IBM TSpaces

Server Administration Guide

Introduction

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



Running a Tspaces Server

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

Special Considerations

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.


Server Configuration file

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:

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.






Access Control Server Setup

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 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.

Using the Admin Application

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.



Starting a Local Server

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:

  TupleSpace.setTSCmdImpl(TSCmd.TSCMD_LOCAL_IMPL);

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.



HTTP Server Interface

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
  

ul>

   http://hostname:8201/debug
  
  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.1
You 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.

Secure Socket (SSL/TLS) support

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:

Planning

Before taking any technical action, the secure protocol (SSL or TLS), the authentication model (server authenticates or mutal authentication), and the trust model must be decided upon. These are issues which vary between organizations and requirements are beyond the scope of this administration guide.

Create key pairs and certificates

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.

Configure the TSpaces server for SSL

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).

Configure the TSpaces client for SSL

In this release, the client is configured by the JSSE system properties only.



Secure Objects support

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

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 waitToTake().

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 true. 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

Temporary Limitations


[ TSpaces home page ]