System Store

Default location of System Store

The default location of IBM® Security Verify Directory Integrator System Store database, in network mode, is your Solution Directory. Therefore, you can have a System Store for each of your Solution Directories.

To share a single System Store across all the Solution Directories, replace $soldir$ value with the actual TDI_install_dir in the com.ibm.di.store.database property of global.properties file and solution.properties file, if already created.

When you create a Solution Directory, update the following properties in the solution.properties file with unique values to avoid conflicts with other Solution Directory settings:

• com.ibm.di.store.port=1527
• api.remote.naming.port=1099
• web.server.port=1098
• System Queue port or Active MQ port in <soldir>/etc/activemq.xml

Note:

The following example describes the effect of specifying the same value for com.ibm.di.store.port property across multiple Solution Directories.

There are two solution directories (soldir1, soldir2) with the same com.ibm.di.store.port values (1527, 1527), and with unique api.remote.naming.port values (1099, 41099).

When you start server on soldir1, the server starts on port 1099 and System Store on port 1527, inside soldir1.

When you start Server on soldir2, the server starts on port 41099 and connects to the System Store, which is already listening on port 1527 inside soldir1.

The remainder of this section discusses the operational aspects of using IBM® Security Verify Directory Integrator, in particular in conjunction with using IBM® Security Verify Directory Integrator to hold your System Store.

Note: With regards to third party RDBMSs, in order to hold encrypted password values you may have to size the fields that hold them quite large. A typical small password might use as much as 178 characters. It depends on both your server's key, and the length of the unencrypted data you try to store (in bytes). Since this is a blocked encoding a larger password might use the same space, or double or triple that amount. Also, the size of the block depends on the server's key. One way to find the size you need, is to store the password (protected) to a file first, and then look at that file to see how many characters were used.

IBM® Security Verify Directory Integrator can run in either of two modes: embedded and networked. By default, as specified in the

global.properties file,

IBM® Security Verify Directory Integrator runs in networked mode.

The System Store used by IBM® Security Verify Directory Integrator releases before V7.0 was IBM® Security Verify Directory Integrator(then called Cloudscape) in embedded mode. There are drawbacks to the way IBM® Security Verify Directory Integrator runs in embedded mode. In embedded mode, IBM® Security Verify Directory Integrator runs as a separate thread within the JVM when required. Startup and shutdown of IBM® Security Verify Directory Integrator is automatic in embedded mode. However, when run this way, this IBM® Security Verify Directory Integrator thread claims exclusive access to the database files. This can become problematic when different JVMs, each with its own IBM® Security Verify Directory Integrator thread, try to access the same System Store.

In embedded mode, these actions cause a new, independent JVM to be started, triggering an access conflict when more than one JVM is active at any given time:

• A command line invocation of the IBM® Security Verify Directory Integrator Server with a config file, causing one or more AssemblyLines to run.
• Startup of the Configuration Editor (GUI)
• Startup of an AssemblyLine from within the Configuration Editor

None of these actions by themselves causes the IBM® Security Verify Directory Integrator thread to start. However, the IBM® Security Verify Directory Integrator thread does start if access to any of the objects in the System Store is required (for example, Objects supported by the System Store such as Delta Tables and the User Property Store).

The solution to the access conflicts as outlined previously is to run IBM® Security Verify Directory Integrator in networked mode, which enables concurrent access to the System Store. Also enable user authentication in IBM® Security Verify Directory Integrator to avoid security concerns in networked mode. To provide security at the database level, IBM® Security Verify Directory Integrator uses the BUILTIN security provider for IBM® Security Verify Directory Integrator. BUILTIN ensures that only valid users are able to access the IBM® Security Verify Directory Integrator database. When you have IBM® Security Verify Directory Integrator configured in networked mode, you can work with multiple instances of IBM® Security Verify Directory Integrator databases booted as System Stores. You can also configure a IBM® Security Verify Directory Integrator instance to work with a specific Configuration file instance.

**Note: Depending on how IBM® Security Verify Directory Integrator was started, instances of IBM® Security Verify Directory Integrator can be left running in networked mode, even after all other IBM® Security Verify Directory Integrator processes have terminated. **

When you set the property derby.drda.startNetworkServer to true (by default, this is the case, in global.properties), the Network Server automatically starts when you start IBM® Security Verify Directory Integrator (in this context, IBM® Security Verify Directory Integrator starts when the embedded driver is loaded).

You may have to terminate IBM® Security Verify Directory Integrator manually, if required.

Cloudscape command-line utility

To make working with the IBM® Security Verify Directory Integrator database more convenient, consider creating a script ("dbserver") with the following line (this example is for Unix/Linux):

export DB_JAR_DIR=jars/3rdparty/IBM
export DB_CLASSPATH=$DB_JAR_DIR/derby.jar:$DB_JAR_DIR/derbyclient.jar:\
$DB_JAR_DIR/derbynet.jar:$DB_JAR_DIR/derbytools.jar
java -classpath $DB_CLASSPATH org.apache.derby.drda.NetworkServerControl "$@"

You may have to join the middle two lines together at the "\ point.

The equivalent dbserver.bat file for Windows would be:

set DB_JAR_DIR=jars/3rdparty/IBM
set DB_CLASSPATH=%DB_JAR_DIR%\derby.jar;%DB_JAR_DIR%\derbyclient.jar;\
%DB_JAR_DIR%\derbynet.jar;%DB_JAR_DIR%\derbytools.jar;
java -classpath %DB_CLASSPATH% org.apache.derby.drda.NetworkServerControl %*

Note: The script must be started from within the IBM® Security Verify Directory Integrator installation path as the working directory, as the following classpath is relative to this directory.

The following example shows the usage of this utility script:

Show all available commands:  ./dbserver  

Start DBServer  ./dbserver start -p 1527     

Stop DBServer   ./dbserver shutdown

The full list of sub-commands that you can specify to the dbserver script, and which are sent to IBM® Security Verify Directory Integrator is:

• start [-h <host>] [-p <portnumber>]: This starts the network server on the port/host specified or on localhost, port 1527 if no host/port is specified and no properties are set to override the defaults. By default Network Server will only listen for connections from the machine on which it is running. Use -h 0.0.0.0 to listen on all interfaces or -h <hostname> to listen on a specific interface on a multiple IP machine.
• shutdown [-h <host>][-p <portnumber>]: This shuts down the network server on the host and port specified or on the local host and port 1527 (default) if no host or port is specified.
• ping [-h <host>] [-p <portnumber>]: This will test whether the Network Server is up.
• sysinfo [-h <host>] [-p <portnumber>]: This prints classpath and version information about the Network Server, the JVM and the Cloudscape server.
• runtimeinfo [-h <host] [-p <portnumber]: This prints extensive debugging information about sessions, threads, prepared statements, and memory usage for the running Network Server.
• logconnections {on | off} [-h <host>] [-p <portnumber>]: This turns logging of connections and disconnections on and off. Connections and disconnections are logged to derby.log. Default is off.
• maxthreads <max> [-h <host>][-p <portnumber>]: This sets the maximum number of threads that can be used for connections. Default 0 (unlimited).
• timeslice <milliseconds> [-h <host>][-p <portnumber>]: This sets the time each session can have using a connection thread before yielding to a waiting session. Default is 0 (no yield).
• trace {on | off} [-s <session id>] [-h <host>] [-p <portnumber>]: This turns drda tracing on or off for the specified session or if no session is specified for all sessions. Default is off .
• tracedirectory <tracedirectory> [-h <host>] [-p <portnumber>]: This changes where new trace files will be placed. For sessions with tracing already turned on, trace files remain in the previous location. Default is clousdcape.system.home .

When running in networked mode, the IBM® Security Verify Directory Integrator database is of course reachable over the network, not only by IBM® Security Verify Directory Integrator instances but also by other applications using the appropriate drivers. The credentials required for such access are defined in the global.properties file, and might have to be tailored for your particular site needs. Pay particular attention to the username and password parameters as these govern integrity and security of the data.

If you often alternate between running IBM® Security Verify Directory Integrator in dedicated mode and in networked mode, consider having two different "prototype" global.properties files on your file system, one each with the correct set of parameters for each of the two modes. Just before starting a server instance, copy in place the appropriate global.properties file, according to your needs. Alternatively, use separate Solution Directories; in a Solution Directory you can have a file called solution.properties, which property values defined in there override the ones defined system-wide in global.properties.

• Property stores
  Password store and User property stores are types of system stores.
• Third-party RDBMS as System Store
  You can configure the System Store to use other multi-user RDBMS systems, as opposed to using the bundled database, Apache Derby.
• Configuring Apache Derby Instances
  You can learn to configure Apache Derby Instances using the information provided here.
• Backing up Apache Derby databases
  You can take a backup of Apache Derby databases by using the method provided here.
• Troubleshooting Apache Derby issues
  This section does not attempt to provide comprehensive troubleshooting guidelines for Derby, but there are a number of symptoms that are observed sometimes in the context of usage of Derby as the underlying database in IBM® Security Verify Directory Integrator.