Usage Information for the DirXML™ Remote Loader for Unix

Contents

Overview

 The DirXML Remote Loader executable is used to host a DirXML application shim or to control another instance of the remote loader that is hosting a DirXML application shim.

Communication between a shim-hosting instance and the command line instance being used to control the shim-hosting instance is through a TCP/IP port. This is referred to as the command port. Another TCP/IP port is used for communication with the DirXML engine, via the remote interface shim.

The remote loader will only load the DirXML application shim when the remote loader is in communication with the remote interface shim on the DirXML server. This means, for example, that the application shim will be shut down if the remote loader loses communication with the DirXML server.

The DirXML Remote Loader is capable of hosting DirXML application shims contained in .so files and DirXML application shims contained in .jar files.

Command Line Options and Parameters

 Command line options are used for three purposes with the DirXML remote loader. Certain command line options specify the parameters for a remote loader instance that is hosting a DirXML application shim. These options include specifying the shim module or class, the connection parameters used for communicating with the remote interface shim on the DirXML server, trace level, etc.

Other command line options are used to send commands to a remote loader instance that is hosting a DirXML application shim. These options include opening and closing the trace window and unloading the remote loader.

Still other options are used for certain configuration purposes. These options include setting the passwords and installing and uninstalling a remote loader instance as a Win32 service.

Option

Secondary Name

Parameter

Description
-class -cl Java class name Specifies the Java class name of the DirXML application shim that is to be hosted. The class option and the module option are mutually exclusive.

Example:

-class com.novell.nds.dirxml.driver.ldap.LDAPDriverShim

-cl com.novell.nds.dirxml.driver.ldap.LDAPDriverShim

-commandport -cp port number Specify the TCP/IP port that the remote loader instance will use for control purposes.

If the remote loader instance is hosting an application shim the command port is the port on which another remote loader instance will communicate with the instance hosting the shim.

If the remote loader instance is sending a command to an instance that is hosting an application shim the command port is the port on which the hosting instance is listening.

If not specified the default command port is 8000.

Multiple instances of the remote loader can be run on the same server hosting different driver instances by specifying different connection ports and command ports.

Example:

-commandport 8001

-cp 8001

-config   filename Specifies a configuration file. The configuration file can contain any command line options except config. Options specified on the command line override options specified in the configuration file.

Example:

-config config.txt

-connection -conn connection configuration string The connection configuration string specifies the connection parameters for the connection to the DirXML server running the DirXML remote interface shim.

The default connection method for the remote loader is TCP/IP using SSL. The default TCP/IP port for this connection is 8090.

Multiple instances of the remote loader can be run on the same server hosting different driver instances by specifying different connection ports and command ports.

Example:

-connection "port=8091 rootfile=server1.pem"

-conn "port=8091 rootfile=server1.pem"

-datadir -dd data directory Sets the directory for data files used by the Remote Loader. This option causes the rdxml process to change its current directory to the specified directory. This means trace files and other files that do not have an explicit path specified will be created in the specified data directory.

Example:

-datadir /var/opt/novell/dirxml/rdxml/data

-dd /var/opt/novell/dirxml/rdxml/data

-description -desc short description Specify a short description string that will be used for Nsure Audit logging.

Example:

-description SAP

-desc SAP

-help -? None Display this help.

Example:

-help

-?

-java -j None Specify that the passwords are to be set for a Java shim instance. This option is only useful in conjunction with the setpasswords option. If -class is specified with -setpasswords this option is not necessary.

Example:

-java

-j

-javadebugport -jdp port number Specify that the remote loader instance is to enable Java debugging on the specified port. This is useful for developers of DirXML application shims.

Example:

-javadebugport 8080

-jdp 8080

-module -m modulename Specifies the module containing the DirXML application shim that is to be hosted. The module option and the class option are mutually exclusive.

Example:

-module /usr/lib/nds-modules/libcskeldrv.so.0.0.0

-m /usr/lib/nds-modules/libcskeldrv.so.0.0.0

-password -p password Specify the password for command authentication. This password must be the same as the first password specified with setpasswords for the loader instance being commanded.

If a command option (unload, tracechange, etc.) is specified and the password option is not specified the user will be prompted to enter the password for the loader that is the target of the command.

Example:

-password novell4

-p novell4

-piddir -pd pidfile directory Sets the directory for the process id file (pidfile) used by the Remote Loader process. The pidfile exists primarily for use by SysV-style init scripts. If not specified, the pidfile directory defaults to /var/run, or, if the Remote Loader is run by a user without sufficient rights to open the pidfile for reading and writing in /var/run, then the current directory is used. (See also -datadir).

Example:

-piddir /var/opt/novell/dirxml/rdxml/data

-pd /var/opt/novell/dirxml/rdxml/data

-setpasswords -sp None, or password password Specify the password for the remote loader instance and the password of the DirXML-Driver object of the remote interface shim with which the remote loader will communicate.

The first password in the optional arguments is the password for the remote loader. The second password in the optional arguments is the password for the DirXML-Driver object associated with the remote interface shim on the DirXML server.

Either no password or both passwords must be specified. If no password is specified the remote loader will prompt for the passwords.

This is a configuration option. Using this option configures the remote loader instance with the passwords specified but does not load a DirXML application shim or communicate with another loader instance.

Example:

-setpasswords novell4 fishlips3

-sp novell4 fishlips3

-trace -t integer Specify the trace level. This is only used when hosting an application shim.

Trace levels correspond to those used on the DirXML server.

Example:

-trace 3

-t 3

-tracechange -tc integer Command a remote loader instance that is hosting an application shim to change its trace level.

Trace levels correspond to those used on the DirXML server.

Example:

-tracechange 1

-tc 1

-tracefile -tf filename Specify a file to which to write trace messages. Trace messages will be written to the file if the trace level is greater than zero. Trace messages will be written to the file even if the trace window is not open.

Example:

-tracefile /tmp/trace.txt

-tf /tmp/trace.txt

-tracefilechange -tfc None, or filename Command a remote loader instance that is hosting an application shim to start using a trace file, or to close one already in use and use a new one.

Using the no-argument version of this option will cause the hosting instance to close any trace file being used.

Example:

-tracefilechange /tmp/newtrace.txt

-tfc /tmp/newtrace.txt

-tracefilemax -tfm size Specify the approximate maximum size that trace file data may occupy on disk. If this option is specified there will be a trace file with the name specified using the tracefile option and up to 9 additional "roll-over" files. The roll-over files are named using the base of the main trace filename plus "_n" where n is 1 through 9.

The size parameter is the number of bytes, and may be specified using the suffixes 'K', 'M', or 'G' for kilobytes, megabytes, or gigabytes, respectively.

Note that if the trace file data is larger than the specified maximum when the remote loader is started then the trace file data will remain larger than the specified maximum until roll-over is completed through all 10 files.

Example:

-tracefilemax 25M

-tfm 25M

-unload -u None Unload the remote loader instance. If the remote loader is running as a Win32 Service this will stop the service.

Example:

-unload

-u

Connection Parameters

 Connection parameters are specified using the connection command line option.

The DirXML Remote loader allows for custom connection methods between the remote loader and the remote interface shim that is hosted on the DirXML server. The default connection method is TCP/IP using SSL and is what is discussed in this section. Refer to the documentation that comes with the custom connection module for information regarding what is expected and allowed in the connection string for a custom connection module.

The remote loader opens a server socket and listens for connections from the remote interface shim. When the remote interface shim connects to the remote loader an SSL handshake is performed to establish a secure channel. Once a secure channel has been established the remote interface shim authenticates to the remote loader. If the authentication of the remote interface shim succeeds then the remote loader authenticates to the remote interface shim. Only when both sides are satisfied that they are communicating with an authorized entity does synchronization traffic occur.

The following section details the argument names and parameters for the TCP/IP connection method.

TCP/IP with SSL Connection Parameters

Option

Parameter

Description
address IP address Specifies that the remote loader will listen on a particular local IP address. This is useful if the server hosting the remote loader has multiple IP addresses and the remote loader must listen on only one of the addresses. If address is not specified the remote loader will listen on all local IP addresses.

Example:

address=137.65.134.83

keystore keystore Used only for DirXML application shims contained in .jar files.

Specifies the filename of the Java keystore that contains the trusted root certificate of the issuer of the certificate used by the remote interface shim. This will typically be the Certificate Authority of the eDirectory tree that is hosting the remote interface shim.

Example:

keystore=my.keystore

port decimal port number Specifies the TCP/IP port on which the remote loader will listen for connections from the remote interface shim.

Example:

port=8090

rootfile filename Used only for DirXML application shims contained in .so files.

Specifies the file containing the trusted root certificate of the issuer of the certificate used by the remote interface shim. This will typically be the Certificate Authority of the eDirectory tree that is hosting the remote interface shim. The certificate file must be in Base 64 format (PEM).

Example:

rootfile=trusted_root.pem

storepass storepass Used only for DirXML application shims contained in .jar files.

Specifies the password for the Java keystore specified by the keystore parameter.

Example:

storepass=mypassword

Configuring a DirXML Application Shim for the Remote Loader

 There are a few additional steps involved in setting up a DirXML application shim for use with the remote loader in addition to the normal procedure for setting up a DirXML application shim.

Using iManager (with the DirXML plug-ins):

Install a driver configuration for the application shim

 This is performed in the usual fashion using iManager (Click DirXML Management > Overview.)

Configure the driver for use with the remote loader
  1. From the Overview, click the DirXML Driver object.
  2. Select the Driver Configuration tab. Change the radio button from "Java" or "Native" to "Connect to Remote Loader".
  3. Enter a password in the Driver Object field. This password will be used by the remote loader to authenticate itself to the remote interface shim.
  4. Enter the password for the remote loader. This password is used by the remote interface shim to authenticate itself to the remote loader.
  5. Enter the communications parameters for the remote loader. This is a series of "name=value" pairs. The following are supported:

    Option

    Parameter

    Description
    hostname host name or ip address Specifies the address or name of the machine on which the remote loader will run.

    Example:

    hostname=192.168.0.1

    kmo Key Name Specifies the Key Name of the Key Material Object containing the keys and certificate used for SSL.

    Example:

    kmo='remote driver cert'

    port TCP port number Specifies the port on which the remote loader will accept connections from the remote interface shim.

    Example:

    port=8090


    An example of communication parameters is: hostname=192.168.0.1 port=8090 kmo=remotecert

Install the remote loader on the remote machine
  1. Using the DirXML 2.0 CD, install the remote loader on the target machine.
  2. Copy the .so file or the .jar file containing the DirXML application shim onto the target machine.

Configure the remote loader
  1. Create a configuration file specifying the shim module or class name, the command port, connection string, and any desired trace level. For example, create a file named config.txt with the following lines:

    -commandport 8000
    -connection "port=8090 rootfile=/dirxmlremote/root.pem"
    -module $DXML_HOME/dirxmlremote/libcskeldrv.so.0.0.0
    -trace 3
  2. Set the loader and driver object passwords using the -setpasswords option. For example:

    dirxml_remote -config config.txt -setpasswords rumple1 stiltskin2

Run the remote loader
  1. Start the remote loader. For example:

    dirxml_remote -config config.txt
  2. Start the remote interface shim using iManager.
  3. Confirm that the remote loader is operating properly.
  4. Stop the remote loader. For example:

    dirxml_remote -config config.txt -u
  5. Install the remote loader as a Win32 service. For example:

    dirxml_remote -config config.txt -service install

Copyright Information

 This software is Copyright © 2001 Novell Inc. (http://www.novell.com) All rights reserved.

This software is pre-release. No promise of future functionality or support is implied. Novell assumes no liability for any data loss or damage resulting from the use of this software.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/) Copyright (c) 1998-2000 The OpenSSL Project. All rights reserved.

This product includes software developed by Eric Young. Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved.

This product includes code licensed from RSA Data Security.