3.2 Configuring the Remote Loader for Linux/UNIX 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 also create or edit a configuration file by using command line options. The following steps provide information on basic parameters for the configuration file. For information on additional parameters, see Section A.0, Options for Configuring a Remote Loader.

  1. To create a configuration file, open a text editor. You should enter each parameter on a separate line in the configuration file.

  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 a port is 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 the connection to the Metadirectory server running the Identity Manager remote interface shim by using the -connection option.

    Use the format -connection “parameter [parameter] [parameter]”.

    For example, type one of the following:

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

    All the parameters must be included within quotation marks. Parameters include the following:

    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”

    port

    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.

    Example:

    port=8090

    address

    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 three options: 

    address=address number
address=’localhost’
Don’t use this parameter

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

    Example: 

    address=137.65.134.83

    fromaddress

    None

    IP address

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

    Example:

    --conn "port=8092 fromaddress=10.0.0.2"

    or

    -connect "port=8094 fromaddress=metaserver1.company.com”

    handshaketimeout

    None

    number of milliseconds

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

    Example:

    -connection “port=8091 handshaketimeout=1000”

    The value can be 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.

    rootfile

    A conditional parameter. If you are running SSL and need the Remote Loader to communicate with a native driver, use

    rootfile=’trusted certname’

    keystore

    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, use a key-value pair:

    keystore=’keystorename’ storepass=’password’

    storepass

    Local address

    hostname

    kmo

    storepass

    keyname

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

    Example:

    storepass=mypassword

    This option applies only to the Java Remote Loader.

    The local address to which the socket is to be bound for client connection.

    Example:

    localaddress=<ip> 

Specifies the address or name of the machine on which the Remote Loader will run.

Example:

    hostname=192.168.0.1 



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

Example:
kmo='remote driver cert'

  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 trace file 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 trace file 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. (Optional) Specify a Java parameter by using the -javaparam option.

    Option

    Secondary Name

    Parameter

    Description

    -javaparam

    -jp

    java environment parameter

    Specify that the specified Java environment parameters are set to the specified values. The supported parameters are DHOST_JVM_ADD_CLASSPATH (for additional jar files to be loaded alongwith the ones in standard IDM classpath), DHOST_JVM_INITIAL_HEAP, DHOST_JVM_MAX_HEAP, and DHOST_JVM_OPTIONS.

    Example:

    -javaparam DHOST_JVM_MAX_HEAP=512M

    -jp DHOST_JVM_MAX_HEAP=512M

  9. Specify the class by using the -class option, or specify 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, use 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 names see Table 3-3.

    -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\ADDriver.dll"
-m "c:\Novell\RemoteLoader\ADDriver.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.

    NOTE:The Remote Loader configuration file does not recognize the tab character as a delimiter in the -class or -module field, and does not start automatically. You need to manually start it. For the Remote Loader to start properly, you can use a space character instead of a tab.

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

IMPORTANT:For the Remote Loader to automatically start when your computer starts, place the configuration file in the following location:

/etc/opt/novell/dirxml/rdxml

3.2.1 Setting Environment Variables on Solaris, Linux, or AIX

After installing the Remote Loader, you can set the environment variable RDXML_PATH, which changes the current directory for rdxml. This directory is then taken as the base path for files that are subsequently created. To set the value of the RDXML_PATH variable, specify the following commands:

  • set RDXML_PATH=path

  • export RDXML_PATH

Refer to TID 7001255 for configuring the Remote Loader on UNIX platforms.