3.4 Configuring the Remote Loader

The Remote Loader can host the Identity Manager application shims contained in .dll, .so, or .jar files. The Java Remote Loader hosts only Java driver shims. It won’t load or host a native (C++) driver shim.

You can configure the driver on Windows through a graphical utility called the Remote Loader Console utility or from the command line.

3.4.1 Configuring the Remote Loader on Windows

The Remote Loader Console utility enables you to manage all Identity Manager drivers running as a Remote Loader on the Windows server. The utility is installed during the installation of Identity Manager.

If you are upgrading to Identity Manager, the Console detects and imports existing instances of the Remote Loader. (To be automatically imported, driver configurations must be stored in the remote loader directory, typically c:\novell\remoteloader.) You can then use the Console to manage the remote drivers.

  1. Double-click the Remote Loader Console icon on the desktop to launch the Remote Loader Console.

    Remote Loader Console icon

    The Remote Loader Console allows you to start, stop, add, remove, and edit each instance of a Remote Loader.

  2. Click Add to add a Remote Loader instance of your driver on this server.

    Remote Loader Console
  3. Specify the Remote Driver Configuration parameters.

    Remote Driver Configuration parameters
    1. Specify a description to identify the Remote Loader instance.

    2. Browse to and select the appropriate shim for your driver.

    3. Specify a name for the configuration file.

      The Remote Loader Console places configuration parameters into this text file and uses those parameters when it runs.

  4. Specify the Communication parameters.

    Communication parameters
    1. Specify the IP address where the Remote Loader listens for connections from the Metadirectory server.

    2. Specify the TCP port on which the Remote Loader listens for connections from the Metadirectory server.

      The default TCP/IP port for this connection is 8090. With each new instance you create, the default port number automatically increases by one.

    3. Specify the TCP port number where a Remote Loader listens for commands such as Stop and Change Trace Level.

      Each instance of the Remote Loader that runs on a particular computer must have a different command port number. The default command port is 8000. With each new instance you create, the default port number automatically increases by one.

      NOTE:By specifying different connection ports and command ports, you can run multiple instances of the Remote Loader on the same server hosting different driver instances.

  5. Specify the Remote Loader Password.

    Remote Loader Password

    This password is used to control access to a Remote Loader instance for a driver. It must be the same case-sensitive password specified in the Enter the Remote Loader Password field on the Identity Manager driver configuration page. It is important that this password be difficult to guess and be different from the driver object password.

  6. Specify the Driver Object Password.

    Driver Object Password

    The Remote Loader uses this password to authenticate to the Metadirectory server. It must be the same case-sensitive password specified in the Driver Object Password field on the Identity Manager driver configuration page. It is important that this password be difficult to guess and be different from the Remote Loader password.

  7. Specify the Secure Socket Link parameters.

    Secure Socket Link parameters
    1. Select Use an SSL connect, if you are encrypting the transfer of data between the Remote Loader and the Metadirectory server.

    2. Browse to and select a trusted root file.

      This is the exported self-signed certificate from the eDirectory tree’s Organization Certificate Authority. See Section 3.2.2, Exporting a Self-Signed Certificate.

  8. Specify Trace File parameters.

    Trace File parameters
    1. Specify a trace level greater than zero to display a trace window that contains informational messages from both the Remote Loader and the driver.

      The most common setting is trace level 3. If the trace level is set to 0, the trace window is not displayed.

    2. Specify a trace filename where trace messages are written.

      Each Remote Loader instance running on a particular machine must use a different trace file. Trace messages are written to the trace file only if the trace level is greater than zero.

    3. Specify the approximate maximum size that the trace file for this instance can occupy on disk.

  9. Select Establish a Remote Loader service for this driver instance if you want the Remote Loader as a service.

    Establish a Remote Loader service for this driver instance

    When this option is enabled, the operating system automatically starts the Remote Loader when the computer starts.

  10. Click OK, to save the configuration information.

If you need to change any of the parameters:

  1. In the Remote Loader Console, select the Remote Loader instance from the Description column.

  2. Click Stop, type the Remote Loader password, then click OK.

  3. Click Edit, then modify the configuration information. These are the same fields you filled in when you add a Remote Loader instance.

  4. Click OK, to save the changes.

3.4.2 Configuring the Remote Loader by Creating a Configuration File

For the Remote Loader to run, it requires a configuration file (for example, LDAPShim.txt). Windows is the only platform that provides a GUI interface to create this file. You can create or edit a configuration file by using command line options. The following steps provide information on basic parameters for the configuration file. Section B.0, Options for Configuring a Remote Loader.

  1. To create a configuration file, open a text editor.

  2. (Optional) Specify a description by using the -description option.

    Option

    Secondary Name

    Parameter

    Description

    -description

    -desc

    short description

    Specify a short description string (for example, SAP) to be used for the trace window title and for Novell Audit logging.

    Example:

    -description SAP 
    -desc SAP
    

    The Remote Loader Console places long forms in the configuration files. You can use either a long form (for example, -description) or a short form (for example, -desc).

  3. Specify a TCP/IP port that the Remote Loader instance will use by using the -commandport option.

    Option

    Secondary Name

    Parameter

    Description

    -commandport

    -cp

    port number

    Specifies the TCP/IP port that the Remote Loader instance uses 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 communicates with the instance that is 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 run on the same server hosting different driver instances by specifying different connection ports and command ports.

    Example:

    -commandport 8001 
    -cp 8001 
    
  4. Specify the parameters for connecting to the Metadirectory server running the Identity Manager remote interface shim by using the -connection option.

    The following table describes the -connection option:

    Option

    Secondary Name

    Parameter

    Description

    - connection

    - conn

    connection configuration string

    Specifies the connection parameters for the connection to the Metadirectory server running the Identity Manager 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 run on the same server. Each instance of the Remote Loader hosts a separate Identity Manager application shim instance. Differentiate multiple instances of the Remote Loader by specifying different connection ports and command ports for each Remote Loader instance.

    Example:

    -connection “port=8091 rootfile=server1.pem” 
    -conn “port=8091 rootfile=server1.pem” 
    

    Type -connection “parameter [parameter]”.

    The following table describes the parameters for the -connection option and their supported platforms:

    Parameter

    Example

    Description

    Platform

    port

    port=8090 
    

    A decimal port number. A required parameter. It specifies the TCP/IP port on which the Remote Loader listens for connections from the remote interface shim.

    Windows and Unix

    address

    address=137.65.134.83
    

    The IP address. An optional parameter. Specifies that the Remote Loader listens 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.

    You have two options:

    address=’ip address’
    address=’localhost’
    

    If you don’t use the address, the Remote Loader listens on all local IP addresses.

    Windows and Unix

    fromaddress

    -connect “port=8094 fromaddress=10.0.0.2”

    The Remote Loader only accepts connections from the specified IP address. Any other connections are not allowed.

    Windows and Unix

    handshaketimeout

    -connection “port=8091 handshaketimeout=1000”

    Increases the time out period of the handshake between the Remote Loader and the Metadirectory engine.

    The value is some integer greater than or equal to zero. Zero means never time out. The non-zero number is the number of milliseconds for the time out to occur. The default value is 1000 milliseconds.

    Windows and Unix

    rootfile

    rootfile=’trusted certname

    A conditional parameter. If you are running SSL and need the Remote Loader to communicate with a native driver, type. This parameter is valid only for native drivers.

    You have the option of specifying the absolute path. If the absolute path is not specified,use the following guidelines to choose the directory:

    • On a Windows platform, use the directory in which dirxml_remote.exe is found.

    • On a Unix platform, specify the directory with the -datadir parameter or with the RDXMLPATH environment variable. If you do not specify a directory, the default directory /var/opt/novell/dirxml/rdxml is used.

    Windows and Unix

    keystore

    keystore=’keystorename

    A conditional parameter. Used only for the Identity Manager 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 is typically the Certificate Authority of the eDirectory tree that is hosting the remote interface shim.

    If you are running SSL and need the Remote Loader to communicate with a Java driver, type a key-value pair.

    You have the option of specifying the absolute path. If the absolute path is not specified,use the following guidelines to choose the directory:

    • On a Windows platform, use the directory in which dirxml_remote.exe is found.

    • On a Unix platform, specify the directory with the -datadir parameter or with the RDXMLPATH environment variable. If you do not specify a directory, the default directory /var/opt/novell/dirxml/rdxml is used.

    NOTE:For more information on creating the keystore option, see Section 3.8.3, Creating a Keystore

    Windows and Unix

    storepass

    storepass=’dirxml

    Used only for the Identity Manager application shims contained in .jar files. Specifies the password for the Java keystore specified by the keystore parameter.

    This option applies only to the Java Remote Loader.

    Unix

    keypass

    keypass=’mypassword

    Used only for the Identiy Manager application shims contained in .jar files. Specifies the password for the Java keystore specified by the keystore parameter.

    Windows

    fromaddress

    137.65.134.84

    Specifies that the remote loader will only accept connections from the specified IP address.

    Windows and Unix

    handshaketimeout

    1500

    Specifies the ‘handshake timeout’ value for connections to the remote loader. If the SSL handshake and password exchange handshake do not complete within this period after the initial TCP connection, the remote loader closes the connection.

    NOTE:The default value of 1000 (1 second) should only be changed when handshake timeouts occur with otherwise valid connections from the Identity Manager engine.

    Windows and Unix

     

     

     

     

  5. (Optional) Specify a trace parameter by using the -trace option.

    Option

    Secondary Name

    Parameter

    Description

    -trace

    -t

    integer

    Specifies the trace level. This is only used when hosting an application shim. Trace levels correspond to those used on the Metadirectory server.

    Example:

    -trace 3
    -t 3 
    
  6. (Optional) Specify a tracefile by using the -tracefile option.

    Option

    Secondary Name

    Parameter

    Description

    -tracefile

    -tf

    filename

    Specify a file to write trace messages to. Trace messages are written to the file if the trace level is greater than zero. Trace messages are written to the file even if the trace window is not open.

    Example:

    -tracefile c:\temp\trace.txt 
    -tf c:\temp\trace.txt 
    
  7. (Optional) Limit the size of the tracefile by using the -tracefilemax option.

    Option

    Secondary Name

    Parameter

    Description

    -tracefilemax

    -tfm

    size

    Specifies the approximate maximum size that trace file data can occupy on disk. If you specify this option, 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. Specify the size by using the suffixes K, M, or G for kilobytes, megabytes, or gigabytes.

    If the trace file data is larger than the specified maximum when the Remote Loader is started, the trace file data remains larger than the specified maximum until roll-over is completed through all 10 files

    Example:

    -tracefilemax 1000M 
    -tfm 1000M 
    

    In this example, the trace file can be only 1 GB.

  8. Specify the class by using the -class option, or the module by using the -module option.

    Option

    Secondary Name

    Parameter

    Description

    -class

    -cl

    Java class name

    Specifies the Java class name of the Identity Manager application shim that is to be hosted.

    For example, for a Java driver, type one of the following:

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

    Java uses a keystore to read certificates. The -class option and the -module option are mutually exclusive.

    To see a list of the Java class name see Table B-2 in Section B.0, Options for Configuring a Remote Loader.

    -module

    -m

    modulename

    Specifies the module containing the Identity Manager application shim that is to be hosted.

    For example, for a native driver, type one of the following:

    -module "c:\Novell\RemoteLoader\Exchange5Shim.dll"
    -m "c:\Novell\RemoteLoader\Exchange5Shim.dll"
    

    or

    -module "/usr/lib/dirxml/NISDriverShim.so"
    -m "/usr/lib/dirxml/NISDriverShim.so"
    

    The -module option uses a rootfile certificate. The -module option and the -class option are mutually exclusive.

  9. Name and save the file.

You can change some settings while the Remote Loader is running, see Table 3-1 for a list of some of these settings. For a complete list of these settings, see Section B.0, Options for Configuring a Remote Loader.

Table 3-1 Selected Remote Loader Parameters

Parameter

Description

-commandport

Specifies an instance of the Remote Loader.

-config

Specifies a configuration file.

-javadebugport

Specifies that the Remote Loader instance is to enable Java debugging on the specified port.

-password

Specifies the password for authentication.

-service

Installs an instance as a service. Windows only.

-tracechange

Changes the trace level.

-tracefilechange

Changes the name of the trace file being written to.

-unload

Unloads the Remote Loader instance.

-window

Turns the trace window on or off in a Remote Loader instance. Windows only.

The following sample configuration files show various options that can be configured. On a Windows platform: -description "Sample1" -commandport 8015 -connection "port=8111" -trace 4 -tracefile "C:\Novell\RemoteLoader\Sample1-Trace.log" -tracefilemax 25M -class "com.novell.nds.dirxml.driver.ldap.LDAPDriverShim"

On a Unix platform: -description "Sample1" -commandport 8015 -connection "port=8111" -trace 4 -tracefile "/tmp/trace.txt" -tracefilemax 25M -class "com.novell.nds.dirxml.driver.ldap.LDAPDriverShim" -module "$DXML_HOME/dirxmlremote/libcskeldrv.so.0.0.0"