Novell Documentation: Nsure Identity Manager 2.0 - Using the Remote Loader Service

Using the Remote Loader Service

The Remote Loader Service allows DirXML drivers running on one platform to communicate with the DirXML engine running on a different platform.

For example, the DirXML Driver for PeopleSoft must operate on the Windows 2000 platform. The Remote Loader lets you run the PeopleSoft driver on a Windows platform, and enables you to synchronize data with the DirXML engine running on a Solaris, Linux, or NetWare platform.

A new feature in Identity Manager 2 is the Remote Loader Console. The console runs on Windows and allows you to easily manage all of your remote loader instances from a single location. For information on using the console, refer to Using the Remote Loader Console on Windows.

This section contains information on the following:

Using the Remote Loader Console on Windows

The Remote Loader Console allows you to easily manage remote instances of your DirXML drivers. Use the Console to add and configure new remote loader instances on the local computer, to edit configuration settings, and to start and stop Remote Loader instances.

NOTE: If you are upgrading to Identity Manager 2, the Console detects and imports existing instances of the Remote Loader (configurations must be stored in the /remoteloader directory to be imported automatically.) You can then use the Console to manage these remote drivers. Do not continue to use the Remote Loader Configuration Wizard that shipped prior to Identity Manager 2. You might encounter errors when using the Wizard and Console together.

When you install the Remote Loader service, an icon is installed on your desktop. Double-click the icon to run the Remote Loader Console.

Entering Information for Remote Loader Instances

When configuring a new remote loader instance, you will be prompted for the following information:

Remote Driver Configuration

Description: Specify a description to identify the remote loader instance.
Driver: Browse to and select the appropriate shim for your driver.
Config File: Specify a name for the configuration file. The Remote Loader Console places configuration parameters into this text file.

Communication

IP Address: Specify the IP address on which the Remote Loader service listens.
Connection Port - DirXML Server: Specify the connection parameters to the DirXML server running the remote driver. The default TCP/IP port for this connection is 8090. With each new instance you create, the port number automatically increases by one.
Command Port - Local Host Communication Only: Specify the TCP port number on which a Remote Loader service listens for commands such as Stop, Change Trace Level, and so forth. Each instance of the Remote Loader that is running on a particular computer must have a different command port number. The default command port is 8000. With each new instance you create, the port number automatically increases by one.
NOTE: You can run multiple instances of the Remote Loader (on the same server hosting different driver instances) by specifying different connection ports and command ports.

Remote Loader Password

Password: This password is used to control access to a Remote Loader instance for a driver. It must be the same password you specify when configuring the driver to connect remotely (via the Driver Parameters page in Novell iManager.)
Confirm: Re-enter the password to confirm.

Driver Object Password

Password: This password is used by the Remote Loader to authenticate itself to the DirXML server. It must be the same password you specify when configuring the driver to connect remotely (via the Driver Parameters page in Novell iManager.)
Confirm: Re-enter the password to confirm.

Secure Socket Link (SSL)

Use an SSL Connection: Check this option to specify an SSL connection.
Trusted Root File: Browse to the Java* keystore file containing the appropriate trusted root certification. This is the exported self-signed certificate from the eDirectory tree's Organization Certificate Authority. The certificate must be exported in Base64 format. For example, MY-TREE CA.b64.

Trace File

Trace Level: Set a trace level greater than zero for the Remote Loader instance to display a trace window that contains informational messages from both the loader and the driver.
Trace File: Specify a trace filename where trace messages will be written. Each Remote Loader instance running a particular machine must use a different trace file. Trace messages are written to the trace file only if the trace level is greater than zero.
Maximum Disk Space Allowed for all Trace Logs (MB): Specify the approximate maximum size that trace file data can occupy on disk. If Unlimited is not selected, the default value is set to 4096 MB or 4 gigabytes.

Establish a Remote Loader Service for this Driver Instance

Check this option to configure the Remote Loader instance as a service. This automatically starts the Remote Loader when the computer boots.

Configuring SSL between the DirXML Engine and the Remote Loader

The following instructions provide information regarding how to create and export certificates, and how to configure your SSL connection between the DirXML Engine and the Remote Loader for secure data transfers.

Creating and Exporting a Certificate

In Novell iManager, click Novell Certificate Server > Create Server Certificate.
Select the server that will own the certificate and give it a certificate nickname. (For example, remotecert.)

IMPORTANT: Write down the certificate nickname, because you will use this for the KMO name in the driver's remote connection parameters. (For example, remotecert)
Leave the Creation method set to Standard, then click Next.
Review the Summary, then click Finish.

You've just created a server certificate. You now need to export the Trusted Root certificate.
Click eDirectory Administration > Modify Object.
Browse to the Certificate Authority in the Security container, then click OK.

The Certificate Authority (CA) is named after the tree name (Treename-CA.Security).
Click the Certificates tab, then click Export.
In the Export Certificate Wizard, select No, then click Next. You do not want to export the private key with the certificate.
Choose to export the file in Base64 format, then click Next.
Click the link to Save the Exported Certificate to a File, specify a location, then click Save.
Copy this file to a secure location that can be accessed by Remote Loader service.

You need to configure the Remote Loader parameters in the driver to use SSL. Refer to Configuring the Driver to use a SSL Connection for more information.

Configuring the Driver to use a SSL Connection

Before configuring your SSL connection, make sure that you have exported the Trusted Root certificate and that the Remote Loader has access to the exported file. Refer to Creating and Exporting a Certificate for detailed instructions.

You now need to modify the driver parameters to use this certificate.

In Novell iManager, click DirXML Management > Overview.
Browse to the driver object for which you want to configure an SSL connection.
Append kmo=kmo object nickname to the Remote Loader Connection parameters. For example, hostname=198.162.0.1 port=8090 kmo=remotecert

If you used spaces in the certificate name, you need to enclose the KMO object nickname in quotation marks.

HINT: The KMO object name is the nickname value you specified in Step 2 of Creating and Exporting a Certificate.

Configuring a DirXML Driver with the Remote Loader

Complete these tasks to configure a driver you want to use with the Remote Loader:

Installing the Remote Loader Service and Drivers

For information on installing the Remote Loader Service and remote DirXML drivers, refer to Installing Identity Manager Components .

Configuring the Driver Object Properties for the Remote Loader

After you have installed the Remote Loader and DirXML Driver, you must also specify parameters for the Remote Loader on the driver object.

In Novell iManager, click DirXML Management > Overview.
Browse to the driver object you want to configure remotely.
Click the driver status icon, then click Edit Properties.
The Driver Configuration parameters will display. Enter the following Authentication information to configure the Remote Loader settings:
- Remote Loader Connection parameters: Enter the communications parameters for the Remote Loader. You enter three parameters as a series of "name=value" pairs for these connection parameters. This is an example of the full communications parameters: hostname=198.162.0.1 port=8090 kmo=remotecert.
  - hostname: Specifies the address or name of the machine on which the Remote Loader will run. For example, hostname=198.162.0.1. (If you don't enter this communication parameter, this value defaults to "localhost.")port: Specifies the port on which the Remote Loader will accept connections from the remote interface shim. For example, port=8090. (If you don't enter this communication parameter, this value defaults to "8090.")kmo: Specifies the key name of the Key Material Object containing the keys and certificate used for SSL. For example, kmo=remotedrivercert. (If you don't enter this communication parameter, no value will be stored. This means, there will be no SSL.)
- Application Password: Enter the password of the application user ID. This is used to pass eDirectory subscription information to the application.
- Remote Loader Password: Enter the password for the Remote Loader. This password is used by the Remote Interface shim to authenticate itself to the Remote Loader.
NOTE: When entering passwords for the application and the Remote Loader, you must set or reset both of these passwords at the same time.
Click OK to apply your changes.

Configuring the Remote Loader on Solaris and Linux

You can configure the Remote Loader to work in either a Java or a native environment. In a native environment, the binary component, rdxml, loads the JVM and the Java Remote Loader to support Java drivers using a native interface. It also loads native drivers.

Setting Environment Variables on Solaris and Linux

After installing the Remote Loader, you can set the environmental variable RDXML_BASE_PATH to point to your preferred directory. This directory will then be taken as the base path for files that are subsequently created. To set the value of the RDXML_BASE_PATH variable, enter the following commands:

set RDXML_BASE_PATH=<path>
export RDXML_BASE_PATH

Configuring the Remote Loader for Remote Drivers

To configure the Remote Loader for hybrid drivers, enter the following command:

rdxml option_name

For more information on the options associated with the rdxml component, refer to Setting Command Line Options and Parameters.

Configuring the Remote Loader with Open SSL on UNIX

To configure the Remote Loader with jsse:

Edit the java.security file in the /jre/lib/security/ directory to add the following line:

security.provider.n=com.sun.net.ssl.internal.ssl.Provider

Specify the value of the variable n depending upon the number of security providers you already have. For example, if this is your second security provider, add the line:

security.provider.2=com.sun.net.ssl.internal.ssl.Provider
Set the CLASSPATH variable to the path of the jsse.jar file in the /usr/lib/dirxml/classes/ directory.
Export the Trusted Root Certificate of a KMO from the eDirectory tree to the machine hosting the Remote Loader. In case of an FTP transfer, export the file in binary mode.
To run the keytool, enter the following command:

keytool -import -alias TrustedRoot -file <pathname_with_filename>
If you are unable to execute the command in Step 4, you might have multiple java.security files. In that case, enter the following command:

java sun.security.tools.KeyTool -import -alias TrustedRoot -file <pathname_with_filename>

Running the Remote Loader Configuration Wizard

You run the Remote Loader Configuration Wizard to set the communication and configuration parameters to run the Remote Loader. You can only run this Wizard on NetWare and Windows NT/2000. You run the Remote Loader Configuration Wizard on the application server where you installed the Remote Loader.

To run the Remote Loader Configuration Wizard:

Run the dirxml_remote.exe found in c:\novell\remoteloader with no command line parameters to launch the wizard.
Use the information in the following table to set parameters for the Remote Loader:

Parameters	Description
CommandPortNumber	The TCP port number on which a Remote Loader instance listens for commands such as Unload, Change Trace Level, Trace Window On/Off, and so forth. Each instance of the Remote Loader that is running on a particular machine must have a different command port number.
Configuration File Name	The configuration file is a text file into which the Remote Loader configuration parameters are placed. Generally, this is in the same directory as the Remote Loader executable.
Java Class Name	The name of the Java class that will be instantiated for the application driver component of the driver if the driver is a Java driver such as the Delimited or LDAP driver. The Java class can either be in the c:\novell\remoteloader\classes directory in a .class file or in the c:\novell\remoteloader\lib directory in a .jar file.
DLL File Name	Specify the name of the native library that implements the driver if the driver is a native driver such as the Active Directory or PeopleSoft drivers. If a native module is specified, it should be located in the same directory as dirxml_remote.exe, or the full path should be provided.
Port Number	The connection port number is the TCP port on which the Remote Loader will listen for connections from the DirXML server.
Address	The IP address on which the loader will listen.
Use SSL	Mark to specify SSL.
Trusted Root File	If you already have a Java keystore file containing the appropriate trusted root certificate, you can specify this file in the field. This is the exported "Self-Signed Certificate" from the eDirectory tree's Organizational Certificate Authority. The certificate must be exported in Base 64 format.
Keystore Password	This field only appears if the trusted root name has an extension of .keystore. Enter the access password for the keystore file in this field.
Trace Level	Set a trace level greater than zero for the Remote Loader instance to display a trace window that contains informational messages from both the loader and the driver.
Trace File	Specify a trace file for trace messages to be written to a file. Each Remote Loader instance running a particular machine must use a different trace file. Trace messages will only be written to the trace file if the trace level is greater than zero.
Install This Remote Loader Instance as a Service	Check this to set up the Remote Loader as a service to start the Remote Loader automatically when the machine boots.
Remote Loader Password	This is used to control access to a Remote Loader instance that is hosting a driver. It must be the same password that is specified as the Remote Loader password using the Driver Object Properties page. Confirm the password in the Confirm password field.
Driver Object Password	The Driver object password is used by the Remote Loader to authenticate itself to the DirXML server. It must be the same password as the Driver Object Password using the Driver Object Properties page.

Setting Command Line Options and Parameters

You can configure the Remote Loader by using command line options and parameters without using the Remote Loader Configuration Wizard. In general, the command line parameters set the shim module or class, connection parameters between the shim and the DirXML server, and the trace level. Other parameters include opening and closing the trace window, setting passwords, and determining whether the Remote Loader instance is a Windows service. You specify command line options and parameters in a configuration file.

Open or create a configuration file in a text editor.
Enter the commands in the following table to configure the Remote Loader:

Option	Secondary Name	Parameter	Description
-class	-cl	Java class name	Specifies the Java class name of the DirXML application shim that is to be hosted. The class option and the module option are mutually exclusive.
-commandport	-cp	port number	Specify the TCP/IP port that the Remote Loader instance uses for control purposes. If the Remote Loader instance is hosting an application shim, the command port is the port on which another Remote Loader instance will communicate with the instance hosting the shim. If the Remote Loader instance is sending a command to an instance that is hosting an application shim, the command port is the port on which the hosting instance is listening. If not specified, the default command port is 8000. Multiple instances of the Remote Loader can be run on the same server hosting different driver instances by specifying different connection ports and command ports.
-config	None	filename	Specifies a configuration file. The configuration file can contain any command line options except config. Options specified on the command line override options specified in the configuration file.
-connection	-conn	connection configuration string	This specifies the parameters for the connection to the DirXML server running the remote interface shim. The default connection method for the Remote Loader is TCP/IP using SSL. The default TCP/IP port for this connection is 8090. Multiple instances of the Remote Loader can be run on the same server hosting different driver instances by specifying different connection ports and command ports.
-java	-j	None	Specifies that the passwords are to be set for a Java shim instance. This option is only useful in conjunction with the setpasswords option. If -class is specified with -setpasswords, this option is not necessary.
-module	-m	modulename	Specifies the module containing the DirXML application shim that is to be hosted. The module option and the class option are mutually exclusive.
-password	-p	password	Specifies the password for command authentication. This password must be the same as the first password specified with setpasswords for the loader instance being commanded. If a command option (unload, tracechange, etc.) is specified and the password option is not specified, the user will be prompted to enter the password for the loader that is the target of the command.
-service	-serv	None, or install/uninstall	To install an instance as a service, use the install argument together with any other arguments necessary to host an application shim. For example, the arguments used must include -module, but any argument can include -connection, -commandport, and so forth. To uninstall an instance running as a service, use the uninstall argument together with any other arguments necessary to host the application shim. Note that this option installs the Win32* service; this option does not start the service. The no-argument version of this option is only used on the command line to an instance being run as a Win32 service. This is automatically set up when installing an instance as a service.
-setpasswords	-sp	password password	Specify the password for the Remote Loader instance and the password of the Driver object of the remote interface shim with which the Remote Loader will communicate. The first password in the argument is the password for the Remote Loader. The second password in the argument is the password for the Driver object associated with the remote interface shim on the DirXML server. Both passwords must be specified. This is a configuration option. Using this option configures the Remote Loader instance with the passwords specified but does not load a DirXML application shim or communicate with another loader instance.
-trace	-t	integer	Specify the trace level. This is only used when hosting an application shim. Trace levels correspond to those used on the DirXML server.
-tracechange	-tc	integer	Command a Remote Loader instance that is hosting an application shim to change its trace level. Trace levels correspond to those used on the DirXML server.
-tracefile	-tf	filename	Specify a file to which to write trace messages. Trace messages will be written to the file if the trace level is greater than zero. Trace messages will be written to the file even if the trace window is not open.
-tracelfilechange	-tfc	None, or filename	Command a Remote Loader instance that is hosting an application shim to start using a trace file, or to close one already in use and use a new one. Using the no-argument version of this option will cause the hosting instance to close any trace file being used.
-unload	-u	None	Unload the Remote Loader instance. If the Remote Loader is running as a Win32 service this will stop the service.
-window	-w	On/Off	Turn the trace window on or off in a Remote Loader instance. This option is not available on Solaris or Linux platforms.
-wizard	-wiz	None	Launches the Configuration Wizard. Note that running dirxml_remote.exe with no command line parameters also launches the wizard. This option is useful if a configuration file is also specified. In this case, the wizard will start with values from the configuration file and the wizard can be used to change the configuration without editing the configuration file directly. This option is not available on Solaris or Linux platforms.

Setting Up Connection Parameters Using the Connection Command Line Option

This section contains the argument names and parameters for the TCP/IP connection method.

Open or create a configuration file in a text editor.
Use the following table to set up the TCP/IP connection:

Option	Parameter	Description
address	IP address	Specifies that the Remote Loader will listen 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. If an address is not specified, the Remote Loader will listen on all local IP addresses.
keypass	keypass	Used only for DirXML application shims contained in .jar files. Specifies the password for the Java keystore specified by the keystore parameter.
keystore	keystore	Used only for DirXML application shims contained in .jar files. Specifies the filename of the Java keystore that contains the trusted root certificate of the issuer of the certificate used by the remote interface shim. This will typically be the Certificate Authority of the eDirectory tree that is hosting the remote interface shim.
port	decimal port number	Specifies the TCP/IP port on which the Remote Loader will listen for connections from the remote interface shim.
rootfile	filename	Used only for DirXML application shims contained in .DLL files. Specifies the file containing the trusted root certificate of the issuer of the certificate used by the remote interface shim. This will typically be the Certificate Authority of the eDirectory tree that is hosting the remote interface shim. The certificate file must be in Base 64 format (PEM).

Running the Remote Loader

The following section contains information about running the Remote Loader service on Solaris and Linux.

Solaris and Linux

On Solaris or Linux, the binary component rdxml provides the Remote Loader functionality. This component is located in the /usr/bin/ directory.

To run the Remote Loader:

Enter a command to start the configuration file, for example:

rdxml -config <path_to_config_file>

The default sample configuration file, remote.conf, is present in the /usr/lib/dirxml/rules/ directory.
Start the Remote Loader interface shim using iManager or ConsoleOne.
Confirm that the Remote Loader is operating properly. You can do this by using either the ps or ndstat commands, or a trace file to check if the command and connection ports are listening.
To stop the Remote Loader, enter a command, like this example:

rdxml -config <path_to_config_file> -U

Setting Up Multiple Instances of the Remote Loader

You can run multiple instances of the Remote Loader on the same server hosting different driver instances by specifying different connection ports and command ports.