2.7 Setting Up the Driver

Complete these tasks to get the driver installed, configured, and running. (If you are upgrading the driver, see Section 3.0, Upgrading.)

Most installations require some customization after installation to handle certification. Refer to Section 4.0, Customizing the Driver for more information.

2.7.1 Installing the Driver Shim

Installing on a Windows Domino Server

  1. Install the Remote Loader. See Section 2.4.2, Installing the Lotus Notes Driver on Windows with the Identity Manager Connected System.

    To install the driver shim, it is recommended you use the Remote Loader to run the driver, even if the driver is running on the same machine as Identity Manager. See Section 2.4, Installing the Lotus Notes Driver During Identity Manager Installation.

    The necessary files for the driver shim are installed in the \Novell\RemoteLoader and \Novell\RemoteLoader\lib directories.

  2. Manually copy the following files to set up the driver.

    Filename

    Copy from

    Copy to

    ndsrep.exe

    The installed location: \novell\NDS

    or \Novell\RemoteLoader

    The Domino server executable folder ( \Lotus\Domino)

    dsrepcfg.ntf

    The installed location: \novell\NDS

    or \Novell\RemoteLoader

    The Domino server data folder ( Lotus\Domino\Data)

    Notes.jar

    \Lotus\Domino

    If running remotely, \Novell\RemoteLoader\lib

    or if running locally, \Novell\NDS\lib

  3. Make sure that the Domino shared libraries directory (for example, c:\lotus\domino) is in the Windows system path, and reboot the computer to make sure this step becomes effective.

    Without this directory in the Windows system path, the JVM* might have difficulty locating the Domino shared libraries required by Notes.jar, such as nlsxbe.dll.

  4. If the Domino server requires databases to be signed, use a Notes client or Domino Administrator to sign dsrepcfg.ntf with your Domino server’s server ID.

  5. After installation, create a driver object as explained in Section 2.5, Importing the Notes Driver Configuration File in iManager or Section 2.6, Installing the Lotus Notes Driver through Designer.

  6. Set passwords for the driver and Remote Loader for the initial startup of the Remote Loader.

    These passwords must be the same as the Driver Password and Remote Password you specified when importing the driver configuration.

  7. Start the driver:

    1. In iManager, select Identity Manager > Identity Manager Overview.

    2. Locate the driver in its driver set by searching the entire tree, or specify a container and click Search.

    3. Click the driver status indicator in the upper right corner of the driver icon, then click Start Driver.

    4. Enter the password for the Notes user that you are using for the driver, if you are prompted to do so. This prompt appears only the first time you start the driver, and whether it appears depends on your driver configuration.

      When the driver starts for the first time, it does the following:

      • Searches for the Domino Server (specified in the driver parameters at import time)

      • Opens dsrepcfg.nsf. If that file does not exist, the driver automatically creates dsrepcfg.nsf, using the dsrepcfg.ntf database template that is provided with the driver.

      • Writes the Publisher parameters and data to dsrepcfg.nsf, specifying an appropriate update database file (usually named ndsrep.nsf), so that ndsrep can read them.

      IMPORTANT:If multiple notes.ini files exist on the machine running the driver, ensure that the NotesDriverShim uses the correct .ini by placing its directory in the OS search path. If the driver shim initializes with the wrong notes.ini file, the driver shim cannot open dsrepcfg.ntf.

      If dsrepcfg.ntf is not found, or the initial dsrepcfg.nsf creation process fails, then the Publisher channel shuts down, and you cannot complete Step 9.

      Ensure that the driver shim initializes properly by modifying the Windows system path to find the appropriate notes.ini file.

  8. At the Domino Console, start the ndsrep task:

    load ndsrep instance
    

    The instance must be the driver name, or a unique instance name set up for this driver. If the name of your driver includes spaces, then you must put quotes around the name. After ndsrep is loaded, all TELL commands are issued to this instance of ndsrep using the instance name.

    A task named NDSREP-instance is now displayed in the Notes Task Viewer.

  9. After the initial configuration and startup has been validated, update the Domino server's notes.ini file so that ndsrep is loaded automatically.

    For example:

    ServerTasks=Update,Replica,Router,AMgr,AdminP,ndsrep notesdrv1,
    CalConn,Sched,HTTP,IMAP,POP3
    

    If the name of your driver includes spaces, then you must put quotes around the name.

    After the first successful startup, the Notes driver and ndsrep can be launched in any order that is convenient for your particular configuration.

    For more information about ndsrep, see Section 2.7.2, Configuring Publication Synchronization Using Ndsrep.

    You can also use Domino Administrator to create a program document that will launch ndsrep when the Domino server starts. To do this, see Automated Method #2.

  10. Activate the driver, as explained in Section 5.0, Activating the Driver.

    Data synchronized by the driver should not be used outside of a test environment if you have not purchased the driver.

  11. If you want to synchronize all objects at once, you must initiate the process as explained in Section 2.7.3, Migrating and Resynchronizing Data.

    Otherwise, synchronization takes place on an object-by-object basis, the next time a change is made to the individual object.

  12. Most installations require some customization after installation to handle certification. Refer to Section 4.0, Customizing the Driver for more information.

Installing on a Notes Client Workstation Running Windows

  1. On a Notes client workstation running Windows, set up a Notes client to connect to the Domino server that hosts the synchronized database.

  2. Install the Remote Loader and the Notes driver shim on a Lotus Notes client workstation that is separate from the Domino server. See Section 2.4.2, Installing the Lotus Notes Driver on Windows with the Identity Manager Connected System.

    The necessary files for the driver shim are installed in the \Novell\RemoteLoader and \Novell\RemoteLoader\lib directories.

  3. Manually copy the following files to set up the driver.

    Filename

    Copy from

    Copy to

    ndsrep.exe

    The installed location: \novell\NDS

    or \Novell\RemoteLoader

    The Domino server executable folder ( \Lotus\Domino)

    dsrepcfg.ntf

    The installed location: \novell\NDS

    or \Novell\RemoteLoader

    The Domino server data folder ( Lotus\Domino\Data)

    Notes.jar

    \Lotus\Notes

    If running remotely, \Novell\RemoteLoader\lib

    or if running locally, \Novell\NDS\lib

  4. Make sure that the Notes client library . dll directory (for example, c:\lotus\notes) is in the Windows system path, and reboot the computer to make sure this step becomes effective.

    Without this directory in the Windows system path, the JVM might have difficulty locating the Notes client libraries required by Notes.jar, such as nlsxbe.dll.

  5. Make sure the necessary user.id and cert.id files are available to the Notes Client and NotesDriverShim.jar so that the Notes driver can properly authenticate to the Domino server and register new Notes users.

  6. After installation, create a driver object as explained in Section 2.5, Importing the Notes Driver Configuration File in iManager or Section 2.6, Installing the Lotus Notes Driver through Designer.

  7. Set passwords for the driver and Remote Loader for the initial startup of the Remote Loader.

    These passwords must be the same as the Driver Password and Remote Password you specified when importing the driver configuration.

  8. Start the driver:

    1. In iManager, select Identity Manager > Identity Manager Overview.

    2. Locate the driver in its driver set by searching the entire tree, or specify a container and click Search.

    3. Click the driver status indicator in the upper-right corner of the driver icon, then click Start Driver.

    4. Enter the password for the Notes user that you are using for the driver, if you are prompted to do so. This prompt appears only the first time you start the driver, and whether it appears depends on your driver configuration.

      When the driver starts for the first time, it does the following:

      • Searches for the Domino Server (specified in the driver parameters at import time)

      • Opens dsrepcfg.nsf. If that file does not exist, the driver creates dsrepcfg.nsf automatically, using the dsrepcfg.ntf database template that is provided with the driver.

      • Writes to dsrepcfg.nsf the Publisher parameters and data specifying an appropriate update database file (usually named ndsrep.nsf), so that ndsrep can read them.

      IMPORTANT:If multiple notes.ini files exist on the machine running the driver, ensure that the NotesDriverShim uses the correct .ini by placing its directory in the OS search path. If the driver shim initializes with the wrong notes.ini file, the driver shim cannot open dsrepcfg.ntf.

      If dsrepcfg.ntf is not found, or the initial dsrepcfg.nsf creation process fails, then the Publisher channel shuts down. Ensure that the driver shim initializes properly by modifying the Windows system path to find the appropriate notes.ini file.

  9. If you choose to run the NotesDriverShim with the Remote Loader on a machine with Windows and a Notes Client, the initial user password (or modified HTTPPassword) is sent across the wire from the NotesDriverShim to the Domino server through a Lotus Notes Client/Domino server communication port. 

    To secure this connection, use the LotusNotes port communication encryption configured on the Domino server. See Domino server documentation for further information.

  10. If the NotesDriverShim runs on the same machine as the Domino server and connects to the Identity Manager services running on a different machine via Remote Loader, you can secure this connection via SSL following the instructions in the IDM Remote Loader documentation. See Setting Up Remote Loaders.

  11. At the Domino Console, start the ndsrep task:

    load ndsrep instance
    

    The instance must be the driver name, or a unique instance name set up for this driver. If the name of your driver includes spaces, then you must put quotes around the name. After ndsrep is loaded, all TELL commands are issued to this instance of ndsrep using the instance name.

    A task named NDSREP-instance is now displayed in the Notes Task Viewer.

  12. After the initial configuration and startup has been validated, update the Domino server's notes.ini file so that ndsrep is loaded automatically.

    For example:

    ServerTasks=Update,Replica,Router,AMgr,AdminP,ndsrep notesdrv1,
    CalConn,Sched,HTTP,IMAP,POP3
    

    If the name of your driver includes spaces, then you must put quotes around the name.

    After the first successful startup, the Notes driver and ndsrep can be launched in any order that is convenient for your particular configuration.

    For more information about ndsrep, see Section 2.7.2, Configuring Publication Synchronization Using Ndsrep.

  13. Activate the driver, as explained in Section 5.0, Activating the Driver.

    Data synchronized by the driver should not be used outside of a test environment if you have not purchased the driver.

  14. If you want to synchronize all objects at once, you must initiate the process as explained in Section 2.7.3, Migrating and Resynchronizing Data.

    Otherwise, synchronization takes place on an object-by-object basis, the next time a change is made to the individual object.

  15. Most installations require some customization after installation to handle certification. Refer to Section 4.0, Customizing the Driver for more information.

Installing on AIX, Linux, or Solaris

  1. After installing Identity Manager, install the driver shim and the Remote Loader on the connected system where you want to run the driver.

    For AIX, Linux, and Solaris, you must use the Remote Loader to run the driver, even if the driver is running on the same machine as Identity Manager.

    In the installation, choose Connected System Server, as described in Section 2.4.3, Installing the Lotus Notes Driver through the GUI Interface On Linux Platforms or Section 2.4.4, Using the Command Line to Install the Driver on UNIX/Linux .

    The necessary files for the driver shim are installed in /usr/lib/dirxml.

  2. Make sure that the Notes.jar file is linked to the correct directory for your environment.

    If your Domino server is prior to V7, enter the following:

    ls -l /usr/lib/dirxml/classes/Notes.jar

    The link should be something like the following:

    /usr/lib/dirxml/classes/Notes.jar linked to /opt/lotus/notes/latest/linux/Notes.jar

    If your Domino server is V7.x running eDirectory 8.8, enter the following:

    ls -l /opt/novell/eDirectory/lib/dirxml/classes/Notes.jar

    The link should be something like the following:

    /opt/novell/eDirectory/lib/dirxml/classes/Notes.jar linked to /opt/ibm/lotus/notes/latest/linux/jvm/lib/ext/Notes.jar

  3. Make sure you have created a user to run the Remote Loader and the driver, as described in Creating Lotus Notes Accounts and Groups.

    You cannot run Remote Loader for the Notes driver using root.

  4. Create a driver object as explained in Importing the Notes Driver Configuration File in iManager or Section 2.6, Installing the Lotus Notes Driver through Designer. Do not start the driver yet.

  5. Use a Notes client or Domino Administrator to sign dsrepcfg.ntf with your Domino server’s server ID.

  6. Copy the following files from where they are installed ( /usr/lib/dirxml/rules/notes or /opt/novell/eDirectory/lib/dirxml/rules), to the location where you intend to launch your driver on the Domino server, such as /local/notesdata. You might want this location to be in your execution search path. You might also need appropriate rights when copying these files to other directories.

    Filename

    Description

    rdxml.startnotes

    This script calls the findDomino script, which sets up appropriate Domino operating system environment variables for the Notes driver. Then the rdxml.startnotes script launches the Remote Loader with the Notes driver parameters specified in the rdxml.confignotes file.

    If the location where the scripts are placed is not in a current search path, you might need to do one of the following:

    • Modify rdxml.startnotes to include a specific path to the findDomino script.

    • Create a symbolic link for findDomino in /usr/bin.

    rdxml.stopnotes

    This script stops the Remote Loader that is running the Notes driver.

    findDomino

    This script is called from the rdxml.startnotes script. When you launch rdxml.startnotes, this script sets up operating system environment variables that indicate the location of a UNIX type of installation of Domino.

    rdxml.confignotes (or wherever your configuration is stored)

    This configuration is referenced by rdxml.startnotes and rdxml.stopnotes scripts.

    You might need to modify the rdxml.startnotes script to fit your environment. For example, if you change the name of the configuration file to a name other than rdxml.confignotes, you must revise the last line in the script.

    You might need to change the configuration ports that are referenced in this file.

    These three sample scripts and the sample configuration file are provided to demonstrate how to launch the driver. You can start the Remote Loader for the driver using rdxml.startnotes, and stop the Remote Loader for the driver using rdxml.stopnotes.

    The sample scripts work in a variety of situations. If they do not work in your environment, you might need to edit them appropriately. The sample scripts produce a Remote Loader trace log for the driver that can be used for troubleshooting.

  7. Modify the scripts and configuration file to fit to your environment, as described in the table in Step 6.

  8. Make sure that the three scripts noted in Step 6 have file access for execution (for example, rwxr-xr-x).

  9. Set passwords for the driver and Remote Loader for the initial startup of the Remote Loader.

    For example,

    cd driver_script_directory
    	./rdxml.startnotes -sp driver_password remote_loader_password
    

    These passwords must be the same as the Driver Password and Remote Password you specified when importing the driver configuration.

  10. Use rdxml.startnotes to start Remote Loader for the driver.

    For example,

    cd driver_script_directory
    	./rdxml.startnotes
    

    The driver_script_directory should be the directory where you placed the files in Step 6.

  11. Start the driver by using iManager.

    1. In iManager, select Identity Manager > Identity Manager Overview.

    2. Locate the driver in its driver set.

    3. Click the driver status indicator in the upper right corner of the driver icon, then click Start Driver.

      When the driver starts the first time, it does the following:

      • Searches for the Domino Server (specified in the driver parameters at import time)

      • Opens dsrepcfg.nsf. If that file does not exist, the driver automatically creates dsrepcfg.nsf, using the dsrepcfg.ntf database template that is provided with the driver.

      • Writes the Publisher parameters and data to dsrepcfg.nsf, specifying an appropriate update database file (usually named ndsrep.nsf), so that ndsrep can read them.

      NOTE:If dsrepcfg.ntf is not found, or this initial dsrepcfg.nsf creation process fails, then the Publisher channel shuts down, and Step 12 cannot be completed. You must have a valid TCP/IP port configured on the Domino server for this to succeed.

  12. At the Domino Console, start the ndsrep task:

    load ndsrep instance
    

    The instance must be the driver name, or a unique instance name set up for this driver. If the name of your driver includes spaces, then you must put quotes around the name. After ndsrep is loaded, all TELL commands are issued to this instance of ndsrep using the instance name.

    A task named DirXML or a similar name is now displayed in the Notes Task Viewer.

  13. After the initial configuration and startup has been validated, update the Domino notes.ini file so that ndsrep is loaded automatically.

    For example:

    ServerTasks=Update,Replica,Router,AMgr,AdminP,ndsrep notesdrv1,
    CalConn,Sched,HTTP,IMAP,POP3
    

    Or you can create a program document (see Loading Ndsrep).

    If the name of your driver includes spaces, then you must put quotes around the name.

    After the first successful startup, the Notes driver and ndsrep can be launched in any order that is convenient for your particular configuration.

  14. Activate the driver, as explained in Section 5.0, Activating the Driver.

    Data synchronized by the driver should not be used outside of a test environment if you have not purchased the driver.

  15. If you want to synchronize all objects at once, you must initiate the process as explained in Section 2.7.3, Migrating and Resynchronizing Data.

    Otherwise, synchronization takes place on an object-by-object basis, the next time a change is made to the individual object.

  16. Most installations require some customization after installation to handle certification. Refer to Section 4.0, Customizing the Driver for more information.

For troubleshooting tips, see Troubleshooting Installation Problems.

2.7.2 Configuring Publication Synchronization Using Ndsrep

Complete the following sections to configure replication using ndsrep:

Setting Up Ndsrep

  1. Review the information about ndsrep and starting the driver in the steps in Section 2.7.1, Installing the Driver Shim.

  2. Make sure you have copied the necessary files for your platform, as described in Section 2.7.1, Installing the Driver Shim.

  3. (Windows only) Add c:\lotus\domino (or the appropriate Domino executable folder) to your system path, then reboot the computer.

  4. Before trying to load ndsrep, make sure that the Identity Manager Driver for Lotus Notes has been started at least once.

Loading Ndsrep

You always load and run ndsrep at the server console on the Domino server. The ndsrep program creates an output database (by default, ndsrep.nsf), detects changes in the Public address book in the Domino server (or other Notes database), and copies these changes to the output database.

You can load ndsrep through two automated methods or though one manual method.

Automated Method #1

  1. Load ndsrep in the Domino Server console.

  2. Add ndsrep to the ServerTasks = statement in notes.ini and restart the Domino server,

    For example:

    ServerTasks=Update,Replica,Router,AMgr,AdminP,ndsrep notesdrv1,
    CalConn,Sched,HTTP,IMAP,POP3
    

Automated Method #2

Create a program document.

Using the Domino Administrator, you can define programs to run on a server using the Server>Programs view. Using the Programs view, define the program you want to run, including the server name. Use the following steps to define ndsrep.

  1. Using Domino Administrator, select the Configuration tab.

  2. Expand the Server icon in the left pane and select the Programs icon under Server.

  3. Click the Add Program button and fill in the information for ndsrep. For example, if you are trying to set up ndsrep for NotesDrv1 on Domino Server Dom/Serv1/acme, enter the following:

    • Under the Basics section, type in the program name ndsrep.

    • In the Command entry, type NotesDrv1

    • In the Server to run on entry, type DomServ1/acme

    • In the Comments entry, type NotesDrv1 Publisher polling process

    • In the Enabled/Disabled entry under the Schedule section, type At server startup only

  4. Click the Save & Close button to save the program definition.

The next time the DomServ1/acme Domino server starts, the nsrep for NotesDrv1 should load automatically.

Manual Method

  1. Type the following in the Notes Server Console window:

    load ndsrep instance 
    

If the name of your driver includes spaces, then you must put quotes around the name.

Controlling Ndsrep

Use the TELL commands described in the table. The following ndsrep TELL commands allow for immediate ndsrep actions. These commands are not stored; ndsrep simply executes the action.

TELL Command

Description

RefreshConfig

Reads ndsrep configuration information from the configuration store.

Replicate

Forces an immediate check for updated notes.

Resume

Sets ndsrep to resume processing timer events and replication.

ShowConfig

Displays ndsrep configuration settings in the console window.

ShowFilter

Displays the first 240 characters of the filter for updated records that ndsrep is using when publishing.

Suspend

Suspends activity until the Resume command is given.

Setting Up Multiple Instances of Ndsrep

You can run multiple instances of ndsrep to support multiple drivers running against a single Domino server. You must specify the appropriate driver instance name as a parameter when loading ndsrep. By default, this instance name is the name of the driver.

If the name of your driver includes spaces, then you must put quotes around the name.

Consider the following important issues with setting up ndsrep and multiple instances:

  • To load ndsrep, you must use the appropriate instance name:

    load ndsrep instance
    

    ndsrep is loaded and referenced using TELL commands by the value of instance.

  • By default, ndsrep stores configuration data for instances in a common Notes database ( dsrepcfg.nsf).

  • When modifying notes.ini to auto load multiple instances of ndsrep, simply insert ndsrep instance multiple times on the ServerTask line of notes.ini.

    For example:

    ServerTasks=Update,Replica,Router,AMgr,AdminP,
    ndsrep notesdrv1,ndsrep notesdrv2,CalConn,Sched,HTTP,IMAP,POP3
    

    You can also create multiple program documents (see Automated Method #2).

  • For custom configurations, you can tell ndsrep to utilize a different configuration database. To do so, use the ndsrep configuration parameter and load ndsrep using the -f filename parameter as noted in ndsrep configuration database and ndsrep configuration instance in the parameters table in Section 4.0, Customizing the Driver

2.7.3 Migrating and Resynchronizing Data

Identity Manager synchronizes data as the data changes. If you want to synchronize all data immediately, you can choose from the following options:

  • Migrate Data from eDirectory: Allows you to select containers or objects you want to migrate from the Identity Vault to an application. When you migrate an object, the Metadirectory engine applies all of the Matching, Placement, and Create rules, as well as the Subscriber filter, to the object.

  • Migrate Data into eDirectory: Allows you to define the criteria Identity Manager uses to migrate objects from an application into the Novell Identity Vault. When you migrate an object, the Metadirectory engine applies all of the Matching, Placement, and Create rules, as well as the Publisher filter, to the object. Objects are migrated into the Identity Vault using the order you specify in the Class list.

  • Synchronize: The Metadirectory engine looks in the Subscriber class filter and processes all objects for those classes. Associated objects will be merged. Unassociated objects are processed as Add events.

To use one of the options explained above:

  1. In iManager, select Identity Manager > Identity Manager Overview.

  2. Locate the driver set containing the Notes driver, then double-click the driver icon.

  3. Click the appropriate migration button.