Novell Doc: Novell Identity Manager 3.5.1 Administration Guide

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.

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

The Remote Loader Console allows you to start, stop, add, remove, and edit each instance of a Remote Loader.
Click Add to add a Remote Loader instance of your driver on this server.
Specify the 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.
Specify the 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.
Specify the 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.
Specify the 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.
Specify the 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.
Specify 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.
Select Establish a Remote Loader service for this driver instance if you want the Remote Loader as a service.

When this option is enabled, the operating system automatically starts the Remote Loader when the computer starts.
Click OK, to save the configuration information.

If you need to change any of the parameters:

In the Remote Loader Console, select the Remote Loader instance from the Description column.
Click Stop, type the Remote Loader password, then click OK.
Click Edit, then modify the configuration information. These are the same fields you filled in when you add a Remote Loader instance.
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.

To create a configuration file, open a text editor.

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

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

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

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

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”

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

(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

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

(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

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

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

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.

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.

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"

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

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"