Novell Documentation: Nsure Identity Manager Drivers

Setting Up the Driver

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

Installing the Driver Shim
This procedure refers to the others in this section, to show when they should be completed.
Creating a Driver Object and Importing the Driver Configuration
Configuring Database Replication Using ndsrep
Migrating and Resynchronizing Data
Activating the Driver

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

Installing the Driver Shim

Installing on Windows

Install the driver shim, and the Remote Loader if necessary.

You can install the driver shim at the same time you install the DirXML engine, or after.
1. To run the driver locally on the same machine as the DirXML engine, run the Identity Manager installation program and select the DirXML Driver for Lotus Notes.
  
  Instructions are in "Installation" in the Novell Nsure Identity Manager 2 Administration Guide.
2. To run the driver remotely, install the driver shim and Remote Loader on the system where you want to run the driver.
  
  Instructions are in "Setting Up a Connected System" in the Novell Nsure Identity Manager 2 Administration Guide.

Manually copy the following files to set up the driver.

Filename	Copy from	Copy to
ndsrep.exe	Its installed location (\novell\NDS)	The Domino server executable folder (\Lotus\Domino)
dsrepcfg.ntf	Its installed location (\novell\NDS)	The Domino server data folder (Lotus\Domino\Data)
Notes.jar	\Lotus\Domino	One of the following: If running locally, \Novell\nds\lib If running remotely, \Novell\RemoteLoader\lib

Filename

Copy from

Copy to

ndsrep.exe

Its installed location (\novell\NDS)

The Domino server executable folder (\Lotus\Domino)

dsrepcfg.ntf

Its installed location (\novell\NDS)

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

Notes.jar

\Lotus\Domino

One of the following:

If running locally, \Novell\nds\lib
If running remotely, \Novell\RemoteLoader\lib

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 is complete.

Without this directory in the Windows system path, the JVM* might have difficulty locating the Domino shared libraries required by Notes.jar, such as nxlsbe.dll.
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.
After installation, create a driver object as explained in Creating a Driver Object and Importing the Driver Configuration.
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, as described in Creating a Driver Object and Importing the Driver Configuration.
Start the driver using iManager.
1. In iManager, select DirXML Management > 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.
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 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 the driver shim initializes with the notes.ini file for a Notes client instead of the Domino server, the driver shim is not able to open dsrepcfg.ntf.
If dsrepcfg.ntf is not found, or the initial dsrepcfg.nsf creation process fails, then the Publisher channel shuts down, and Step 8 cannot be completed.

Ensure that the driver shim initializes properly by modifying the Windows system path to find the notes.ini file for the Domino server before it finds the notes.ini for a Notes client.
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.
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 Configuring Database Replication Using ndsrep.
Activate the driver, as explained in Activating the Driver.

Data synchronized by the driver should not be used outside of a test environment if you have not purchased the driver.
If you want to synchronize all objects at once, you must initiate the process as explained in 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.
Most installations require some customization after installation to handle certification. Refer to Customizing the Driver for more information.

Installing on AIX, Linux, or Solaris

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

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

In the installation, choose Connected System Server, as described in "Setting Up a Connected System" in the Novell Nsure Identity Manager 2 Administration Guide.

The necessary files for the driver shim are installed in /usr/lib/dirxml.
Make sure that /usr/lib/dirxml/classes/Notes.jar is linked to the correct directory for your environment.

For example, 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/60030/linux/Notes.jar

In this example, 60030 is the version number of Domino. If you upgrade Domino after installing the driver, you need to check your symbolic links. See Troubleshooting Installation.
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.
Create a driver object as explained in Creating a Driver Object and Importing the Driver Configuration. Do not start the driver yet.
Use a Notes client or Domino Administrator to sign dsrepcfg.ntf with your Domino server's server ID.

Copy the following files from where they are installed (/usr/lib/dirxml/rules/notes by default), to the location where you intend to launch your driver on the Domino server, such as /local/notesdata, /home/notes, or /user/bin. You might want this location to be in your search path.

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.

Modify the scripts and configuration file to fit to your environment, as described in the table in Step 6.
Make sure that the three scripts noted in Step 6 have file access for execution (for example, rwxr-xr-x).
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, as described in Creating a Driver Object and Importing the Driver Configuration.
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.
Start the driver using iManager.
1. In iManager, select DirXML Management > 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 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.
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.
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.
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
```
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.
Activate the driver, as explained in Activating the Driver.

Data synchronized by the driver should not be used outside of a test environment if you have not purchased the driver.
If you want to synchronize all objects at once, you must initiate the process as explained in 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.
Most installations require some customization after installation to handle certification. Refer to Customizing the Driver for more information.

For troubleshooting tips, see Troubleshooting Installation.

Troubleshooting Installation

For Windows:

The first time the driver runs, it searches for the Domino Server (specified in the driver parameters at import time), and tries to open dsrepcfg.nsf to write the publisher parameters that ndsrep reads. If dsrepcfg.nsf does not exist, then the NotesDriverShim attempts to create dsrepcfg.nsf using the database template dsrepcfg.ntf that ships with the driver.
If dsrepcfg.nsf is successfully created, and contains data specifying an appropriate update database file (usually named ndsrep.nsf), then you can load ndsrep successfully at the Domino Console.

If dsrepcfg.ntf is not found, or this initial dsrepcfg.nsf creation process fails, then the Publisher channel shuts down, and you can't load the ndsrep task at the Domino console.

You can use a Notes client to create the dsrepcfg.nsf database using the dsrepcfg.ntf template. After doing so, modify the ACL so that the Notes driver user has manager-level access to the database.

For AIX, Linux, and Solaris:

If you upgrade Domino after installing the driver, you need to do one of the following:

Check the following symbolic links, and re-create them manually if necessary.

File to link	Symbolic link to create
Notes.jar	/usr/lib/dirxml/classes/Notes.jar Example: ln -s /opt/lotus/notes/latest/your_platform/Notes.jar /user/lib/dirxml/classes/Notes.jar
ndsrep	/opt/lotus/notes/latest/your_platform/ndsrep Example: ln -s /usr/lib/dirxml/rules/notes/ndsrep /opt/lotus/notes/latest/your_platform/ndsrep
dsrepcfg.ntf	/opt/lotus/notes/latest/your_platform/dsrepcfg.ntf Example: ln -s /usr/lib/dirxml/rules/notes/dsrepcfg.ntf /opt/lotus/notes/latest/your_platform/dsrepcfg.ntf

File to link

Symbolic link to create

Notes.jar

/usr/lib/dirxml/classes/Notes.jar

Example:

ln -s /opt/lotus/notes/latest/your_platform/Notes.jar
/user/lib/dirxml/classes/Notes.jar

ndsrep

/opt/lotus/notes/latest/your_platform/ndsrep

Example:

ln -s /usr/lib/dirxml/rules/notes/ndsrep
/opt/lotus/notes/latest/your_platform/ndsrep

dsrepcfg.ntf

/opt/lotus/notes/latest/your_platform/dsrepcfg.ntf

Example:

ln -s /usr/lib/dirxml/rules/notes/dsrepcfg.ntf
/opt/lotus/notes/latest/your_platform/dsrepcfg.ntf

The variable your_platform represents the operating system. The following table shows the folder names.

Operating System	Folder Name
AIX	ibmpow
Linux	linux
Solaris	sunspa

Back up certain files, and then reinstall the driver. Reinstalling the driver shim re-creates the symbolic links, but it overwrites certain files. If you have made changes to them, you need to make a backup.
Back up the following files:

rdxml.startnotes
rdxml.stopnotes
findDomino
rdxml.confignotes (or wherever your configuration is stored)

After reinstalling the driver shim, copy the backups to their original location.

Even if you don't use the mail functions, you must specify all mail parameters in the driver configuration. If they are not specified, the driver might report errors and stop running.
The sample scripts provided (rdxml.startnotes, rdxml.stopnotes, findDomino) produce a Remote Loader trace log for the driver that can be used for troubleshooting.

Creating a Driver Object and Importing the Driver Configuration

Import the driver configuration file to create all necessary eDirectory objects, such as policies, style sheets, and filters, for basic driver configuration. Then you can modify the configuration to fit your specific business needs.

Follow the instructions in "Creating a Driver Object" in the Novell Nsure Identity Manager 2 Administration Guide.

Provide the following information and finish the wizard, then start the driver as described in Installing the Driver Shim.

The sample driver configuration uses a new feature, flexible prompting, to reduce complexity when importing the configuration. If you choose to install the driver for use with Remote Loader, or if you choose to use Role-Based Entitlements, an additional page is displayed in the wizard where you provide information for those features.

Import Prompt	Description
Notes User ID	Enter the Notes User ID this driver will use for Notes Authentication (in fully qualified canonical form: i.e. cn=Notes Driver/o=Organization). This user ID needs administrative rights to the Input database as well as the Output database. We recommend that this ID be specifically created for the driver and used only by the driver. This will prevent the driver from responding to changes made to Notes when this user is used.
Notes User ID File	Enter the full path (on the Domino Server) for the Notes User ID file associated with the Notes User this driver will use for Notes Authentication.
Notes User Password	Enter the password for the Notes User ID this driver will use when authenticating to Notes (for the above user ID file).
Domino Server	Enter the Name of the Domino server this driver will authenticate to (in fully qualified canonical form: i.e. cn=NotesServer/o=Organization).
Notes Server ID File	Enter the full path for the Notes Server ID file associated with the Notes Server this driver will authenticate to.
Default Notes Certifier ID File	Enter the full path (on the Domino server) for the Default Notes Certifier ID file the driver will use at the default certifier. This is usually the root certifier, but can be any certifier with adequate access.
Default Notes Certifier Password	Enter the password for the Default Notes Certifier ID this driver will use when certifying new users. This password is secured using the new Named Passwords feature. See Using Named Passwords.
Notes Organization Name	Enter the name of the Notes Organization (This is usually the o= at the root of the tree).
Notes Domain	Enter the name of the Notes Domain.
Target Notes Database	Enter the relative path and file name (on the Domino server) for the target Notes Database. The path should be relative to the Domino server's data directory.
Is this database a Notes Address Book?	This driver has the capability of interfacing with different Notes databases.
Notes Changelog Database	Enter the relative path and file name (on the Domino server) for the Notes Changelog Database. This file is created by ndsrep. The path should be relative to the Domino server's data directory.
Certify new Notes Users?	Should the driver certify users added to Notes on the subscriber channel?
Notes ID Storage Path	Enter the path (on the Domino server) where the driver should create new user ID files.
Notes Certification Log Database	Enter the relative path and file name (on the Domino server) for the Notes Certification Log Database. The path should be relative to the Domino server's data directory.
Update Address Book with user certifications?	Should Notes update the server entry in the Address Book when a new user is certified in Notes on the subscriber channel?
Store User ID files in Notes Address Book?	Should Notes store new users IDs in the address book when certifying users added to Notes on the subscriber channel?
Is the Domino Server a North American Server?	Is the Domino server this driver is binding to when certifying new users a North American Domino server? This affects encryption levels. Choose Yes for 128 bit encryption.
ID File Expiration Term	Enter the expiration term (in years) for ID files created by the driver when certifying users added on the Subscriber channel.
Minimum Notes Password Length:	Enter the minimum password length for new Notes user IDs (0 - 16).
Default Notes User ID Password:	Enter the default password for new Notes user IDs.
Default Notes HTTP Password	Enter the default HTTP password for new Notes users.
Create Mail File?	Should the driver create a mail file for users certified to Notes on the subscriber channel?
Mail Database Storage Path:	Enter the relative path where the driver should create new Mail databases. The path should be relative to the Domino Data directory.
Notes Mail Database Template	Enter the relative path and file name (on the Domino server) for the Notes Mail Database Template this driver will use when creating new mail databases. The path should be relative to the Domino server's data directory.
Notes Mail Server	Enter the Name of the Notes Mail Server this driver will create new mail databases on (in fully qualified canonical form: i.e. cn=NotesServer/o=Organization).
Internet Mail Domain	Enter the Internet Mail Domain to be used when generating Internet e-mail addresses.
Deny Access Group Universal Note ID	Enter the Notes Universal ID for the Deny Access Group. This can be found on the Properties sheet for the Group in the Notes Client (32 characters long).
Publisher Channel Poll Rate	Enter the polling interval (in seconds) for how often the publisher channel will check the change log for updates.
Publisher placement destination path for USERS	Enter the eDirectory path where eDirectory users will be created.
Publisher placement destination path for GROUPS	Enter the eDirectory path where eDirectory groups will be created.
Subscriber placement source path for USERS	Enter the eDirectory path (subtree root) where user changes will be detected.
Subscriber placement source path for GROUPS:	Enter the eDirectory path (subtree root) where group changes will be detected.
Detect Event Loop Back?	Select Yes to prevent event loop back from occurring, or No to allow event loop back.
NDSREP Schedule Units	Enter the schedule units for the ndsrep polling interval.
NDSREP Schedule Value	Enter the schedule value for the ndsrep polling interval.
DNFormat	Enter the distinguished name format.
Check Attributes	Shall all attributes be checked for each object event?
Write Time Stamps	Shall driver time stamps be written to each synchronized object?
Enable Role-Based Entitlement features	Select Yes if you are using the Entitlements Driver and would like to include the role-based entitlement features provided by this driver configuration. This is a design decision. Don't choose this option unless you have reviewed the information about Role-Based Entitlements in the Novell Nsure Identity Manager 2 Administration Guide.
Install Driver as Remote/Local	Configure the driver for use with the Remote Loader service by selecting Remote, or select Local to configure the driver for local use. For information on how to decide, see Where to Install the Driver.
Remote Host Name and Port	(Remote Driver Configuration only) Enter the Host Name or IP Address and Port Number where the Remote Loader Service has been installed and is running for this driver. The Default Port is 8090.
Driver Password	(Remote Driver Configuration only) The Driver Object Password is used by the Remote Loader to authenticate itself to the DirXML server. It must be the same password that is specified as the Driver Object Password on the DirXML Remote Loader.
Remote Password	(Remote Driver Configuration only) The Remote Loader password is used to control access to the Remote Loader instance. It must be the same password that is specified as the Remote Loader password on the DirXML Remote Loader.

Configuring Database Replication Using ndsrep

Complete the following sections to configure replication using ndsrep:

Setting Up ndsrep

Review the information about ndsrep and starting the driver in the steps in Installing the Driver Shim.
Make sure you have copied the necessary files for your platform, as described in Installing the Driver Shim.
(Windows only) Add c:\lotus\domino to your system path, then reboot the computer.
Before trying to load ndsrep, make sure that the DirXML Driver for Lotus Notes has been started at least once.

Loading and Controlling 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 address book in the Domino server (or other Notes database), and copies these changes to the output database.

Loading ndsrep: Load ndsrep in the Domino Server console.

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
```
or

Type the following in the Notes Server Console window:
```
load ndsrep instance 
```
In either case, 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 will be loaded and referenceable 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
```
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 Customizing the Driver

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 eDirectory to an application. When you migrate an object, the DirXML 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 Novell eDirectory. When you migrate an object, the DirXML engine applies all of the Matching, Placement, and Create rules, as well as the Publisher filter, to the object. Objects are migrated into eDirectory using the order you specify in the Class list.
Synchronize: The DirXML 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:

In iManager, select DirXML Management > Overview.
Locate the driver set containing the Notes driver, then double-click the driver icon.
Click the appropriate migration button.

Activating the Driver

Activation must be completed within 90 days of installation, or the driver will not run.

For activation information, refer to "Activating Novell Identity Manager Products" in the Novell Nsure Identity Manager 2 Administration Guide.