20.2 Understanding the Configuration Parameters for the Remote Loader

For the Remote Loader to work with a driver instance that hosts an Identity Manager application shim, you must configure the driver instance. For example, you must specify the connection and port settings for the instance. You can specify the settings from the command line, in a configuration file (UNIX or Linux), or in the Remote Loader Console (Windows). Once the instance is running, you can use the command line to modify the configuration parameters or instruct the Remote Loader to perform a function. For example, you might want to open the trace window or unload the Remote Loader.

This section provides information about the configuration parameters. The explanation specifies whether a parameter can be sent from the command line to updated the Remote Loader while the instance is running.

For more information about configuring a new driver instance, see the following sections:

Linux and UNIX: Configuring the Remote Loader for Driver Instances on UNIX or Linux
Windows: Configuring the Remote Loader for Driver Instances on Windows.

20.2.1 Configuration Parameters for the Driver Instances in the Remote Loader

You can configure a driver instance from the command line or in a configuration file. NetIQ provides a sample file config8000.txt to help you configure the Remote Loader and drivers for use with your application shim. The sample file is located by default in the /opt/novell/dirxml/doc directory. For example, the configuration file might include the following lines:

-commandport 8000
-connection "port=8090 rootfile=/dirxmlremote/root.pem"
-module $DXML_HOME/dirxmlremote/libcskeldrv.so.0.0.0
-trace 3

Use the following parameters:

-assembly

(Conditional) When using a .NET Remote Loader, specifies the path where the driver .dll is located. Ensure that the configuration file includes this parameter. For example:

-assembly C:\Novell\remoteloader.NET\DXMLMADDriver.dll

-description value (-desc value)

(Optional) Specifies a short description in string format, such as SAP, which the application uses for the title of the trace window and for audit logging. For example:

-description SAP

-desc SAP

-class name (-cl name)

(Conditional) When using a Java driver, specifies the Java class name of the Identity Manager application shim that you want to host. This options tells the application to use a Java keystore to read certificates. For example:

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

NOTE:

You cannot use this option if you specify a -module option.
If you use the tab character as a delimiter in the -class option, the Remote Loader does not start automatically. Instead, you must manually start it. For the Remote Loader to start properly, you can use a space character instead of a tab.
For more information about names that you can specify for this option, see Understanding the Names for the Java -class Parameter.

-commandport port_number (-cp port_number)

Specifies the TCP/IP port that the driver instance uses for control purposes. For example, -commandport 8001 or -cp 8001. The default value is 8000.

To use multiple driver instances with the Remote Loader on the same server, specify different connection ports and command ports for each instance.

If the driver instance hosts an application shim, the command port is the port on which another instance communicates with the instance that is hosting the shim. If the driver instance sends a command to an instance that is hosting an application shim, the command port is the port on which the hosting instance is listening.

When you send this parameter from the command line to an instance that hosts an application shim, the command port represents the port on which the hosting instance is listening. You can send this command when the Remote Loader is running.

-config filename

Specifies a configuration file for the driver instance. For example:

-config config.txt

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

You can send this command when the Remote Loader is running.

-connection “parameters” (-conn “parameters”)

Specifies the settings for connecting to the server hosting the Identity Manager engine that runs the Identity Manager remote interface shim. The default connection method is TCP/IP using SSL.

To use multiple driver instances with the Remote Loader on the same server, specify different connection ports and command ports for each instance.

Enter the connection settings in the following syntax:

-connection "parameter parameter parameter"

For example:

-connection "port=8091 fromaddress=198.51.100.0 rootfile=server1.pem keystore=ca.pem localaddress=198.51.100.0 hostname=198.51.100.0 kmo=remote driver cert"

Use the following parameters for the specifying the settings for a TCP/IP connection:

address=IP_address

(Optional) Specifies whether 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. The following values are valid:

address=address number
address='localhost'

For example:

address=198.51.100.0

If you do not specify a value, the Remote Loader listens on all local IP addresses.

fromaddress=IP_address

Specifies the server from which the Remote Loader accepts connections. The application ignores connections from other addresses. Specify an IP address or the DNS name of the server. For example:

fromaddress=198.51.100.0

fromaddress=testserver1.company.com

handshaketimeout=milliseconds

(Conditional) Applies when handshake timeouts occur with otherwise valid connections from the Identity Manager engine. Specifies the timeout period, in milliseconds, for the handshake between the Remote Loader and the Identity Manager engine. For example:

handshaketimeout=1000

You can specify an integer greater than or equal to zero. Zero means that the connection never times out. The default value is 1000 milliseconds.

hostname=server

Specifies the IP address or name of the server on which the Remote Loader runs. For example:

hostname=198.51.100.0

secureprotocol=TLS version

Specifies the version of the TLS protocol that the Remote Loader uses to connect to the Identity Manager engine. For example:

secureprotocol=TLSv1_2

Identity Manager supports TLSv1 and TLSv1_2. By default, the Remote Loader uses TLSv1_2. To use TLSv1, specify this version in the parameter.

enforceSuiteB=true/false

(Conditional) Applies only when you want the Remote Loader to communicate with the Identity Manager engine using Suite B cryptographic algorithms.

To use Suite B for communication, specify true. This communication is supported only on TLS 1.2 protocol.

If you try to connect a Suite B-enabled engine with a Remote Loader that does not support TLSv1.2, the handshake fails and the communication is not established. For example, Remote Loader 4.5.3, which does not support TLS v1.2.

useMutualAuth=true/false

(Conditional) Applies only when want the Remote Loader and the Identity Manager engine to authenticate each other by verifying the public key certificate or digital certificate issued by the trusted Certificate Authorities (CAs) or self-signed certificates. For example:

useMutualAuth=true

keystore=filename

Specifies the file name of the Java keystore that contains the trusted root certificate of the issuer of the certificate that the remote interface shim uses. For example:

keystore=keystore filename

Usually, you specify the Certificate Authority of the tree that is hosting the remote interface shim.

kmo=name

Specifies the key name of the Key Material Object containing the keys and certificate used for SSL connections. For example:

kmo=remote driver cert

localaddress=IP_address

Specifies the IP address to which you want to bind the socket for client connection. For example:

localaddress=198.51.100.0

port=port_number

Specifies the TCP/IP port on which the Remote Loader listens for connections from the remote interface shim. To specify the default port, enter port=8090.

rootfile=trusted certname

Specifies the name of the file that contains the trusted root certificate of the issuer of the certificate that the remote interface shim uses. The certificate file must be in Base 64 format (PEM). For example:

rootfile=trustedcert

Usually, the file will be the Certificate Authority of the tree that is hosting the remote interface shim.

storepass=password

Specifies password for the Java keystore that you entered for the keystore parameter. For example:

storepass=mypassword

For the Remote Loader to communicate with a Java driver, specify a key-value pair, using the following syntax:

keystore=keystorename storepass=password

-datadir directory (-dd directory)

Specifies the directory for data files that the Remote Loader uses. For example:

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

When you use this command, the rdxml process changes its current directory to the specified directory. Trace files and other files that do not have an explicitly specified path will be created in this data directory.

-help (-h)

Instructs the application to display the Help.

-java (-j)

(Conditional) Specifies that you want to set passwords for a Java driver shim instance.

NOTE:Use this option with the -setpasswords option when you do not also specify a -class value.

-javadebugport port_number (-jdp port_number)

Instructs the instance to enable Java debugging on the specified port. For example:

-javadebugport 8080

Use this command when developing Identity Manager application shims. You can send this command when the Remote Loader is running.

-javaparam parameters (-jp parameters)

Specifies the parameters for the Java environment. Enter the Java environment parameters in the following syntax:

-javaparam parameter
-jp parameter
-jp parameter

NOTE:Do not use this parameter with the Java Remote Loader.

To specify multiple values for an individual parameter, enclose the parameter in quotation marks. For example:

-javaparam DHOST_JVM_MAX_HEAP=512M
-jp DHOST_JVM_MAX_HEAP=512M
-jp "DHOST_JVM_OPTIONS=-Dfile.encoding=utf-8 -Duser.language=en"

Use the following parameters for setting the Java environment:

DHOST_JVM_ADD_CLASSPATH

Specifies additional paths for the JVM to search for package (.jar) and class (.class) files. To specify multiple class paths for a UNIX or Linux JVM, insert a colon between each path. For a Windows JVM, use a semicolon.

DHOST_JVM_INITIAL_HEAP

Specifies the initial (minimum) JVM heap size in decimal number of bytes. Use a numeric value followed by G, M, or K representing the byte type. For example:

100M

If you do not specify a byte type, the size defaults to bytes. Using this parameter is the same as using the java -Xms command.

This parameter has precedence over the driver set attribute option. Increasing the initial heap size can improve startup time and throughput performance.

DHOST_JVM_MAX_HEAP

Specifies the maximum JVM heap size in decimal number of bytes. Use a numeric value followed by G, M, or K representing the byte type. For example:

100M

If you do not specify a byte type, the size defaults to bytes.

This parameter has precedence over the driver set attribute option.

DHOST_JVM_OPTIONS

Specifies the arguments that you want to use when starting the JVM instance of the driver. Use a space to separate each option string. For example:

-Xnoagent -Xdebug -Xrunjdwp: transport=dt_socket,server=y, address=8000

The driver set attribute option has precedence over this parameter. This environment variable is tacked on to the end of driver set attribute option. For more information about valid options, see the JVM documentation.

-module “name” (-m “name”)

(Conditional) When using a native drive, specifies the module containing the Identity Manager application shim that you want to host. This option tells the application to use a rootfile certificate. For example, for a native driver, type one of the following:

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

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

NOTE:

You cannot use this option if you specify a -class option.
If you use the tab character as a delimiter in the -module option, the Remote Loader does not start automatically. Instead, you must manually start it. For the Remote Loader to start properly, you can use a space character instead of a tab.

-password value (-p value)

Specifies the password for the driver instance when you issue commands that change settings or affect instance operation. You must specify the same password as the first password specified with setpasswords for the instance that you want to command. For example:

-password netiq4

If you do not send the password when issuing commands, the driver instance prompts you for the password.

You can send this command when the Remote Loader is running.

-piddir directory (-pd directory)

Specifies the path to directory for the process id file (pidfile) used by the Remote Loader process. For example:

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

The pidfile exists primarily for use by SysV-style init scripts. The default value is /var/run. Alternatively, the default value is the current directory, if the Remote Loader is run by a user without sufficient rights to open the pidfile for reading and writing in /var/run.

This parameter is similar to -datadir.

-service value (-serv value)

(Windows only) Specifies whether you want to configure an instance as a Win32 service on a Windows computer. Valid values are install and uninstall plus the other parameters necessary to host an application shim. For example, you must include -module and might also include -commandport and the connection settings.

This command simply installs or uninstalls the instance as a service. It does not start the service.

You can send this command when the Remote Loader is running. However, you cannot use this command on rdxml or the Java Remote Loader.

-setpasswords Remote_Loader_pwd optional_pwd (-sp Remote_Loader_pwd optional_pwd)

Specifies the password for the driver instance and the password of the Identity Manager Driver object of the remote interface shim with which the Remote Loader communicates.

You do not need specify a password. Instead, the Remote Loader prompts you for the passwords. However, if you specify the password for the Remote Loader, you must also specify the password for the Identity Manager Driver object associated with the remote interface shim on the Identity Manager engine server. To specify the passwords, use the following syntax:

-setpasswords Remote_Loader_password driver_object_password

For example:

-setpasswords netiq4 idmobject6

NOTE:Using this option configures the driver instance with the passwords specified but does not load a Identity Manager application shim or communicate with another instance.

trace file settings

(Conditional) When hosting an Identity Manager application shim, specifies the settings for a trace file that contains informational messages from both the Remote Loader and the driver for this instance.

Add the following parameters to the configuration file:

-trace integer (-t integer)

Specifies the level of messages that you want displayed in a trace window. For example:

-trace 3

Trace levels for the Remote Loader correspond to those used on the server hosting the Identity Manager engine.

-tracefile filepath (-tf filepath)

Specifies the path to a file where trace messages are logged. You must specify a unique trace file for each driver instance running on a particular computer. For example:

-tracefile c:\temp\trace.txt

The application writes messages to the file if the -trace parameter is greater than zero. The trace window does not need to be open for messages to be written to the file.

-tracefilemax size (-tf size)

Specifies a limit to the size of the trace file for this instance. Specify the value in kilobytes, megabytes, or gigabytes, using the abbreviation for the byte type. For example:

-tracefilemax 1000K
-tf 100M
-tf 10G

NOTE:

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.
When you add this option to the configuration file, the application uses the specified name for the tracefile and includes up to 9 “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.

-tracechange integer (-tc integer)

(Conditional) When you have an existing driver instance that hosts an application shim, specifies a new level of informational messages. Trace levels correspond to those used on the Identity Manager server. For example:

-trace 3

You can send this command when the Remote Loader is running.

-tracefilechange filepath (-tfc filepath)

(Conditional) When you have an existing driver instance that hosts an application shim, instructs that instance to use a trace file or to close a file already in use and change to this new file. For example:

-tracefilechange \temp\newtrace.txt

You can send this command when the Remote Loader is running.

-unload (-u)

Instructs the driver instance to unload. If the Remote Loader is running as a Win32 Service, this command stops the service.

You can send this command when the Remote Loader is running.

-window value (-w) value

(Windows only) Instructs the application to turn on or off the trace window for a driver instance on a Windows computer. Valid values are on and off. For example:

-window on

You can send this command when the Remote Loader is running. You cannot use this command with the Java Remote Loader.

-wizard (-wiz)

(Windows only) Launches the Configuration Wizard for the Remote Loader on a Windows computer. You can also launch the wizard by running dirxml_remote.exe with no command line parameters.

If you run this command and also specify a configuration file (-config option), the wizard starts with the values from the configuration file. You can use the wizard to change the configuration without editing the configuration file directly. For example:

-wizard -config config.txt

You cannot use this command with the Java Remote Loader.

20.2.2 Understanding the Names for the Java -class Parameter

When you use the -class parameter to configure a driver instance for the Remote Loader and Java Remote Loader, you must specify the Java class name of the Identity Manager application shim that you want to host.

Java Class Name	Driver
com.novell.nds.dirxml.driver.dcsshim.DCSShim	Driver for Data Collection Service
com.novell.nds.dirxml.driver.delimitedtext.DelimitedTextDriver	Delimited Text Driver
be.opns.dirxml.driver.ars.arsremedydrivershim.ARSDriverShim	Driver for Remedy ARS
com.novell.nds.dirxml.driver.entitlement.EntitlementServiceDriver	Entitlements Service Driver
com.novell.gw.dirxml.driver.rest.shim.GWdriverShim	GroupWise 2014 Driver
com.novell.idm.drivers.idprovider.IDProviderShim	ID Provider Driver
com.novell.nds.dirxml.driver.jdbc.JDBCDriverShim	JDBC Driver
com.novell.nds.dirxml.driver.jms.JMSDriverShim	JMS Driver
com.novell.nds.dirxml.driver.ldap.LDAPDriverShim	LDAP Driver
com.novell.nds.dirxml.driver.loopback.LoopbackDriverShim	Loopback Driver
com.novell.nds.dirxml.driver.ebs.user.EBSUserDriver	Oracle User Management Driver
com.novell.nds.dirxml.driver.ebs.hr.EBSHRDriver	Oracle HR Driver
com.novell.nds.dirxml.driver.ebs.tca.EBSTCADriver	Oracle TCA Driver
com.novell.nds.dirxml.driver.msgateway.MSGatewayDriverShim	Managed System Gateway Driver
com.novell.nds.dirxml.driver.manualtask.driver.ManualTaskDriver	Manual Task Driver
com.novell.nds.dirxml.driver.nisdriver.NISDriverShim	NIS Driver
com.novell.nds.dirxml.driver.notes.NotesDriverShim	Notes Driver
com.novell.nds.dirxml.driver.psoftshim.PSOFTDriverShim	PeopleSoft Driver
com.netiq.nds.dirxml.driver.pum.PUMDriverShim	Privileged User Management Driver
com.novell.nds.dirxml.driver.salesforce.SFDriverShim	Salesforce Driver
com.novell.nds.dirxml.driver.SAPHRShim.SAPDriverShim	SAP HR Driver
com.novell.nds.dirxml.driver.sap.portal.SAPPortalShim	SAP Portal Driver
com.novell.nds.dirxml.driver.sapumshim.SAPDriverShim	SAP User Management Driver
com.novell.nds.dirxml.driver.soap.SOAPDriver	SOAP Driver
com.novell.idm.driver.ComposerDriverShim	User Application
com.novell.nds.dirxml.driver.workorder.WorkOrderDriverShim	WorkOrder Driver