[ODB1] Chapter 8 - ObjectDB Server

8.1  Running an ObjectDB Server

The ObjectDB server is a pure Java application, packaged in the odbse.jar file. The jar file contains the entire ObjectDB implementation including support for embedded mode. In order to use client server mode, you have to install the odbse.jar file on both the client and the server machines. This section explains how to run the server. More details on server configuration and operation are provided later in this chapter.

The Server as a Java program

You can run the server as a Java program from the command line, as so:

> java -cp <OBJECTDB_HOME>/lib/odbse.jar com.objectdb.Server

Or on Windows:

> java -cp <OBJECTDB_HOME>\lib\odbse.jar com.objectdb.Server

where <OBJECTDB_HOME> represents the installation path of ObjectDB.

If you add odbse.jar to the classpath, you can run the server simply by:

> java com.objectdb.Server

Running the ObjectDB server edition without command line arguments displays a usage message, as shown below:

Usage: java com.objectdb.Server [options] start | stop | restart
options include:
  -conf <path>  :  specify a configuration file explicitly
  -port <port>  :  override configuration TCP port to listen to

To start the server, use the start command:

> java com.objectdb.Server start

Running the ObjectDB server requires the specification of an ObjectDB server configuration file. ObjectDB is shipped with a default server configuration file named default.xml. It is recommended that you use this file as a template for constructing your own specific configuration file. You can use the –conf command line parameter to specify the location of your server configuration file, as shown below:

You can also specify an explicit path to the configuration file:

> java com.objectdb.Server -conf config.xml start

If you name your configuration file server.xml, you do not need to use the –conf command line parameter, because ObjectDB will automatically look for a server/server.xml file if the –conf parameter is not used. Also, if you do not use the –conf parameter and do not create a server.xml file, the ObjectDB server will use the default.xml file as a last resort. Please note, if you edit the default.xml file, it is likely that your modifications will be overwritten when you extract a newer version of the ObjectDB server.

The TPC port on which the server is listening for new connections is specified in the configuration file (as explained in section 8.2), but you can override this setting using the –port command line option to specify another port, as shown below:

> java com.objectdb.Server -port 8888 start

You can also use standard JVM arguments. For instance, you can increase the maximum allowed memory and instruct Java to run in server mode in order to enlarge the cache and improve server performance:

> java -server -Xmx512m com.objectdb.Server start

To stop the server you can use the stop command:

> java com.objectdb.Server stop

To stop the server and then immediately start it again, you can use the restart command:

> java com.objectdb.Server restart

While a server is running in the foreground the command window may be blocked. Therefore, you may need a new command window for the stop and restart commands. The –conf and –port commands can also be used with the stop and restart commands. However, in this context, you must use the same port number that was specified during server startup in order for the stop/restart command to have any effect.

Running the Server on Unix

On Unix you can also use a shell script to run and manage the server. A sample script, server.sh, is located in the bin/sh subdirectory. Before using that script, you have to edit the path to the odbse.jar file, and to the JVM. It is recommended that you do not edit this file directly. Rather, you should copy it to the bin subdirectory and then edit the new copy. In this way, the edited script will not be deleted when extracting the files of a newer ObjectDB version to the same installation directory.

Consult your operating system documentation about running the server in the background (for instance, using the & character at the end of the command line), or starting the server automatically at boot time and stopping it at shutdown time, or on restarting the server periodically (for instance, using crontab).

Running the Server on Windows

On Windows, you can also run the server using the server.exe application, located in the bin directory. For this to work, the original structure of ObjectDB directory must be preserved because server.exe tries to locate and load the odbse.jar and jdo.jar files. By default, server.exe starts the server using the following command:

> java -server -Xms32m -Xmx512m com.objectdb.Server start

When running server.exe, you can specify arguments for the JVM as well as for the server (excluding the stop and the restart server commands). For example:

> server.exe -client -Xmx256m -port 6666 

The specified arguments override conflicting defaults. Therefore, the above run uses the following command:

> java -client -Xms32m -Xmx256m com.objectdb.Server start -port 6666

The server.exe application is represented, when running, by an icon in the Windows Tray. Right click the icon and use the context popup menu to manage the server (stop, restart and start), and to exit the application.

8.2  Single User Server Configuration

As noted before, to run the ObjectDB server a configuration file is required. If a path to the configuration file is not explicitly specified when starting the server, default paths are checked. A valid configuration file is expected to be located on one of these paths. This section discusses a simple configuration file with a single registered user. Notice that a single user configuration may also be used by multi user applications (such as web applications) where the same username and password can be shared by all the database connections.

The following is a simple configuration file with one registered user:

<objectdb.com>

  <server port="6136" reload="30">
    <data path="$objectdb/server/data" />
    <log path="$objectdb/server/log" />
    <connections max="10" user-max="10" timeout="300" />
  </server>
  
  <users>
    <user name="admin" password="admin" address="127.0.0.1">
      <dir path="/">
        <permissions access="+" modify="+" create="+" delete="+" />      
      </dir>
    </user>
  </users>

</objectdb.com>

The server configuration file is in XML format. It always includes an <objectdb.com> root element with two sub elements, <server> and <users>. The <server> sub element specifies general server settings, and the <users> sub element lists all the registered users.

The <server> element

  <server port="6136" reload="30">
    <data path="$objectdb/server/data" />
    <log path="$objectdb/server/log" />
    <connections max="10" user-max="10" timeout="300" />
  </server>

All attributes and sub elements shown in the above <server> element are required.

The port attribute specifies the TPC port on which the server will be listening for new connections. Usually, it should be set to 6136, which is the default port of ObjectDB. If a port other than the default is specified, it also has to be specified by clients in the url connection string (as explained in section 5.1) when connecting to the database.

The reload attribute specifies how often (in seconds) the server checks the configuration file for changes. For instance, a value of 30 (as specified above) indicates a check every 30 seconds. If a change is found, the new configuration is loaded automatically without having to restart the server. To turn off auto reloading specify a value of "0" for the reload attribute. In this case the server has to be restarted manually to apply configuration changes.

The <data> element

The <data> element specifies the data directory containing all the database files that the server is allowed to access and manage. Please note: appropriate file system permissions have to be set on that directory to enable operations by the server process. The location of the data directory is specified in the path attribute using an absolute path. The $objectdb prefix can be used to represent ObjectDB installation directory, as demonstrated in the configuration shown above. The data directory of the ObjectDB server is very similar to the document root directory of a web server. Every file in the data directory or in its subdirectories can be accessed by the server but any file outside this directory cannot be accessed. When connecting to the server, the path specified in the url connection is resolved relative to the data directory. For instance, a url connection string "objectdb://localhost/my/db.odb" refers to a database file db.odb in a subdirectory my of the data directory.

The <log> element

The <log> element specifies a directory to which the server writes its log files. Appropriate file system permissions have to be set on that directory to enable operations by the server process. The location of the log directory is specified in the path attribute using an absolute path. The $objectdb prefix can be used to represent the ObjectDB installation directory, as demonstrated in the configuration shown above.

The <connections> element

The <connections> element specifies restrictions on connections to the server. The max attribute specifies the maximum simultaneous connections allowed by the server. The user-max attribute specifies the maximum simultaneous connections allowed for each user. Because only one registered user is defined in the configuration above, there is no point to specifying different values for the max and user-max attributes (if different values are specified the lowest value is applied). A request for a connection that exceeds the maximum is blocked until some open connection is closed or until a timeout specified on the client side is exceeded. The role of the timeout attribute in the server configuration file is different. It specifies the maximum allowed connection inactivity time (in seconds). If a connection is inactive for more than the specified time the server may close it.

The <users> element

  <users>
    <user name="admin" password="admin" address="127.0.0.1">
      <dir path="/">
        <permissions access="+" modify="+" create="+" delete="+" />      
      </dir>
    </user>
  </users>

The <users> element lists all the users who are allowed to connect to the server.

The <user> element

Every user is represented by a single <user> element. The required name and password attributes specify a username and a password to be used when connecting to the server (see chapter 5). The address attribute is optional. If specified, the user is restricted to connect to the server only from the specified IP address. For instance, the "127.0.0.1" value above (which always represents the local machine) enables connecting to the database server only from the machine on which the server process is running. Multiple IP addresses can also be specified in a comma separated list and using a hyphen (-) to indicate a range. For example, a value "192.18.0.0-192.18.194.255,127.0.0.1" allows connections from any IP address in the range of 192.18.0.0 to 192.18.194.255, as well as from 127.0.0.1.

The <dir> element

Every <user> element should have one or more <dir> sub elements, indicating which paths under the server data directory (as set by the data element) the user is allowed to access. The required path attribute specifies a path to a directory relative to the data directory root. A permission to access a directory always includes a permission to access the whole tree of subdirectories under that directory. Therefore, a path "/", as specified in the configuration above, indicates that the user can access the entire data directory. By using the <dir> element in a multi user configuration, every user can be assigned a private subdirectory containing his or her private database files (as demonstrated in section 8.3).

The <permissions> element

The <dir> element itself grants the user permission to view the directory content (using the Explorer). Additional permissions are granted using the <permissions> sub element and its four attributes. The access permission enables opening database files and the modify permission enables modifying their content. In order to create new subdirectories and new database files a create permission is required. A delete permission is required for deletion of subdirectories and database files. Permissions are granted by "+" values in the proper attributes. Notice that a permission to do an operation in a directory always includes the permission to do the same operation in subdirectories of that directory.

8.3  Multi User Server Configuration

Similar to a web server, which can serve either a single website or multiple websites of one or more users, an ObjectDB server can manage a single database file or multiple database files of any number of users. As long as only one user is involved, a simple configuration as demonstrated in the previous section is sufficient, even for more than just one database file. This section discusses a more complicated case in which multiple users use a shared server to manage different database files. Providing database server support on a shared server could be useful in a shared web hosting environment and in educational settings (such as universities and colleges).

The following configuration file declares three users:

<objectdb.com>

  <server port="6136" update-rate="20">
    <data path="$objectdb/server/data" />
    <log path="$objectdb/server/log" />
    <sessions max="50" user-max="5" timeout="60" />
  </server>
  
  <users>
    <user name="admin" password="admin" address="192.18.97.71">
      <dir path="/">
        <permissions access="+" modify="+" create="+" delete="+" />      
      </dir>
    </user>
    <user name="user1" password="user1">
      <dir path="/home/user1">
        <permissions access="+" modify="+" create="+" delete="+" />      
        <quota subdirs="0" files="3" diskspace="500k" />
      </dir>
    </user>
    <user name="user2" password="user2">
      <dir path="/home/user2">
        <permissions access="+" modify="+" create="+" delete="+" />      
        <quota subdirs="20" files="100" diskspace="20m" />
      </dir>
    </user>
  </users>
  
</objectdb.com>

The administrator user, admin, is authorized to manage database files and subdirectories anywhere in the data directory. For the sake of security, the administrator is only allowed to connect to the server from a specified IP address. The two other users, user1 and user2, can connect to the server from any IP address, but each one is only authorized to access a specific directory, which is dedicated for his or her use.

The <quota> element

A <dir> element can have an optional <quota> sub element, specifying restrictions on the directory content. All three attributes are required. The subdirs attribute specifies how many subdirectories are allowed under that directory (nested subdirectories are also allowed). The files attribute specifies how many database files the directory may contain. Finally, the diskspace attribute specifies maximum disk space for all the files in that directory. A suffix m indicates megabytes and a suffix k indicates kilobytes. Only one <quota> element is permitted per directory. Therefore, if a directory is represented by multiple <dir> elements (in different <user> elements), no more than one of them can have a <quota> sub element.

User Inheritance

User inheritance may simplify management of many similar user accounts:

  <users>
    <user name="admin" password="admin">
      <dir path="/">
        <permissions access="+" modify="+" create="+" delete="+" />      
      </dir>
    </user>
    <user name="$standard" address="12.*.*.*">
      <dir path="/home/$user/">
        <permissions access="+" modify="+" create="+" delete="+" />      
        <quota subdirs="20" files="20" diskspace="5m" />
      </dir>
      <dir path="/examples">
        <permissions access="+" />      
      </dir>
    </user>
    <user name="user1" password="user1" super="$standard" />
    <user name="user2" password="user2" super="$standard" />
  </users>

A <user> element whose user name starts with a $ character, such as $standard in the configuration above, is abstract and does not represent a real user. Connections to the database cannot be obtained using an abstract user, but an abstract <user> element can serve as a base for other ordinary <user> elements, as demonstrated by user1 and user2 above. Only the name of an abstract <user> element can be specified in the optional super attribute, and that abstract user must be declared in the configuration file before its derived users. One abstract user can inherit from another abstract user. When using the super attribute, all the attributes and the sub elements of the specified abstract user are inherited except the name attribute. The $user variable (in the path attribute of $standard) is evaluated, when inherited, to the name of the inheriting user. Therefore, user1 gets access to directory /home/user1 and user2 to directory /home/user2.

Inherited attributes can be overridden, as demonstrated by user3:

    <user name="user3" password="user3" super="$standard" address="">
      <dir path="/home/$user/">
        <permissions delete="-" />      
        <quota subdirs="20" databases="20" diskspace="20m" />
      </dir>
    </user>

Three attributes are changed. The empty address attribute eliminates the inherited address restriction. The minus value in the delete attribute removes an inherited permission, and a new value in the diskspace attribute increases the disk quota for the user.

8.4  Using Secure Socket Layer (SSL)

ObjectDB supports encryption of client server communications using the Secure Sockets Layer (SSL) protocol. Encryption is especially important when the communication between the client and the server is over an unsecured network, such as the Internet. There are several implementations of SSL available for Java. ObjectDB uses the JSSE implementation, which is integrated in J2SDK as a standard package since version 1.4.

Keystore and Trustore

To use SSL you have to generate at least two files:

• A Keystore file that functions as a unique signature of your server. This file contains general details (such as a company name), an RSA private key and its corresponding public key (the SSL protocol is based on the RSA algorithm).
• A Trustore file that functions as a certificate that enables the client to validate the server signature. This file is generated from the Keystore file, by omitting the private key (it still contains the general information and the public key).

You can generate these files using the keytool utility (located in the J2SDK bin directory).

Using these Keystore and Trustore files, a client can verify during SSL handshaking that it is connected to the real server, and not to another server in the way that is pretending to be the real server (what is known as "a man in the middle attack"). The server, on the other hand, might be less selective and allow connections from any machine, as long as valid username and password are provided. If an authentication of the client machine by the server is also required, a Keystore file (which might be different from the server Keystore) has to be installed on the client machine, and its corresponding Trustore file has to be installed on the server machine.

Setting the Server to use SSL

To setup an ObjectDB server for using SSL, you have to put an <ssl> element with a <keystore> sub element inside the <server> element. The Keystore file and its password are specified in the two required attributes of the <keystore> element, where $objectdb represents the ObjectDB installation directory, as shown below:

  <server port="6136">
      :
    <ssl>
      <keystore path="$objectdb/server/keystore" password="ksp-pwd" />
    </ssl>
      :
  </server>

When client authentication is also required, the <ssl> element should also contain a <truststore> sub element that serves as a certification of the client signature:

  <server port="6136">
      :
    <ssl>
      <keystore path="$objectdb/server/keystore" password="ksp-pwd" />
      <truststore path="$objectdb/server/truststore" password="ts-pwd" />
    </ssl>
      :
  </server>

Setting the Client to use SSL

To access an ObjectDB server that is set to use SSL, a Truststore file for authentication of the server has to be provided. If the PersistenceManagerFactory is initialized using a property file, two lines should be added to specify the path of the Truststore file and its password:

  com.objectdb.ssl.truststore.path=$objectdb/lib/truststore
  com.objectdb.ssl.truststore.password=ts-pwd

Alternatively, the PersistenceManagerFactory's properties can be set at runtime:

  Properties properties = new Properties();
    :  
    :  
  properties.setProperty(
    "com.objectdb.ssl.truststore.path", "$objectdb/lib/truststore");
  properties.setProperty(
    "com.objectdb.ssl.truststore.password", "ts-pwd");

  PersistenceManagerFactory pmf =
    JDOHelper.getPersistenceManagerFactory(properties);

If client authentication is also required, the client's Keystore can also be specified in a property file:

  com.objectdb.ssl.keystore.path=$objectdb/lib/keystore
  com.objectdb.ssl.keystore.password=ks-pwd

or at runtime:

  Properties properties = new Properties();
    :  
    :  
  properties.setProperty(
    "com.objectdb.ssl.keystore.path", "$objectdb/lib/keystore");
  properties.setProperty(
    "com.objectdb.ssl.keystore.password", "ks-pwd");

Finally, to access the server using SSL, the connection URL should start with objectdbs:// instead of with objectdb://. Otherwise, the Keystore and the Truststore properties are ignored and an attempt to establish an ordinary non secured connection is performed. Of course, this attempt is expected to fail if the server is set to use SSL.