Installing a Remote Loader on a Windows Server

1. Run the Identity Manager 2 installation program (for example, \nt\install.exe).

2. View the Welcome page, accept the license agreement, and view the two Overview pages.

3. In the DirXML Install dialog box, deselect all components except DirXML Connected System, then click Next.

   
   

4. Select a location for the connected system (the Remote Loader and remote driver shims), then click Next.

   
   

5. Select the DirXML Remote Loader Service and remote driver shims (drivers), then click Next.

   
   

6. Acknowledge the activation requirement, view products to be installed, then click Finish.

7. Select whether to place the Remote Loader Console icon on your desktop.

Installing a Remote Loader on Solaris, Linux, or AIX

This section assumes that you have downloaded and expanded Identity Manager 2. If you need to download Identity Manager, go to the Novell download Web site.

After you expand the Identity Manager 2 file that you downloaded from the Novell Web site, complete the following steps:

1. Run one of the following installation files, depending on your platform:

   • dirxml_solaris.bin
   • dirxml_linux.bin
   • dirxml_aix.bin

2. After accepting the license agreement, press Enter to arrive at the Choose Install Set page:

   
   

3. Select DirXML Connected System Server by typing 2, then press Enter.

4. At the Pre-Installation Summary screen, review components that you have selected to install, then press Enter.

   
   

Installing a Remote Loader on HP-UX, AS/400, OS/390, or z/OS

The HP-UX, AS/400, OS/390,and z/OS platforms require the Java Remote Loader.

1. Create a directory on the target system where you want to run the Java Remote Loader.

2. From the Identity Manager 2 CD or download image, copy the appropriate file in the /java_remoteloader directory to the directory that you created in Step 1:

   Platform	File
   HP-UX AS/400 z/OS OS/390	dirxml_jremote.tar.gz dirxml_jremote.tar.gz dirxml_jremote_mvs.tar dirxml_jremote_mvs.tar

3. For HP-UX, AS/400, or z/OS, unzip the dirxml_jremote file.

4. Untar the file that you just copied.

   The Java Remote Loader is now ready for configuration. Because the tar file doesn't contain drivers, you must manually copy the drivers into the lib directory. The lib directory is under the directory where the untarring occurred.

For information on MVS, untar the dirxml_jremote_mvs.tar file. Then refer to the usage.html document.

Configuring the Remote Loader on Windows

The Remote Loader Console is a new feature in Identity Manager 2. It runs only on Windows. The Console enables you to manage all DirXML drivers running under the Remote Loader on that computer:

• Add and configure new Remote Loader instances on the local computer.
• Edit configuration settings.
• Start and stop Remote Loader instances.
• Start and stop the trace for each driver instance.

If you are upgrading to Identity Manager 2, the Console detects and imports existing instances of the Remote Loader. (To be automatically imported, driver configurations must be stored in the remoteloader directory, typically c:\novell\remoteloader.) You can then use the Console to manage the remote drivers.

To launch the Remote Loader Console, click the Remote Loader Console icon on your desktop. The following figure illustrates the Console.

If you type dirxml_remote from the command line, without any parameters, the Remote Loader Application Wizard is launched.

NOTE:  Using the wizard and the Console together can cause unexpected behavior. Therefore, we recommend that you use the Remote Loader Console going forward and upgrade your existing configurations into the Console.

To add a Remote Loader instance, click Add, then provide the following information.

To edit a Remote Loader instance:

1. Select it from the Description column.

2. Click Stop, type the Remote Loader password, then click OK.

3. Click Edit, then modify 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 and uses those parameters when it runs.

Communication

• IP Address: Specify the IP address where the Remote Loader listens for connections from the DirXML server.
• Connection Port - DirXML Server. Specify the TCP port on which the Remote Loader listens for connections from the DirXML server.

  The default TCP/IP port for this connection is 8090. With each new instance you create, the default port number automatically increases by one.

• Command Port - Local Host Communication Only: Specify the TCP port number where a Remote Loader listens for commands such as Stop and Change Trace Level.

  Each instance of the Remote Loader that runs on a particular computer must have a different command port number. The default command port is 8000. With each new instance you create, the default port number automatically increases by one.

  NOTE:  By specifying different connection ports and command ports, you can run multiple instances of the Remote Loader on the same server hosting different driver instances.

Remote Loader Password

• Password: This password is used to control access to a Remote Loader instance for a driver.

  The password must be the same case-sensitive password that you typed in the Enter the Remote Loader Password edit box in the Authentication section on the DirXML Configuration page, when you configured the driver.

• Confirm: Re-enter the password.

Driver Object Password

• Password: The Remote Loader uses this password to authenticate itself to the DirXML server.

  This password must be the same password you typed in the Driver Object Password edit box on the Driver Configuration page, when you configured the driver.

• Confirm: Re-enter the password.

Secure Socket Link (Secure Socket Layer)

• Use an SSL Connection: To specify an SSL connection, select this option.
• Trusted Root File: Browse to and select the certificate file that contains the appropriate trusted root certification.

  This is the exported self-signed certificate from the eDirectory tree's Organization Certificate Authority. See Exporting a Self-Signed Certificate.

Trace File

• Trace Level: For the Remote Loader instance to display a trace window that contains informational messages from both the Remote Loader and the driver, set a trace level greater than zero.

  If the trace level is set to 0, the trace window won't appear or display messages.

• Trace File Specify a trace filename where trace messages are written.

  Each Remote Loader instance running on a particular machine must use a different trace file. Trace messages are written to the trace file only if the trace level is greater than zero.

• Maximum Disk Space Allowed for all Trace Logs (MB): Specify the approximate maximum size that trace file data for this instance can occupy on disk.

Establish a Remote Loader Service

• To configure the Remote Loader instance as a service, select this option. When the option is enabled, the operating system automatically starts the Remote Loader when the computer starts.

Configuring the Remote Loader by Using Command Line Options

To run the Remote Loader, all platforms use a configuration file (for example, LDAPShim.txt). You can create or edit a configuration file by using command-line options. The following steps provide information on basic parameters for the configuration file. For information on additional parameters, see Options to Configure a Remote Loader.

1. Open a text editor.

2. (Optional) Specify a description by using the -description option.

   Option	Secondary Name	Parameter	Description
   -description	-desc	short description	Specify a short description string (for example, SAP) to be used for the trace window title and for Nsure Audit logging. Example: -description SAP -desc SAP The Remote Loader Console places long forms in the configuration files. You can use either a long form (for example, -description) or a short form (for example, -desc).

3. Specify a TCP/IP port that the Remote Loader instance will use by using the -commandport option.

   Option	Secondary Name	Parameter	Description
   -commandport	-cp	port number	Specifies the TCP/IP port that the Remote Loader instance uses for control purposes. If the Remote Loader instance is hosting an application shim, the command port is the port on which another Remote Loader instance communicates with the instance that is hosting the shim. If the Remote Loader instance is sending a command to an instance that is hosting an application shim, the command port is the port on which the hosting instance is listening. If not specified, the default command port is 8000. Multiple instances of the Remote Loader can run on the same server hosting different driver instances by specifying different connection ports and command ports. Example: -commandport 8001 -cp 8001

4. Specify the parameters for the connection to the DirXML server running the DirXML remote interface shim by using the -connection option.

   Type -connection "parameter [parameter] [parameter]".

   For example, type one of the following:

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

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

   Option	Secondary Name	Parameter	Description
   -connection	-conn	connection configuration string	Specifies the connection parameters for the connection to the DirXML server running the DirXML remote interface shim. The default connection method for the Remote Loader is TCP/IP using SSL. The default TCP/IP port for this connection is 8090. Multiple instances of the Remote Loader can run on the same server. Each instance of the Remote Loader hosts a separate DirXML application shim instance. Differentiate multiple instances of the Remote Loader by specifying different connection ports and command ports for each Remote Loader instance. Example: -connection "port=8091 rootfile=server1.pem" -conn "port=8091 rootfile=server1.pem"
   port		decimal port number	A required parameter. It specifies the TCP/IP port on which the Remote Loader listens for connections from the remote interface shim. Example: port=8090
   address		IP address	An optional parameter. Specifies that the Remote Loader listens on a particular local IP address. This is useful if the server hosting the Remote Loader has multiple IP addresses and the Remote Loader must listen on only one of the addresses. You have three options: address=address number address='localhost' Don't use this parameter. If you don't use the -address, the Remote Loader listens on all local IP addresses. Example: address=137.65.134.83
   rootfile			A conditional parameter. If you are running SSL and need the Remote Loader to communicate with a native driver, type rootfile='trusted certname'
   keystore			Conditional parameters. 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 is typically the Certificate Authority of the eDirectory tree that is hosting the remote interface shim. If you are running SSL and need the Remote Loader to communicate with a Java driver, type a key-value pair: keystore='keystorename' storepass='password'
   -storepass		storepass	Used only for DirXML application shims contained in .jar files. Specifies the password for the Java keystore specified by the keystore parameter. Example: storepass=mypassword This option applies only to the Java Remote Loader.

5. (Optional) Specify a trace parameter by using the -trace option.

   Option	Secondary Name	Parameter	Description
   -trace	-t	integer	Specifies the trace level. This is only used when hosting an application shim. Trace levels correspond to those used on the DirXML server. Example: -trace 3 -t 3

6. (Optional) Specify a tracefile by using the -tracefile option.

   Option	Secondary Name	Parameter	Description
   -tracefile	-tf	filename	Specify a file to write trace messages to. Trace messages are written to the file if the trace level is greater than zero. Trace messages are written to the file even if the trace window is not open. Example: -tracefile c:\temp\trace.txt -tf c:\temp\trace.txt

7. (Optional) Limit the size of the tracefile by using the -tracefilemax option.

   For example, type one of the following:

   -tracefilemax 1000M  
   -tfm 1000M 

   In this example, the tracefile can be only 1 GB.

   Option	Secondary Name	Parameter	Description
   -tracefilemax	-tfm	size	Specifies the approximate maximum size that trace file data can occupy on disk. If you specify this option, there will be a trace file with the name specified using the tracefile option and up to 9 additional "roll-over" files. The roll-over files are named using the base of the main trace filename plus "_n", where n is 1 through 9. The size parameter is the number of bytes. Specify the size by using the suffixes K, M, or G for kilobytes, megabytes, or gigabytes. If the trace file data is larger than the specified maximum when the Remote Loader is started, the trace file data remains larger than the specified maximum until roll-over is completed through all 10 files Example: -tracefilemax 1000M -tfm 1000M In this example, the tracefile can be only 1 GB.

8. Specify the class by using the -class option or module by using the -module option.

   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. For example, for a Java driver, type one of the following: -class com.novell.nds.dirxml.driver.ldap.LDAPDriverShim -cl com.novell.nds.dirxml.driver.ldap.LDAPDriverShim Java uses a keystore to read certificates. The -class option and the -module option are mutually exclusive.
   -module	-m	modulename	Specifies the module containing the DirXML application shim that is to be hosted. For example, for a native driver, type one of the following: -module "c:\Novell\RemoteLoader\Exchange5Shim.dll" -m "c:\Novell\RemoteLoader\Exchange5Shim.dll" or -module "usr/lib/dirxml/NISDriverShim.so" -m "usr/lib/dirxml/NISDriverShim.so" The -module option uses a rootfile certificate. The -module option and the -class option are mutually exclusive.

9. Name and save the file.

You can change some settings while the Remote Loader is running. For information on these settings, refer to Options to Configure a Remote Loader.

Parameter	Description
-commandport	Specifies an instance of the Remote Loader.
-config	Specifies a configuration file.
-javadebugport	Specifies that the Remote Loader instance is to enable Java debugging on the specified port.
-password	Enables you to send in commands.
-service	Installs an instance as a service. Windows only.
-tracechange	Changes the trace level.
-tracefilechange	Changes the name of the trace file being written to.
-unload	Unloads the Remote Loader instance.
-window	Turns the trace window on or off in a Remote Loader instance. Windows only.

The Remote Loader on Windows

To run the Remote Loader on Windows:

1. Click the Remote Loader Console icon on the desktop.

   
   

2. Select a driver instance, then click Start.

Running the Remote Loader from the Command Line

On Solaris, Linux, or AIX, the binary component rdxml provides the Remote Loader functionality. This component is located in the /usr/bin/ directory. On Windows, the default is c:\novell\RemoteLoader.

To run the Remote Loader:

1. Set the password.

   Platform	Command
   Windows	dirxml_remote -config path_to_config_file -sp password password
   Solaris LInux AIX	rdxml -config path_to_config_file -sp password password
   HP-UX AS/400 OS/390 z/OS	dirxml_jremote -config path_to_config_file -sp password password

   Option	Secondary Name	Parameter	Description
   -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 (for example, unload or tracechange) is specified and the password option isn't specified, the user is prompted to enter the password for the loader that is the target of the command. Example: -password novell4 -p novell4
   -setpasswords	-sp	password password	Specifies the password for the Remote Loader instance and the password of the DirXML Driver object of the remote interface shim that the Remote Loader communicates with. The first password in the argument is the password for the Remote Loader. The second password in the optional arguments is the password for the DirXML Driver object associated with the remote interface shim on the DirXML server. Either no password or both passwords must be specified. If no password is specified, the Remote Loader prompts for the passwords. This is a configuration option. Using this option configures the Remote Loader instance with the passwords specified but doesn't load a DirXML application shim or communicate with another loader instance. Example: -setpasswords novell4 staccato3 -sp novell4 staccato3

2. Start the Remote Loader.

   Platform	Command
   Windows	dirxml_remote -config path_to_config_file
   Solaris LInux AIX	rdxml -config path_to_config_file
   HP-UX AS/400 OS/390 z/OS	dirxml_jremote -config path_to_config_file

3. Using iManager, start the driver.

4. Confirm that the Remote Loader is operating properly.

   The Remote Loader loads the DirXML application shim only when the Remote Loader is in communication with the remote interface shim on the DirXML server. This means, for example, that the application shim will be shut down if the Remote Loader loses communication with the DirXML server.

   For Linux, Solaris, or AIX, use the ps command or a trace file to find out whether the command and connection ports are listening.

   For HP-UX and similar platforms, 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, the loader is successfully running and awaiting connection from the DirXML remote interface shim:

   TRACE: Remote Loader: Entering listener accept()

To configure the Remote Loader (rdxml) to start automatically on UNIX, see TID 10097249.