The TSpaces Server Administration Guide will describe the how to set and run the Tspaces server. There is also a Client Programmer's Guide that will cover Tspaces client programming. There are some topics that bridge the gap between client and server and could be placed in either Guide. In most cases, if these involve Java programming, they will be in the Client programmers Guide and this guide will simply refer to it.
This guide applies to TSpaces Version 3.1.0
In order to actually run your TSpaces client, you need to have an available TSpaces server. During the testing phase, you will probably run your own copy of the server on your local machine and refer to it with the server name of "localhost". The sample programs come with a shell script for starting a TSpaces server and you may be able to use that script to start your server. You can refer to the instruction for running the sample programs that come with TSpaces for instructions and shell scripts for starting a local server.
If you write your own script or invoke it directly, you have to ensure that the CLASSPATH is set correctly so that the jar files that contain the Server code is available. Also you need to have the XML Parser jar library if you want to use the distributed XML support. If you use the SSL connection then you will have to also specify the jar files that are required for SSL. See the SSL instructions. Let's assume that this is a WinNT system and you installed TSpaces in the c:\java directory. The following should be sufficient to run the TSpaces server.
set CLASSPATH=c:\java\tspaces\classes; c:\java\tspaces\lib\tspaces.jar; c:\java\tspaces\lib\log.jar; c:\java\tspaces\lib\xerces.jar java com.ibm.tspaces.server.TSServer [options]
There are a number of options that can be specified when starting the server.
Options: [-a password] Password for sysadmin userid [-b] Boot without restoring TupleSpaces [-B] Boot without restoring TupleSpaces or User/Group status [-c ConfigurationFile] specify location of the Configuration file [-d checkpointDirectory] specify a checkpoint directory [-p port#] specify a port number [default 8200] [-i interval] specify a checkpoint interval [-D] Turn on Debug output [-A] Allow Admin actions via http [-S] Start the HTTP debug interface Note that the spaces after the option flags are needed
All of the options can be specified by the Configuration file. If the -c option is not specified, it will look for a "tspaces.cfg" in the current directory and if still not found, then it will run with a set of hard-coded defaults.
A sample tspaces.cfg file is distributed with the system that contains comments about the options. For more details see Server Configuration file
An important factor to keep in mind is the requirement that the Server have access to the class definitions for any objects that are written to or read from the server. The fact that the server has access to the class definitions for the objects that are contained in the tuples, gives TSpaces the ability to do selection on any fields of the tuple. But this also can be a problem area.
So you should ensure that the CLASSPATH that is used when starting the server, includes the directory where the client class files are placed (usually the current directory at compile time or specified via "java -d classdir").
Also, once the class file is loaded by the server, that version continues to be used. So if you correct a bug in the client class and recompile, you may need to restart the server. Of course, use of the Serialver option will make this unnecessary. See the User Objects Example for an example of this.
Another consideration with the above, is that when you allow user objects to be sent to the server, then certain methods of those objects will be invoked in the server Virtual Machine. This may be a security problem and/or a reliability problem. In general, if you have a TSpaces server with sensitive data in it and/or reliability is important, you probably want to have tight control over the placement of client Java class files into the Server library. The earlier section on User Objects describes how one can bypass these problems with Object PreSerialization.
You also have the option of running TSpaces with it's own class loader so that it will provide a secure environment for Objects that are submitted by the client. Refer to the Secure Qbjects section for futher informantion.
The operation of the Tspaces server and the selection of many options is controlled by the configuration file. The default configuration file used is tspaces.cfg which is found in the current directory. A sample tspaces.cfg file is distributed with Tspaces and can be used and modified by the installation. A different configuration file can be specified with the -c filename option when starting Tspaces.
A configuration file has the following format:
# # comment lines start with # # [section1] keyword1 = value1 keyword2 = true keyword3 = 5
The following are the valid section names:
[Server] Base Server options
[HTTPServer] Options for built-in HTTP Server.
[AccessControl] Access control information
[FileStore] FileStore options
[Runner] Secure Objects options
The use of these sections is described in subsequent chapters.
Within each of the above sections are keyword = value statements and posibly other sections. The distributed sample file contains each of the valid statements (sometimes shown as a comment) The keywords in each statement must be spelled as shown in the sample file and are case sensitive. The values can be a string, a number, or the boolean true or false.
The TSpaces server supports authentication of the Clients and Access Control List(ACL) protection of each Space.
Note! Tspace is distributed with the Access Control checking turned off. If you want to enable it, you must update the tspaces.cfg file.
[AccessControl] CheckPermissions = true
If this is not done then the userid and password will be authenticated but no access checking will be done.
The TSpaces clients identify themselves by specifying a userid and password on the TupleSpace constructor call. For an example of this, see Access Support example
The server maintains a Hashtable of Userids and password keys. These password keys are the passwords from the user that have been turned into a digest by the SHA algorithm that is part of java.security and then the results turned into a BigInteger. The user/password combinations can either be read from the config file (not recommended) or entered via the Admin application. The Hashtable is currently written in a tuple to the Admin space and also to a file for backup in case the server does not have checkpointing or is rebooted.
The client code in TupleSpace takes the password supplied on the constructor and turns it into a BigInteger and then sends the BigInteger over the socket where it is compared to the BigInteger maintained by the server. So since the SHA digest is non-reversable, anyone seeing the socket data or looking at the file on disk, would not be able to determine the original password.
The above enables the client to securely tell the Server who they are. If not specified by the client, then the userid of "anonymous" is used.
Although currently the Userid and group structure is managed by TSpaces, the design is such that in the future, the User/Group configuration could be interfaced to the installation's User/Group setup for the Operating System where the T Space server is running.
The java.security interfaces are
Principal: represents a user or group. It has a name and not much else.
Group: a subclass of Principal. It has members that are other principals
AclEntry: represents the Permissions for a Principal. Can be negative or positive.
Acl: represents the Access Control list for some resource (i.e. a TupleSpace) It has a name and contains a set of ACLEntry objects. It has methods for checking that a given Principal has the specified Permissions.
Permission: Represents a Permission - contains an equals() method to test it. There are both general Permissions of Read, Write, Owner, and Admin. All current TSpaces commands can be given permissions in combinations of these permissions. In addition, one can have specific permissions that only apply to a single command. So, for example, one could implement a command named "SpecialCmd" and only invoke it if the caller has "SpecialCmd" permission for that Space.
The initial hierarchy group and user hierarchy is built from the Server Configuration file. the first time that the server is started or when the "-B" operand is specified on startup. If you look at the tspaces.cfg file that is distributed with TSpaces, you will see that it sets up a very basic hierarchy with the top level group users that contains a subgroup of AdminGroup and the users sysadmin, guest and anonymous. The comments in the file will hopefully show how one could enhance this. Based on the configuration file, a TsACLDBase object is built that contains a linked list that represents the User/Group hierarchy and this object is written to the Admin Space on the server.
Also a DefaultACL is built based on the configuration file. The default ACL is the ACL used for any Space that is created without specifying an ACL. If there is no config file, then we build an ACL that gives Read,write authority to group Users and read,write,admin authority to sysadmin. The CreateAcl is also built based on the configuration file. It is used to control who has permission to create a new space. The default is to grant all users, including anonymous, the permission to create Spaces.
The default ACLs and any ACLs that are created when a new Space is created are written and maintained in the Admin Space.
There is a very basic Admin application distributed with the system that allows the "Administration user" to manipulate both the User/Group hierarchy and the ACL entries that protect the individual Spaces. To invoke the application on a Windows system, issue the following commands:
cd your_tspaces_directory bin\admin.bat [host] [port] [userid] [password]
It is not as easy to use this application as we would have liked. One hint is that it does use popup menus, so click the mouse button assigned to "popup" on a user or group entry. That will bring up the menu options to add or delete users or groups. Clicking it on an Acl permission entry will allow you to modify or add new AclEntry objects.
The user/group hierarchy information and the user/password information is stored in the TSpaces Admin space. But because you may want to run the server in non Persistent mode, it is also backed up into files so you will not lose your user/group information when you restart even if you use the -b option. These backup files (acldb.ser and password.ser) are stored in the current directory. If you want to completely start from scratch and get the initial ACL information from the configuration file then you should specify the -B flag on the command line.
Sometimes it is useful to have the client actually run the server as a thread inside that same Java Virtual Machine as the client. It lets the client control the starting and stopping of the server and may give somewhat significant performance enhancements. For example, it might be useful when you have many clients on remote systems providing input to a main central server where they are processed by a local client. In this case you want the local client to be able to access TSpaces as fast as possible.
A new interface between the client and the Server is available for the case where the client and the server are running on the same machine and under the same Java Virtual Machine. In this case, the client calls are directly implemented by the Server without the TCPIP socket overhead. Under certain circumstances, it can also reduce the overhead of Object serialization.
To do this the client must start the server with the following code:
TSServer ts = new TSServer(); Thread serverThread = new Thread( ts, "TSServer" ); serverThread.start();
The above TSServer default constructor will let all of the command line options have the default values, including having the default tspaces.cfg file in the current directory. You can refer to the JavaDoc API for TSServer to see how you would specify other options for the server.
Now to use the interface that avoids all TCPIP socket overhead, you add the following line to your client code:
The rest of your code is unchanged. It should be noted that this special interface will be used only by this client. Any other clients on another system or even on this system but under a different JVM will continue to use the socket interface to communicate with this server.
The local interface can avoid much of the overhead of Object Serialization under some circumstances. It important that the objects stored in the server be independent from the objects that the client is manipulating. If the client and the server are both running under the same JVM, then this means that when an object is transfered from the client to the server (or viceversa) that the server gets a copy of the object. If the Tuple consists of only String and Number fields, then this copy is done by a call to the Tuple.clone method which is relatively efficient. Otherwise, the copy is made by calling the same Object Serialization routines that are used when the client and server talk over a socket interface.
The bottom line is: if you have an application where the Tuples consist of only String and Number fields and you have a client that needs high performance and can run on the same system as the TSpaces server, then using this special local interface may be worthwhile. This special local interface is also useful if you want to have the local client monitor the execution of the TSpaces server.
The TSpaces Server contains a built-in HTTP Server that can be accessed via a Web Browser interface This interface can be used to determine the status of TSpaces, obtain debug information, or even download HTML and Java Applets. You need to set the following Configuration options:
[HTTPServer] HTTPServerSupport = true HttpPort = 8201
To access the HTTP server to obtain status or debug information you would use the following URL:
To access applets or HTML files, place the files into a directory on the server and set the ClassesDirectory Configuration option.
For Example: # Specify the directory where downloadable class files are kept [HTTPServer] ClassesDirectory = c:\tspaces\
You can also restrict the HTTP interface to specific client systems. The [HTTPClients] section can be used to restrict the use of the HTTP interface to specific client addresses. The system is distributed so that use of the HTTP interface is restricted to the local server with the following statements
[HTTPClients] localhost 127.0.0.1You can remove thse statements to enable global use of the HTTP interface or add additional system names to allow it to be used only by users on that system.
TSpaces' Secure Socket support is based entirely on the Java Secure Socket Extension (JSSE) available in Java Standard Edition 1.4 and higher. This section assumes familiarity with JSSE concepts such keystores and truststores as well as secure socket concepts such as SSLv2, SSLv3 and TLS. For background information on JSSE, we recommend the excellent JSSE Reference Guide for the J2SDK, v 1.4.
The main steps in deploying TSpaces over SSL are:
TSpaces does not provide tools for the generation and management of keys and certificates. Rather, key material is produced and managed using tools specific to the task as chosen by an organization. Examples of such tools are Java's keytool and IBM's iKeyMan. The TSpaces server will require at least a keystore, while a truststore for the TSpaces clients is required. If client authentication will be used, a trustore is also required on the server while each TSpaces client will require its own keystore.
Secure sockets are enabled by setting the
SSLSupport property in the
[Server] section of
the tspaces configuration file as shown below:
[Server] ... #------------------------------------------------------------ # ***** Secure Sockets (JSEE) Options #------------------------------------------------------------ SSLSupport = true SSLPort = 8202
Note also how the lisetning port for the secure socket is also specified. In this example, it is simply set to the default TSpaces SSL port.
Once enabled, the required JSSE input identifying the location of keystores and their respective passwords must be configured. As mentioned, this can be done at the JVM level using the system properties defined in the JSSE reference Manual.
Alternatively, the JSSE parameters can also be specified in the tspaces configuration file as shown below:
[Server] ... #------------------------------------------------------------ # ***** Secure Sockets (JSEE) Options #------------------------------------------------------------ SSLSupport = true SSLPort = 8202 # Specify the protocl. Valid entrie are: "TLS" (default) and "SSL". Default is "SSL" sslProtocol = SSL # the keystore containing the key pair and certificate used by the tspaces server keyStore=/opt/myapp/etc/tspaces.keystore keyStorePassword=myPassword # specify the keystore type - default is JKS #keyStoreType=JKS # define truststore containing trusted clients - used only for mutual authentication #trustStore=/opt/myapp/etc/tspaces.truststore #trustStorePassword=myPassword
In the example above, a keystore without truststore is specified, implying SSL v2 (i.e., server authenticates to client).
In this release, the client is configured by the JSSE system properties only.
When you allow user objects to be sent to the server, then certain methods of those objects will be invoked in the server Virtual Machine. This may be a security problem and/or a reliability problem.
For example, if a client uses SubclassableTuple then their subclass can contain a matches() method that is invoked for every comparison with existing Tuples in the space. If this matches() is not controlled it could do damage to the server. For example, a System.exit() call would terminate the server. Another example might be a spy class where the matches() method could read other files on the server system.
We have provided an alternative way of running the TSpaces server where it will run with its own class loader and you can specify what authorizations the client classes will have.
The TSRunner class handles the invoking of TSServer under the control of a classLoader and Security manager. It will create an instance of TSClassLoader It will use the default or overridden location of the tspaces.cfg file so that it can get the pathname for the TSpaces class or jar file and pass that information to the class loader. and then invoke the "main()" method for TSServer using this class loader. It will scan the arguments passed via the command line and pass those unmodified to the main() method.
In order to work correctly, it requires that it be invoked with the following command line (or something equivalent)
set classpath=.\tsrunner.jar java -Djava.security.manager - -Djava.security.policy=file:./.java.policy - TSRunner -c .\tspaces.cfg where: tsrunner.jar contains only: com.ibm.tspace.tsrunner.TSRunner.class com.ibm.tspaces.tsrunner.TSClassLoader.class com.ibm.tspaces.tsrunner.Configuration.class com.ibm.tspaces.tsrunner.ConfigException.class where: tspaces.cfg has a tsrunner stanza that defines the classpath for TSServer. where: .java.policy defines the permissions that are allowed for each of the directories or jar files in the classpath.
The TSpaces distribution contains examples of both a configuration file ( tsrunner.cfg ) and a policy file (tsrunner.policy). These MUST be edited to match the installation environment.
TCP Keep-Alive is described in RFC 1122 and is a means to verify the liveness of a TCP connection by periodically sending ACK packets. Keep alive can help detect lost TCP connections and thereby lead to release of server resources. On the client side, early detection of lost server connections can facilitate connection recovery.
As an example, consider a client performing
TupleSpace.waitToTake() when the server
crashes or is physically disconnected from the network. The client-side IP stack will not necessarily receive a
packet indicating the lost connection, but could instead continue to perceive the connection as "live".
When the server recovers and is available again, the client will not reconnect but remain waiting
hopelessly on the old invalid connection.
To perceive such broken connections, the client would have to periodically
initiate an action involving the transmission of a packet, actively provoking the detection
of the lost socket half. Means to accomplish this at the TSpaces level involve periodically calling
TupleSpace.status() or "polling" the server by using
TupleSpace.waitToTake(Serializable template, long timeout)
with a wait time out instead of the open-ended version of
As an alternative to probing at the TSpaces level, TCP Keep-Alive takes place at the transport level in the IP stack impementation. If specified, ACK's are periodically sent over idle socket connections. When the remote host fails to respond to the ACK, the loss of connection is detected. Keep-Alives can make sense where timely detection of lost connections are required and where the number of client connections to a server are relatively small. Note that TCP Keep-Alive only works for the side that initiates them. TSpaces supports enabling of TCP Keep-Alive on both the server and the client side by calling java.net.Socket.setKeepAlive(true) when Keep-Alive is enabled.
On the server side, TCP Keep-Alive is activated by setting the
keepAlive property in
the tspaces configuration file to
If this property is not specified, the default is "false" and TCP Keep-Alive is not be employed.
The configuration file snippet below shows TCP keep alive enabled:
[Server] #------------------------------------------------------------ # Sockets Options #------------------------------------------------------------ tcpKeepAlive = true
On the client side, keep alive is set programmatically. Programmatically setting TupleSpace options is described in the TSpaces Client Programmer's Guide under the section, Configuration Options
[ TSpaces home page ]