3.4 Configuring the Remote Loader and Drivers

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 does not load or host a native (C++) driver shim.

Before using the Remote Loader, you must configure the application shim to connect securely with the Identity Manager engine. You must also configure both the Remote Loader and Identity Manager drivers. For more information about shims, see Understanding Shims.

3.4.1 Creating a Secure Connection to the Identity Manager Engine

You must ensure that data transfers securely between the Remote Loader and the Identity Manager engine. NetIQ recommends using Transport Layer Security/Secure Socket Layer (TLS/SSL) protocols for communication. To support TLS/SSL connections, you need an appropriate self-signed certificate in a keystore file. This section explains how to create, export, and store that certificate.

NOTE:Use the same version of SSL on the servers hosting the Identity Manager engine and the Remote Loader. If the versions of SSL on the server and the Remote Loader do not match, the server returns a SSL3_GET_RECORD:wrong version number error message. This message is only a warning, and communication between the server and Remote Loader is not interrupted. However, the error might cause confusion.

Understanding the Communication Process

The Remote Loader opens a server socket and listens for connections from the remote interface shim. The remote interface shim and the Remote Loader perform an SSL handshake to establish a secure channel. Then the remote interface shim authenticates to the Remote Loader. If the authentication of the remote interface shim succeeds, 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 process for establishing SSL connections between a driver and the Identity Manager engine depends on the type of driver:

  • For a native driver, such as the Active Directory driver, point to a base64 encoded certificate. For more information, see Managing Self-Signed Server Certificates.

  • For a Java driver, you must create a keystore. For more information, see Creating a Keystore File when Using SSL Connections.

  • For a .NET driver, point to a base64 encoded certificate. For more information, see Managing Self-Signed Server Certificates.

    If the EC certificate is created with 521 as the key size, then you must add the NIST P-521 elliptic curve to the list of TLS ECC order on the Windows server where .NET Remote Loader is running. To do so, perform the following steps:

    1. Click Run > gpedit.msc.

    2. In the Local Group Policy Editor, navigate to Computer Configuration > Administrative Templates > Network > SSL Configuration Settings.

    3. Double-click ECC Curve Order.

    4. Set the value to Enabled and then add NistP521 in the ECC Curve Order field.

    5. Save the changes and restart the Windows server.

NOTE:The Remote Loader allows for custom connection methods between the Remote Loader and the remote interface shim that is hosted on the Identity Manager server. To configure a custom connection module, see the documentation that comes with the module for information regarding what is expected and allowed in the connection string.

Managing Self-Signed Server Certificates

You can create and export a self-signed server certificate to ensure secure communication between the Remote Loader and the Identity Manager engine. For additional security, you can configure stronger ciphers for SSL communication as specified by Suite B. This communication requires the use of ECDSA (Elliptic Curve Digital Signature Algorithm) certificates for encrypting the data. When Suite B is enabled, Remote Loader uses TLS 1.2 as a communication protocol. For more information about Suite B, see Suite B Cryptography.

You can export a newly created certificate or use an existing certificate.

NOTE:When a server joins a tree, eDirectory creates the following default certificates:

  • SSL CertificateIP

  • SSL CertificateDNS

  • Suite B compliant certificates

  1. Log in to NetIQ iManager.

  2. To create a new certificate, complete the following steps:

    1. Click NetIQ Certificate Server > Create Server Certificate.

    2. Select the server to own the certificate.

    3. Specify a nickname for the certificate. For example, remotecert.

      NOTE:NetIQ recommends that you avoid using spaces in the certificate nickname. For example, use remotecert instead of remote cert.

      Also, make a note of the certificate nickname. This nickname is used for the KMO name in the driver’s remote connection parameters.

    4. Select the certificate creation method, then click Next.

      You have the following options:

      • Standard: This option creates a server certificate object using the largest possible key size and signs the public key certificate with your Organizational CA.

      • Custom: This option creates a server certificate object using the settings you specify. It allows you to set a number of customized settings for the Server Certificate object. Select this option to create ECDSA certificates for Suite B communication.

      • Import: This option creates a server certificate object using the keys and certificates from a PKCS12 (PFX) file. You can use this option in conjunction with the Export feature to backup and restore a Server Certificate or to move a Server Certificate object from one server to another.

    5. Specify the certificate parameters.

    6. Accept the rest of the certificate defaults.

    7. Review the summary, click Finish, then click Close.

  3. To export a certificate, complete the following steps:

    1. In iManager, navigate to Roles and Tasks > NetIQ Certificate Access > Server Certificates.

    2. Browse and select the created certificate or the server created certificate (for example, SSL CertificateDNS).

    3. Click Export.

    4. Select the CA Certificate as OU=organization CA.O=TREEANAME from the drop down menu.

    5. Select the Export Format as BASE64 from the drop down menu.

      NOTE:When the Remote Loader is running on a Windows 2012 R2 64-bit server, the certificate must be in Base64 format. If you use the DER format, the Remote Loader fails to connect to the Identity Manager engine.

    6. Click Next.

    7. Click Save, then click Close.

Creating a Keystore File when Using SSL Connections

To use SSL connections between a Java driver and the Identity Manager engine, you must create a keystore. A keystore is a Java file that contains encryption keys and, optionally, certificates. If you want to use SSL between the Remote Loader and the Identity Manager engine, and you are using a Java shim, you need to create a keystore file. The following sections explain how to create a keystore file:

Creating a Keystore on Any Platform

To create a keystore on any platform, you can enter the following at the command line:

keytool -import -alias trustedroot -file self-signed_certificate_name -keystore filename -storepass keystorepass

The filename can be any name. For example, rdev_keystore.

Creating a Keystore on Linux

In Linux environments, use the create_keystore file, which is a shell script that calls the Keytool utility. The file is installed with rdxml, located by default in the install_directory/dirxml/bin directory. The create_keystore file is also included in the dirxml_jremote.tar.gz file, found in the \dirxml\java_remoteloader directory.

Perform the following actions to create the keystore:

  1. Change to the directory in which you installed the JRE.

    % cd JAVA-HOME/bin

    For example: % cd opt/netiq/common/jre/bin

  2. Set the path variable to include the location of the JRE at the command line.

    export PATH=opt/netiq/common/jre/bin 
  3. Create the keystore by entering the following at the command line:

    create_keystore self-signed_certificate_name keystorename

    For example, type one of the following

    create_keystore tree-root.b64 mystore
    create_keystore tree-root.der mystore

    The create_keystore script specifies a hard-coded password of “dirxml” for the keystore password. This is not a security risk because only a public certificate and public key are stored in the keystore.

Creating a Keystore on Windows

Run the Keytool utility, located by default in the c:\novell\remoteloader\jre\bin directory.

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

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 on Linux. On Windows, the sample file is located by default in the C:\novell\remoteloader\<architecture(64bit/32bit>\ or C:\Novell\remoteloader.NET directory.

For example, the configuration file might include the following lines on Linux:

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

The configuration file might include the following lines on Windows:

-commandport 8000
-connection "port=8090"
-trace 4
-tracefile ./trace8000.log
-class com.novell.nds.dirxml.driver.delimitedtext.DelimitedTextDriver 

Table 3-1 describes the options that enable you to configure the Remote Loader:

Table 3-1 Remote Loader Options

Option

Secondary Name

Parameter

Description

-assembly

path to driver DLL file

(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

-class

-cl

Java class 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

-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

None

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.

-description

-desc

short description

(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

-module

-m

modulename

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

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

-p

password

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

-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

-serv

None, or install/uninstall

Specifies whether you want to configure an instance as a Win32 service. 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

-sp

password password

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.

-datadir

-dd

directory

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

-datadir C:\novell\remoteloader 

When you use this command, the Remote Loader 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

None

Instructs the application to display the Help.

-connection

-conn

connection configuration string

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"

TCP/IP connection settings

 

 

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

address

None

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

None

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

None

Number of 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

None

IP_address or name of the server

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

hostname=198.51.100.0

secureprotocol

None

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

None

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

None

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

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

 

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

 

decimal 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 root certificate filename

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

 

storepass

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

Java settings

Use the following parameters for specifying the Java settings:

-java

-j

None

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

NOTE:If -class value is specified with -setpasswords, this option is not necessary.

-javadebugport

-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

-jp

 

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"

Java environment settings

 

 

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.

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.

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

-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

-tf

filename

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 /home/trace.txt on Linux

-tracefile c:\temp\trace.txt on Windows

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

-tfm

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:

  • 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. Each file size is 1/10th of the total size specified. The roll-over files are named using the base of the main trace filename plus _n, where n is 1 through 9.

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

-tracechange

-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

-tfc

None, or filename

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

Certificate password settings

 

 

(Conditional) Only when useMutualAuth is set to true in the configuration file.

Use the following parameters for specifying the Certificate password settings:

-keystorepassword

-ksp

password

Specifies the keystore password to enable mutual authentication for Java Remote Loader drivers only.

-keypassword

-kp

password

Specifies the key password to enable mutual authentication for both Java and native Remote Loader drivers.

-unload

-u

None

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

-w

On/Off

Instructs the application to turn on or off the trace window for a driver instance. 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

None

Launches the Configuration Wizard for the Remote Loader. 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.

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

3.4.3 Configuring the Remote Loader for Driver Instances on UNIX or Linux

The Remote Loader can host the Identity Manager application shims contained in .dll, .so, or .jar files. For the Remote Loader to run on a UNIX or Linux computer, the application needs a configuration file such as LDAPShim.txt for each driver instance. You can also create or edit a configuration file by using command line options.

By default, the Remote Loader connects to the Identity Manager engine through TCP/IP using TLS/SSL protocols. The default TCP/IP port for this connection is 8090. You can run multiple driver instances with the Remote Loader on the same server. Each instance hosts a separate Identity Manager application shim instance. To use multiple instances of the Remote Loader on the same server, specify different connection ports and command ports for each instance.

NOTE:

  • The configuration file can contain any command line options except -config.

  • When adding parameters to the configuration file, you can use the long form or a short form of the parameter. For example, -description or -desc.

  • The following procedure lists the long form first, followed by the short form in parentheses. For example -description value (-desc value).

  • For more information about the parameters used in this section, see Understanding the Configuration Parameters for the Remote Loader.

To create a configuration file:

  1. In a text editor, create a new 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.

  2. Add the following configuration parameters to the file:

    • -description (optional)

    • -commandport

    • connection parameters:

      • port (mandatory)

      • address

      • fromaddress

      • handshaketimeout

      • rootfile

      • keystore

      • localaddress

      • hostname

      • kmo

      • secureprotocol

      • enforceSuiteB

      • useMutualAuth

    • trace file parameters (optional):

      • -trace

      • -tracefile

      • -tracefilemax

    • -javaparam

    • -class or -module

    For more information about specifying values for these parameters, seeUnderstanding the Configuration Parameters for the Remote Loader.

  3. Save the file.

    For the Remote Loader to start automatically when your computer starts, save the file to the /etc/opt/novell/dirxml/rdxml directory.

3.4.4 Configuring the Remote Loader for Driver Instances on Windows

The Remote Loader can host the Identity Manager application shims contained in .dll, .so, or .jar files. For the Remote Loader to run, the application needs a configuration file, such as LDAPShim.txt. The Remote Loader Console utility (the Console) helps you manage all instances of Identity Manager drivers running on the Windows server. You can start, stop, add, remove, and edit each instance of a Remote Loader. The installation program for the Remote Loader also installs the Console.

If you are upgrading, the Console detects and imports existing driver instances. For a driver to be automatically imported, its configuration file must be stored in the Remote Loader directory, located by default at c:\novell\remoteloader. You can then use the Console to manage the remote drivers.

You can use the command line or the Remote Loader Console to configure the Remote Loader to recognize a driver on Windows. For more information about using the command line, see Understanding the Configuration Parameters for the Remote Loader.

This section provides instructions for the following activities:

Creating a New Driver Instance in the Remote Loader on Windows

  1. Open the Remote Loader Console.

    NOTE:During installation, if you selected to create a shortcut for the Console, use the Identity Manager Remote Loader Console icon on the desktop. Otherwise, run rlconsole.exe located by default in C:\novell\remoteloader\nnbit.

  2. To add an instance of your driver on this server, click Add.

  3. For Description, provide a short name to represent the instance.

    The Console uses this information in the default value for Config File.

  4. For Driver, select the Java class name.

    NOTE:To use the Active Directory driver, select ADDriver.dll. For more information about the class names for each driver, see Understanding the Names for the Java -class Parameter.

  5. For Config File, specify the path to the file where Remote Loader stores its configuration parameters. The default value is C:\novell\remoteloader\nnbit\Description-config.txt.

  6. Specify passwords for the Remote Loader and driver object.

  7. (Optional) To use a TLS/SSL connection between the Remote Loader and the Identity Manager engine server, complete the following steps:

    1. Select Use an SSL Connection.

      NOTE:NetIQ recommends using the same version of SSL on both the Identity Manager engine server and the Remote Loader. If the versions of SSL on the server and the Remote Loader do not match, the server returns a “SSL3_GET_RECORD:wrong version number” error message. This message is only a warning, and communication between the server and Remote Loader is not interrupted. However, the error might cause confusion.

    2. For Trusted Root File (base64 format file), specify the exported self-signed certificate from the eDirectory tree’s Organization Certificate Authority. For more information, see Creating a Secure Connection to the Identity Manager Engine and Understanding the Configuration Parameters for the Remote Loader.

  8. (Optional) To configure the trace file for the Remote Loader, complete the following steps:

    NOTE:NetIQ recommends using the trace functionality only for troubleshooting issues. Having the trace enabled reduces the performance of the Remote Loader. Do not leave the trace enabled in production.

    1. For Trace Level, specify a value greater than zero that defines the level of informational messages from both the Remote Loader and the driver that you want display in a trace window. Values 1 to 4 are pre-defined by the Console. To create your own message types, specify a value of 5 or higher.

      The most common setting is trace level 3, which provides general processing, XML documents, and Remote Loader messages.

    2. For Trace File, specify the path to a file where trace messages are logged. For example, C:\novell\remoteloader\64bit\Test-Delimited-Trace.log.

      You must specify a unique trace file for each driver instance running on a particular computer. Trace messages are written to the trace file only if the trace level is greater than zero.

    3. For Maximum Disk Space Allowed for all Trace Logs (Mb), specify an approximate value for the most disk space that the trace file for this instance can occupy.

  9. (Optional) To allow the Remote Loader to start automatically when the computer starts, select Establish Remote Loader Service for this driver instance.

    NOTE:If the SSL connection fails due to handshaketimeout when Remote Loader establishes connection with Identity Manager engine then, update the default handshaketimeout variable to 10000 and restart both driver and remote loader.

  10. (Conditional) To modify the parameters for Java configuration, complete the following steps:

    1. Select Advanced.

    2. For Classpath, specify the paths for the JVM to search for package (.jar) and class (.class) files.

      This parameter functions the same as the java -classpath command.

    3. For JVM Options, specify the options that you want to use when starting the JVM instance of the driver.

    4. Specify the initial and maximum heap size for the JVM instance in MB.

    5. For Suite B communication, specify enforceSuiteB=true. This communication is supported only on TLS 1.2 protocol.

      For more information, see Creating a Secure Connection to the Identity Manager Engine and Understanding the Configuration Parameters for the Remote Loader.

    6. Click OK.

  11. (Optional) To allow the Remote Loader to use the secure protocol while connecting to the Identity Manager engine, specify the secure protocol version in the Remote Loader configuration file. For example: secureprotocol=TLSv1_2

    For more information, see Understanding the Configuration Parameters for the Remote Loader.

    NOTE:Skip this step if you already configured the secure protocol version on the driver.

  12. (Optional) To allow the Remote Loader communication to use the protocols specified by Suite B, specify enforceSuiteB=true in the Remote Loader configuration file. This communication is supported only on TLS 1.2 protocol.

    For more information, see Understanding the Configuration Parameters for the Remote Loader.

    NOTE:Skip this step if you already enabled Suite B communication on the driver.

  13. Click OK.

Modifying an Existing Driver Instance in the Remote Loader on Windows

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

  2. Click Stop.

  3. Enter the password for the Remote Loader, then click OK.

  4. Click Edit.

  5. Modify the configuration information. For more information about each parameter, see Creating a New Driver Instance in the Remote Loader on Windows.

  6. To save the changes, click OK.

3.4.5 Configuring the Java Remote Loader for Driver Instances

The Java Remote Loader hosts only Java driver shims. It does not load or host a native (C++) driver shim.

To configure a new instance for the Java Remote Loader on Linux platforms, complete the following steps. For more information about the parameters used in this section, see Understanding the Configuration Parameters for the Remote Loader.

  1. In a text editor, create a new 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 at /opt/novell/dirxml/doc/.

  2. Add the following parameters to the new configuration file:

    • -description (optional)

    • -class or -module

      For example, -class com.novell.nds.dirxml.driver.ldap.LDAPDriverShim

    • -commandport

    • connection parameters:

      • port (mandatory)

      • address

      • fromaddress

      • handshaketimeout

      • rootfile

      • keystore

      • localaddress

      • hostname

      • kmo

      • secureprotocol

      • enforceSuiteB

      • useMutualAuth

    • -java (conditional)

    • -javadebugport

    • -password

    • -service

    • -setpasswords

    • trace file parameters (optional):

      • -trace

      • -tracefile

      • -tracefilemax

    NOTE:For more information about the parameters, see Understanding the Configuration Parameters for the Remote Loader.

  3. Save the new configuration file.

    For the Remote Loader to start automatically when your computer starts, save the file to the \jremote directory.

  4. Open a command prompt.

  5. At the prompt, enter -config filename, where filename is the name of the new configuration file. For example:

    dirxml_jremote -config <configFile> -service

    This starts the Java Remote Loader service and opens a trace window.

  6. (Optional) To stop the driver service, go to Services, then stop the service.

3.4.6 Configuring the .NET Remote Loader for Driver Instances

The Remote Loader can host the Identity Manager application shim contained in .dll file. For the Remote Loader to run, the application needs a configuration file, such as LDAPShim.txt. The Remote Loader Console utility (the Console) helps you manage all instances of Identity Manager drivers running on the server. You can start, stop, add, remove, and edit each instance of a Remote Loader. The installation program for the Remote Loader also installs the Console.

If you are upgrading, the Console detects and imports existing driver instances. For a driver to be automatically imported, its configuration file must be stored in the Remote Loader directory, located by default at c:\novell\remoteloader.net. You can then use the Console to manage the remote drivers.

You can use the command line or the Remote Loader Console to configure the Remote Loader to recognize a driver. For more information about using the command line, see Understanding the Configuration Parameters for the Remote Loader.

This section provides instructions for the following activities:

Creating a New Driver Instance in the .NET Remote Loader

  1. Open the Remote Loader Console.

    NOTE:During installation, if you selected to create a shortcut for the Console, use the Identity Manager Remote Loader Console icon on the desktop. Otherwise, run the rlconsole.exe located by default in C:\novell\remoteloader.net.

  2. To add an instance of your driver on this server, click Add.

  3. For Description, provide a short name to represent the instance.

    The Console uses this information in the default value for Config File.

  4. For Driver, select the appropriate driver.dll.

  5. For Config File, specify the path to the file where Remote Loader stores its configuration parameters. The default value is C:\novell\remoteloader.net\Description-config.txt.

  6. Specify passwords for the Remote Loader and driver object.

  7. (Optional) To use a TLS/SSL connection between the Remote Loader and the Identity Manager engine server, complete the following steps:

    1. Select Use an SSL Connection.

      NOTE:NetIQ recommends using the same version of SSL on both the Identity Manager engine server and the Remote Loader. If the versions of SSL on the server and the Remote Loader do not match, the server returns a “SSL3_GET_RECORD:wrong version number” error message. This message is only a warning, and communication between the server and Remote Loader is not interrupted. However, the error might cause confusion.

    2. For Trusted Root File (base64 format file), specify the exported self-signed certificate from the eDirectory tree’s Organization Certificate Authority. For more information, see Creating a Secure Connection to the Identity Manager Engine and Understanding the Configuration Parameters for the Remote Loader.

  8. (Optional) To configure the trace file for the Remote Loader, complete the following steps:

    NOTE:NetIQ recommends using the trace functionality only for troubleshooting issues. Having the trace enabled reduces the performance of the Remote Loader. Do not leave the trace enabled in production.

    1. For Trace Level, specify a value greater than zero that defines the level of informational messages from both the Remote Loader and the driver that you want display in a trace window. Values 1 to 4 are pre-defined by the Console. To create your own message types, specify a value of 5 or higher.

      The most common setting is trace level 3, which provides general processing, XML documents, and Remote Loader messages.

    2. For Trace File, specify the path to a file where trace messages are logged. For example, C:\novell\remoteloader.net\Test-Delimited-Trace.log.

      You must specify a unique trace file for each driver instance running on a particular computer. Trace messages are written to the trace file only if the trace level is greater than zero.

    3. For Maximum Disk Space Allowed for all Trace Logs (Mb), specify an approximate value for the most disk space that the trace file for this instance can occupy.

  9. (Optional) To allow the Remote Loader to start automatically when the computer starts, select Establish Remote Loader Service for this driver instance.

    NOTE:If the SSL connection fails due to handshaketimeout when Remote Loader establishes connection with Identity Manager engine then, update the default handshaketimeout variable to 10000 and restart both driver and remote loader.

  10. (Optional) To allow the Remote Loader to use the secure protocol while connecting to the Identity Manager engine, specify the secure protocol version in the Remote Loader configuration file. For example: secureprotocol=TLSv1_2

    For more information, see Understanding the Configuration Parameters for the Remote Loader.

    NOTE:Skip this step if you already configured the secure protocol version on the driver.

  11. (Optional) To allow the Remote Loader communication to use the protocols specified by Suite B, specify enforceSuiteB=true in the Remote Loader configuration file. This communication is supported only on TLS 1.2 protocol.

    For more information, see Understanding the Configuration Parameters for the Remote Loader.

    NOTE:Skip this step if you already enabled Suite B communication on the driver.

  12. Click OK.

Modifying an Existing Driver Instance in the .NET Remote Loader

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

  2. Click Stop.

  3. Enter the password for the Remote Loader, then click OK.

  4. Click Edit.

  5. Modify the configuration information. For more information about each parameter, see Creating a New Driver Instance in the .NET Remote Loader.

  6. To save the changes, click OK.

3.4.7 Configuring Identity Manager Drivers to Work with the Remote Loader

You can configure a new driver or enable an existing driver to communicate with the Remote Loader. You must set up an Identity Manager application shim for use with the Remote Loader.

NOTE:This section provides general information on configuring drivers so that they communicate with the Remote Loader. For driver-specific information, refer to the relevant driver implementation guide at the Identity Manager Driver documentation website.

To add a new or modify an existing Driver object in either Designer or iManager, you must configure settings that enable the driver instance for the Remote Loader. For more information about the parameters used in this section, see Understanding the Configuration Parameters for the Remote Loader.

  1. From Overview, select the Identity Manager Driver object.

  2. In the properties of the Driver object, complete the following steps:

    1. For Driver Module, select Connect to Remote Loader.

    2. For Driver Object Password, specify the password that the Remote Loader uses to authenticate itself to the Identity Manager engine server.

      This password must match the password for the driver object defined in the Remote Loader.

    3. For Remote Loader Connection Parameters, specify the information required to connect to the Remote Loader. Use the following syntax:

      hostname=xxx.xxx.xxx.xxx port=xxxx kmo=certificatename localaddress=xxx.xxx.xxx.xxx

      where

      hostname

      Specifies the IP address for the server that hosts the Remote Loader. For example, hostname=192.168.0.1.

      port

      Specifies the port that the Remote Loader listens on. The default is 8090.

      kmo

      Specifies the key name of the Key Material Object containing the keys and certificate used for SSL connections. For example, kmo=remotecert.

      localaddress

      Specifies the source IP address if more than one IP addresses are configured on the server that hosts the Identity Manager engine.

    4. For Remote Loader Password, specify the password required for the Identity Manager engine (or Remote Loader shim) to authenticate to the Remote Loader.

  3. Define a security-equivalent user.

  4. Click Next, then click Finish.

3.4.8 Configuring Mutual Authentication with the Identity Manager Engine

You can configure mutual authentication to ensure secure communication between the Remote Loader and the Identity Manager engine. Mutual authentication uses certificates for handshake instead of passwords. The Remote Loader and the Identity Manager engine authenticate each other by exchanging and validating the public key certificate or digital certificate issued by the trusted Certificate Authorities (CAs) or self-signed certificates. If mutual authentication succeeds, the Remote Loader authenticates to the engine. Synchronization traffic occurs after both the Remote Loader and the Identity Manager engine establish trust that they are communicating with an authorized entity.

Perform the following tasks to configure mutual authentication:

Exporting Certificates for the Identity Manager Engine and the Remote Loader

For mutual authentication to work properly, you need a server certificate for the engine and a client certificate for the Remote Loader. You can export the certificates from eDirectory or import them from a third-party vendor. In most cases, you will export a server certificate from eDirectory with no further investment. In some cases, you might want to export a third-party client certificate for the Remote Loader.

Exporting a Certificate from eDirectory

A certificate object in the Identity Vault is called Key Material Object (KMO). This object securely contains both the certificate data including the public key and the private key associated with the certificate used for SSL connections. For mutual authentication, you need two KMOs, each for the engine and the Remote Loader.

You can export an existing KMO or create a new KMO and then export it. The process of creating a client KMO and a server KMO is different.

Creating KMOs

You must create a server KMO before creating a client KMO. To create a KMO, perform the following steps:

  1. Log in to NetIQ iManager.

  2. In the left side pane, select NetIQ Certificate Server > Create Server Certificate.

  3. Select the server to own the certificate that you created.

  4. Specify a nickname for the certificate.

    For example, serverkmo for server certificate and clientkmo for client certificate.

  5. Select Custom in the certificate creation method, then click Next.

  6. Keep the default Organizational Certificate Authority selection and click Next.

  7. (Conditional) If you are creating client KMO.

    1. Select Enable Extended key usage.

    2. Select Custom, then select User Authentication.

    3. Click Next.

    NOTE:For server KMO, keep the default selections and click Next.

  8. Specify Validity period for the KMO.

    Ensure that iManager server time is synchronized with your Identity Manager components and the connected application.

  9. Review the summary, click Finish, then click Close.

  10. Repeat these steps to create a client KMO.

Exporting KMOs

Export the KMOs from eDirectory that the engine and the Remote Loader will use for authenticating with each other.

To export the KMO for the Identity Manager engine, run the DirXML Command Line (dxcmd) utility:

dxcmd -user <admin DN> -password <password of admin> -exportcerts <kmoname> <server|client> <java|native|dotnet> <output dir>

where

  • user specifies the name of a user with administrative rights to the driver.

  • password specifies the password of the user with administrative rights to the driver.

  • exportcerts exports the certificates and private/public keys from eDirectory. You must specify whether you are exporting a server or a client certificate, the type of driver that will use the certificate, and a destination folder where the command will store this information.

Example1: dxcmd -user admin.sa.system -password novell -exportcerts serverkmo server java 'C:\certs'

This command generates the serverkmo_server.ks file in the C:\certs directory. The default keystore password and key password is dirxml.

Example 2: dxcmd -user admin.sa.system -password novell -exportcerts serverkmo server java '/home/certs'

This command generates the serverkmo_server.ks file in the /home/certs/ directory. The default password for the keystore is dirxml.

When running the dxcmd command for exporting the KMO for the Remote Loader, the following considerations apply:

  • The dxcmd utility runs in LDAP mode. When you use it for the first time, it prompts for specifying the choice of trusting the certificate from eDirectory. Depending on your environment, you can choose to trust the certificate only for the current session, for the current and future sessions, trust all certificates, or select not to trust the certificate.

  • If the Remote Loader is running on the Identity Manager server, run the command in either LDAP or dot format. If the Remote Loader is installed on a separate server, run the command only in LDAP format.

  • Specify the -host parameter in the command to resolve the server IP address or hostname to be able to authenticate with the Identity Manager server.

Run the command using the following syntax:

dxcmd -dnform ldap -host <IP address of the host> -user <admin DN> -password <password of admin> -exportcerts <kmoname> <client> <java|native|dotnet> <output dir>

Table 3-2 Example commands for different types of drivers

Type of Driver

Command

Output

Java Driver

dxcmd -dnform ldap -host 194.99.90.218 -user cn=admin,ou=sa,o=system -password novell -exportcerts clientkmo client java 'C:\certs'

clientkmo_client.ks file in the C:\certs directory

The default password for the keystore is dirxml.

The default Private Key Password is dirxml.

Native Driver

dxcmd -dnform ldap -host 194.99.90.218 -user cn=admin,ou=sa,o=system -password novell -exportcerts clientkmo client native 'C:\certs'

clientkmo_clientcert.pem, clientkmo_clientkey.pem, and trustedcert.b64 files in the C:\certs directory.

The default key password is dirxml.

.NET Driver

dxcmd -dnform ldap -host 194.99.90.218 -user cn=admin,ou=sa,o=system -password novell -exportcerts clientkmo client dotnet 'C:\certs'

clientkmo_clientcert.pfx and trustedcert.b64 files in the C:\certs directory.

The default key password of clientkmo_clientcert.pfx is dirxml.

Exporting a Third-Party Certificate for Remote Loader

To use third party certificates with the Remote Loader, you need to export a certificate in the .pfx file and a trusted root file in Base 64 format and then convert the .pfx certificate to the format that the driver uses. For example, a native driver requires the private key and the certificate key in .pem format while a Java driver requires the keystore in .jks format. The .NET driver uses the file in .pfx format. So you need not convert the file for a .NET driver.

Native driver

Complete the following steps:

  1. Retrieve the private key in .pem format from the .pfx file.

    Enter a command, such as openssl pkcs12 -in servercert.pfx -out serverkey.pem

  2. Retrieve the certificate key in .pem format from the .pfx file.

    Enter a command, such as openssl pkcs12 -in servercert.pfx -out servercert.pem

Java driver

Create a Java keystore from the .pfx file. Enter the following command:

keytool -importkeystore -srckeystore servercert.pfx -srcstoretype pkcs12 -destkeystore servercert.jks -deststoretype JKS

This command prompts you to type source keystore password (srckeystore passwd) and destination keystore password (dest keystorepasswd). Enter these passwords appropriately.

As a final step, specify the information in the Remote Loader configuration file depending on the type of the driver. For more information, see Enabling a Driver for Mutual Authentication.

Enabling a Driver for Mutual Authentication

You enable a driver communication for mutual authentication by performing the following tasks:

Configuring a Driver Using KMO or Keystore

You can configure the driver by using KMO or keystore in Designer or iManager.

Designer

Before configuring a driver using KMO or keystore in Designer, ensure you have completed the basic driver configuration as follows:

  1. Open your project in Designer.

  2. In the palette of the Modeler view, select the driver that you want to create.

  3. Drag the icon for the driver onto the Modeler view.

  4. Follow the steps in the installation wizard.

  5. In the Remote Loader window, select yes.

    1. Host name: Specify the hostname or IP address of the server where the driver’s Remote Loader service is running. For example, enter Host name as 192.168.0.1. If you do not specify a value for this parameter, the value defaults to localhost.

    2. Port: Specify the port number where the Remote Loader is installed and is running for this driver. The default port number is 8090.

  6. Click Next.

  7. Follow the rest of the instructions in the wizard until you finish installing the driver.

  8. Review the summary of tasks that will be completed to create the driver, then click Finish.

To modify the driver configuration using KMO or Keystore

  1. In the Outline view of Designer, right-click the driver.

  2. Select Properties.

  3. In the navigation pane, select Driver Configuration.

  4. In Authentication, select Enable Mutual Authentication and specify the following parameters:

    KMO

    Specifies the name of the server KMO.

    Other parameters

    Specifies the rootfile and its absolute path.

    KeyStore file

    Specifies the absolute path of the keystore file.

    Key alias

    Specifies the name of the server KMO.

  5. Set Key Store Password.

  6. Set Key Password.

NOTE:By default, the Key Store Password and Key Password is set to dirxml.

You can also set Keystore and key password using dxcmd command.

dxcmd -user <administrative_user> -password <admin_password>
  1. Select Driver Operations.

  2. Select the driver that you want to set keystore and key password.

  3. Select Password Operations.

  4. Select Set Keystore password for Mutual Authentication and enter the Keystore password.

  5. Select Set Key password for Mutual Authentication and enter the key password.

iManager

To modify the configuration in iManager:

  1. Launch iManager.

  2. In Identity Manager Administration, select Identity Manager Overview.

  3. In Overview, select the Identity Manager driver set.

  4. Select Edit Properties for the driver that you want to configure.

  5. In Driver Configuration > Driver Module > Connect to Remote Loader > Remote Loader Connection Parameters.

  6. (Windows) Specify the following connection details:

    1. In Remote loader connection parameters, specify the following connection details:

      KMO=<server_KMO_name>
      rootfile=<absolute path to the file>

      For example,

      KMO=serverkmo
      rootfile=C:\cacert.b64
    2. Set the Application password.

    3. Select Enable Mutual Auth.

    4. To use keystore method, specify the following:

      Key alias

      Specifies the name of server KMO and set Key password.

      For example: serverKMO

      Keystore file

      Specifies the absolute path of the keystore file and set the Keystore password.

      For example: C:\certs\serverkmo_server.ks

    5. Click Apply, then click OK.

    NOTE:When you enable mutual authentication, configuring Remote Loader Password and Driver Object Password are not necessary.

Configuring the Remote Loader for Driver Instances

You must configure the driver instance in the Remote Loader configuration file. Ensure that you specify the absolute path to the directory that stores the key file, certificate file, and the root file in the Remote Loader configuration file for a driver.

Adding a New Remote Loader Driver Instance on Windows
  1. Right-click on the Identity Manager Remote Loader Console application and select Run as administrator.

  2. Click Add to add a new Remote Loader instance.

  3. Specify the Description and select the type of driver.

  4. Specify the Connection port that is used to connect Remote Loader and Identity Manager engine.

  5. Specify the Command port for your Remote Loader instance.

  6. Select Mutual Authentication and specify the required type of driver:

    • Java driver: Browse the path of the keystore file that contains the certificate. Thekeystore file must contain at least one public/private key pair.

      Keystore File

      Specifies the path to the Java keystore file you want to use for authentication. The keystore file contains encryption keys and certificates. For example, clientkmo_client.ks in the C:\certs\ directory created by dxcmd in Exporting a Certificate from eDirectory.

      Key Alias

      Specifies the name of the public/private key pair in the keystore file that you want to use for symmetric key generation. For example, clientkmo.

      Keystore Password

      Specifies the password used to load the keystore file.

      Private Key Password

      Specifies the password for the private key stored in the keystore. Identity Manager uses this key for encrypting the SSL communication.

    • Native driver: Browse the path to the key file that stores the certificate for authentication. The key file must be in Base 64 format.

      Key File

      Specifies the path to the file that stores the key for authentication. For example, clientkmo_clientkey.pem file in the C:\certs\ directory created by dxcmd.

      Key Password

      Specifies the password for the private key used for authentication.

      Certificate File

      Specifies the file where the certificates are stored. The certificate file must be in Base 64 format. For example, clientkmo_clientcert.pem in the C:\certs\ directory created by dxcmd in Exporting a Certificate from eDirectory.

      Trusted Root File

      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 trusted root file must be in Base 64 format. For example, trustedcert.b64 files in the C:\certs\ directory created by dxcmd in Exporting a Certificate from eDirectory.

    • .NET driver: Browse the path to the key file that stores the certificate for authentication.

      Key File

      Specifies the path to the file that stores the key for authentication. For example, clientkmo_clientcert.pfx in the in the C:\certs\ directory created by dxcmd in Exporting a Certificate from eDirectory.

      Key Password

      Specifies the password for the private key used for authentication.

      Trusted Root File

      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 trusted root file must be in Base 64 format. For example, trustedcert.b64 file in the C:\certs\ directory created by dxcmd in Exporting a Certificate from eDirectory.

    For more information about the output files generated for this driver using dxcmd tool, see Table 3-2, Example commands for different types of drivers.

Configuring the Remote Loader on Windows

You must configure the driver instance in the Remote Loader configuration file. Ensure that you specify the absolute path to the directory that stores the keystore file, key file, certificate file, and the root file in the Remote Loader configuration file for a driver.

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

  2. Click Stop.

  3. Enter the password for the Remote Loader, then click OK.

  4. Click Edit and perform Step 6 from Adding a New Remote Loader Driver Instance on Windows

  5. Click OK.

Configuring the Remote Loader on UNIX or Linux

Modify the Remote Loader configuration file for a driver to include the content for enabling mutual authentication. The file is located in the /opt/novell/dirxml/doc directory.

To modify the configuration:

  1. Log in to the server where you installed the driver and Remote Loader.

  2. Stop the Remote Loader.

    For example, enter the following command:

    rdxml -config /home/drivershim.conf -u
  3. Provide keystore or key password based on the Remote Loader type:

    Java Remote Loader:

    Specify the combination of keystore password and key password using the following syntax:

    dirxml_jremote -config /home/drivershim.conf -ksp <keystorepassword> -kp <keypassword>

    For example,

    dirxml_jremote -config /home/drivershim.conf -ksp dirxml -kp dirxml
    Native Remote Loader:

    Specify the keypassword using the following syntax:

    dirxml_jremote -config /home/drivershim.conf -kp <keypassword>

    For example,

    dirxml_jremote -config /home/drivershim.conf -kp dirxml
  4. In a text editor, open the Remote Loader configuration file for the driver.

  5. Add the content required for enabling mutual authentication to the file.

    • For example, for a Java driver, add this entry:

      -connection "port=8090 useMutualAuth=true keystore='/home/certs/clientkmo_client.ks' key='clientkmo' 
    • For example, for a Native driver, add this entry:

      -connection "useMutualAuth=true port=8090 rootfile='/home/certs/trustedcert.b64' certfile='/home/certs/clientkmo_clientcert.pem' keyfile='/home/certs/clientkmo_clientkey.pem' certform=PEM keyform=PEM" 
  6. Save and close the file.

  7. Restart the driver.

3.4.9 Starting and Stopping the Remote Loader

The Remote Loader is either a service or a daemon, which occasionally must be restarted. This chapter explains how to stop and start the Remote Loader.

Starting a Driver Instance in the Remote Loader

You can configure each platform to automatically start a driver instance when the host computer starts. You can also manually start an instance.

Starting Driver Instances on UNIX or Linux

NetIQ provides two ways that you can start a driver instance for the Remote Loader on UNIX or Linux computers:

Starting Driver Instances Automatically on UNIX or Linux

You can configure a driver instance for the Remote Loader to start automatically when the computer starts. Place your configuration file in the /etc/opt/novell/dirxml/rdxml directory.

Using the Command Line to Start Driver Instances on UNIX or Linux

For Linux platforms, the binary component rdxml supports command line functionality for the Remote Loader. This component is located by default in the /usr/bin/ directory.

For more information about the parameters used in this section, see Understanding the Configuration Parameters for the Remote Loader.

  1. Open a command prompt.

  2. To specify the passwords for authenticating the driver instance to the Identity Manager engine, enter one of the following commands:

    • Linux: rdxml -config filename -sp password password

    • UNIX: dirxml_jremote -config config_file -sp password password

  3. To start the driver instance, enter the following command:

    • Linux: rdxml -config filename

    • UNIX: dirxml_jremote -config filename

  4. Log in to iManager, then start the driver.

  5. Confirm that the Remote Loader is working properly.

    • Linux: Use the ps command or a trace file to determine whether the command and connection ports are listening.

    • UNIX: Monitor the Java Remote Loader by using the tail command on the tracefile:

      tail -f trace filename

      If the last line of the log shows the following text, the loader is successfully running and awaiting connection from the Identity Manager remote interface shim:

      TRACE: Remote Loader: Entering listener accept()

    The Remote Loader loads the Identity Manager application shim only when the Remote Loader is in communication with the remote interface shim on the Identity Manager engine server. This means, for example, that the application shim shuts down if the Remote Loader loses communication with the server.

Starting Driver Instances on Windows

NetIQ provides three ways that you can start a driver instance for the Remote Loader on Windows computers:

Starting Driver Instances Automatically on Windows

You can configure a driver instance for the Remote Loader to start automatically when the Windows computer starts.

  1. Open the Remote Loader Console.

    During installation, if you created a shortcut for the Remote Loader Console, use the Identity Manager Remote Loader Console icon on the desktop. Otherwise, run the rlconsole.exe located by default in C:\novell\remoteloader\nnbit.

  2. Select a driver instance, then click Edit.

  3. Select Establish a Remote Loader service for this driver instance.

  4. Save your changes, and then close the console.

Using the Console to Start Driver Instances on Windows
  1. Open the Remote Loader Console.

    During installation, if you created a shortcut for the Remote Loader Console, use the Identity Manager Remote Loader Console icon on the desktop. Otherwise, run the rlconsole.exe located by default in C:\novell\remoteloader\nnbit.

  2. Select a driver instance, then click Start.

Using the Command Line to Start Driver Instances on Windows

The dirxml_remote.exe file supports command line functionality for the Remote Loader. The executable is located by default in the c:\novell\RemoteLoader directory. For more information about the parameters used in this section, see Understanding the Configuration Parameters for the Remote Loader.

  1. Open a command prompt.

  2. To specify the passwords for authenticating the driver instance for the Remote Loader to the Identity Manager engine, enter the following command:

    dirxml_remote -config filename -setpasswords password password

    For example:

    dirxml_remote -config config.txt -sp Novell4 idmpwd6
  3. To start the driver instance, enter the following command:

    dirxml_remote -config filename

    For example:

    dirxml_remote -config config.txt
  4. Log in to iManager, then start the driver.

  5. Confirm that the Remote Loader is working properly.

    The Remote Loader loads the Identity Manager application shim only when the Remote Loader is in communication with the remote interface shim on the Identity Manager engine server. This means, for example, that the application shim shuts down if the Remote Loader loses communication with the server.

  6. (Conditional) If you did not previously install the Remote Loader as a Win32 service, enter the following command:

    dirxml_remote -config filename -service install

    For example:

    dirxml_remote -config config.txt -service install

Stopping a Driver Instance in the Remote Loader

Each platform has a different method for stopping a driver instance in the Remote Loader. For more information about the parameters used in this section, see Understanding the Configuration Parameters for the Remote Loader.

NOTE:

  • If you run multiple instances of the Remote Loader on a UNIX or Linux computer, include the -cp command port option to ensure that the Remote Loader can stop the appropriate instance.

  • When you stop a driver instance, you must have sufficient rights or specify the Remote Loader password. For example, the Remote Loader is running as a Windows service. You have sufficient rights to stop it. You enter a password, but realize that it is incorrect. The Remote Loader stops anyway, because the Remote Loader does not actually “accept” the password. Instead, it ignores the password because the password is redundant in this case. If you run the Remote Loader as an application rather than as a service, the password is used.

To stop a driver instance:

Linux

Enter the rdxml -config filename -u command. For example:

rdxml -config config.txt -u
UNIX

Enter the dirxml_jremote -config filename -u command. For example:

dirxml_jremote -config config.txt -u
Windows

Use the Remote Loader Console.

During installation, if you created a shortcut for the Remote Loader Console, use the Identity Manager Remote Loader Console icon on the desktop. Otherwise, run the rlconsole.exe located by default in C:\novell\remoteloader\nnbit.

Stopping, Starting, or Restarting a Driver in Designer

  1. Open a project in the Modeler, then right-click the driver line.

  2. Click Live, then click the appropriate option to stop, start, or restart the driver.

Stopping, Starting, or Restarting a Driver in iManager

  1. In the Roles and Tasks view, click Identity Manager > Identity Manager Overview.

  2. In the Search in field, specify the fully distinguished name of the container where you want to start searching and then click , or click to browse for and select the container in the tree structure.

  3. Click the upper right corner of the driver icon whose status you want to change, then click the appropriate option to stop, start, or restart the driver.

3.4.10 Verifying the Configuration

For more information about starting and stopping the Remote Loader, see Starting and Stopping the Remote Loader.

  1. Start the driver using iManager.

  2. Manage Remote Loader using any of the following ways:

    Remote Loader user interface
    1. Right-click the Identity Manager Remote Loader console and select Run as administrator.

    2. You can Start, Stop, Add, Remove, and more operations using Remote Loader interface.

    NOTE:To run Remote Loader as a service, select Establish a Remote Loader service for this driver instance. De-selecting this option runs Remote Loader as an application.

    Remote Loader console

    Navigate to the Remote Loader installed location and run the following commands in the command prompt:

    1. To start or load the Remote Loader instance:

      For Java Remote Loader:

      dirxml_jremote -config <configuration_filename> -ksp <keystore_password> -kp <keypassword>
      
      dirxml_jremote -config <configuration_filename>

      For Native Remote Loader:

      dirxml_remote -config <configuration_filename> -ksp <keystore_password> -kp <keypassword>
      
      dirxml_remote -config <configuration_filename>

      For .Net Remote Loader:

      RemoteLoader.exe  -config <configuration_filename> -ksp <keystore_password> -kp <keypassword>
      
      RemoteLoader.exe  -config <configuration_filename>
    2. To stop or unload the Remote Loader instance, append -u at the end of the previous command. For example

      For Java Remote Loader:

      dirxml_jremote -config <configuration_filename> -u

      For Native Remote Loader:

      dirxml_remote -config <configuration_filename> -u

      For .Net Remote Loader:

      RemoteLoader.exe  -config <configuration_filename> -u

    NOTE:To run the Remote Loader instance as a service use the following command:

    dirxml_remote -config config.txt -service install