Setting Up Remote Loaders

This section provides information on the following:


Installing Remote Loaders

This section provides information on the following:


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.


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


    The edit box to specify a location
  5. Select the DirXML Remote Loader Service and remote driver shims (drivers), then click Next.


    The dialog box to select the Remote Loader and driver shims
  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:


    Options on 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.


    The Pre-Installation Summary page


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 Remote Loaders

The DirXML Remote Loader can host DirXML application shims contained in .dll, .so, or .jar files. The Java Remote Loader hosts only Java driver shims. It won't load or host a native (C++) driver shim.


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.


The Remote Loader Console dialog box

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


Remote Driver Configuration parameters
  • 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


Communication parameters
  • 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


Edit boxes to specify the 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


Edit boxes to specify the 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)


Parameters to set up SSL
  • 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 file parameters
  • 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


The check box to 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.


Setting Environment Variables on Solaris, Linux, or AIX

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


Running Remote Loaders


The Remote Loader on Windows

To run the Remote Loader on Windows:

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


    The Remote Loader Console
  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.


Stopping Remote Loaders

Platform Command

Windows

Use the Remote Loader Console to stop a driver instance.

Solaris
LInux
AIX

rdxml -config path_to_config_file -u

HP-UX
AS/400
OS/390
z/OS

dirxml_jremote -config path_to_config_file -u

If multiple instances of the Remote Loader are running on the computer, pass the -cp command port option so that the Remote Loader can stop the appropriate instance.

When you stop the Remote Loader, you must have sufficient rights or enter the Remote Loader password.

Scenario: Sufficient Rights. 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.

The Remote Loader isn't "accepting" the password. Instead, it is ignoring 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.