PMDF System Manager's Guide
Previous Next Contents Index

37.6.3 The Lotus Notes Directory Agent

The SYNC_LN channel on the PMDF system, plus two main additional PMDF-DIRSYNC programs (one of which runs a third subsidiary program for the actual work) running on the Lotus Notes server, acts as a directory agent for Lotus Notes. On the PMDF system side of things, the SYNC_LN channel master program connects over TCP/IP to a server installed on the Notes system; the SYNC_LN channel slave program is itself a service which runs under the Dispatcher. On the Lotus Notes server system, the programs LDIF2LNM, LDIF2LN, and LN2LDIFM have to be installed on the Notes system, and LDIF2LNM and LN2LDIFM have to be scheduled to run at appropriate times.

37.6.3.1 Create a Directory on the Lotus Notes Server System

On the Lotus Notes server system you must create a scratch directory for the LDIF2LNM and LN2LDIFM programs' use. A typical name would be 


c:\tmp\dirsync\

37.6.3.2 Copy Images to the Lotus Notes Server System

The Lotus Notes directory agent images ldif2ln.exe, ldif2lnm.exe, ln2ldif.exe, and ln2ldifm.exe must be copied (installed) to the Lotus Notes program directory on the PC Lotus Notes server system.

For an NT (Intel hardware) based Lotus Notes server, copy the ldif2ln.exe, ldif2lnm.exe, ln2ldif.exe, and ln2ldifm.exe images from either the

directory on the PMDF system, or directly from the directory on the PMDF distribution CD-ROM (an ISO 9660 with Rockridge extensions CD-ROM directly readable from many platforms including most PC operating systems) to the Lotus Notes program directory on the PC server system.

For an OS/2 based Lotus Notes server, copy the ldif2ln.exe, ldif2lnm.exe, ln2ldif.exe, and ln2ldifm.exe images from either the

directory on the PMDF system, or directly from the directory on the PMDF distribution CD-ROM (an ISO 9660 with Rockridge extensions CD-ROM directly readable from many platforms including most PC operating systems) to the Lotus Notes program directory on the PC server system.

37.6.3.3 Configuring the Lotus Notes Directory Agent on the Lotus Notes Server

The Lotus Notes server system must be configured to run the LDIF2LNM Lotus Notes Service, and the LN2LDIFM program, at appropriate times; these programs control the Lotus Notes server side of the Lotus Notes directory agent. LN2LDIFM must be run whenever a directory needs to be sent into the dirsync process. The other process, LDIF2LNM, is a process that should be running at all times waiting for a connection from the PMDF system's SYNC_LN channel when the PMDF system has a directory update to send back to Lotus Notes.

LN2LDIFM takes a number of command line parameters but requires no other configuration. The command line parameters tell it what Notes database to read, what records are wanted from the database, and how to sent the information to the SYNC_LN channel on the PMDF system. Its command line format is: 


ln2ldifm server nsf dnf tmpdir host port maxtries retrywait
or 


ln2ldifm server nsf dnf tmpdir host port maxtries retrywait "selection-formula"
The meanings of the parameters are as follows:

server

This specifies the name of the Lotus Notes server. The special string - meaning the local server can also be used.

nsf

This specifies the file name of a Notes name and address book, for instance, names.nsf.

dnf

This specifies the name of the Lotus Notes directory attribute to use as the distinguished name field---the DN. This is used to determine which attribute is considered the unique identifier for the record. Given that the data will be going through a cook process that will determine its own order for the data, this is not a particularly powerful parameter. The attribute FullName is usually a good choice.

tmpdir

This specifies where the output LDIF file is staged before mailing.

host

This specifies the TCP/IP host where PMDF is running.

port

This specifies the port number of the SYNC_LN channel's slave direction server.

maxtries

This specifies the number of retry attempts to be made.

retrywait

This specifies the delay in seconds between retry attempts.

selection-formula

This optional parameter is a Lotus Notes selection formula. If omitted, the formula "select type=\"Person\"" is used. Note that the formula is case sensitive.

For instance, a sample invocation line might be: 


ln2ldifm - names.nsf FullName c:\tmp\dirsync host.example.com 9981 5 3600 "select type=\"Person\""

Note that an LN2LDIFM command needs to be issued for each name and address book that goes into the dirsync process.

For the other direction, the LDIF2LNM server should be installed on the Notes server so that it is always running. It is a very small program that receives data from the SYNC_LN master channel, puts it into a temporary file, and then runs another program, LDIF2LN, to process the data and update a Notes database. This approach ensures that the long running program does not need to use the Notes API and also ensures that there can not be any memory or handle "leaks", the bane of any program using the Notes API.

LDIF2LNM takes some command line parameters but requires no other configuration. Its command line format is: 


ldif2lnm port tmpfile subprogram nsf
The meanings of the parameters are as follows:

port

This specifies the port number on which to listen for connections from the PMDF system's SYNC_LN channel's master direction. Note therefore that this value must match that specified for the NOTES_PORT option in the corresponding sync_ln_*_option file.

tmpfile

This specifies where the LDIF file inbound to Lotus Notes is staged before processing (application as an update to a Lotus Notes name and address book).

subprogram

This is the name of the program to run to process the data, typically LDIF2LN, e.g., C:\notes\ldif2ln.exe.

nsf

This is the name of a Notes name and address book to be updated.

Note that a separate LDIF2LNM server process needs to be running for each name and address book update that comes back from the PMDF dirsync process.

37.6.3.3.1 Scheduling the Processes on the Lotus Notes Server

Recall that the LN2LDIFM program needs to be run on a schedule to send the directories into the dirsync process, and the LDIF2LNM program needs to be running constantly so it can receive directory updates when the PMDF dirsync process sends them.

There are a number of ways to arrange for LN2LDIFM to be run automatically on a schedule. One way is to NT Schedule service. There are two steps involved in doing this. The first is to ensure that the Schedule service is running and will be started automatically on a reboot. This is easiest to achieve by using the Services tool in the control panel. Find the Service called Schedule and check to see that its Status is Started, and Startup is Automatic. If its Status is not Started, highlight the service in the Services window and click on the Start button. If Startup is not Automatic, highlight the service and click on the Startup button and select Automatic in the panel that then appears. Once that Schedule service is running, you can use the at command to have a command issued on a regular basis. For instance to send the name and address book names.nsf at midnight each day, issue the command 


at 00:00 c:\notes\ln2ldifm - names.nsf FullName c:\temp pmdf.example.com 9745 360 "select type=\"Person\""

There are also a number of ways to make sure that the LDIF2LNM program gets started on a reboot. The best way is to use the program srvrany.exe from the NT resource kit. This is described in the file srvrany.wri on the NT resource kit CD.

37.6.3.4 Utility Programs for the Lotus Notes Server

Two utilities, LN2LDIF and LDIF2LN, are provided for running directly on the Lotus Notes server system. In production operation, LDIF2LN is normally run by the LDIF2LNM server, but can also be run as a standalone utility for testing. The main purpose of LN2LDIF is as a standalone test utility.

These utilities can assist in initial testing of the Lotus Notes directory format, possibly before setting up the full PMDF-DIRSYNC configuration. That is, these utilities can be used to extract Lotus Notes directory information to an LDIF file (to see just what attributes and typical values your Lotus Notes directory is actually using) and to test importing directory update information from a (perhaps manually generated) LDIF file on the Lotus Notes server system into your Lotus Notes directory. Such checking on the Lotus Notes directory attribute usage is likely to be necessary or at least desirable as a preliminary step in determining what to put in the recipe files for cooking and serving the Lotus Notes directory information.

These utilities are located on the PMDF system under the appropriate Lotus Notes platform subdirectory under pmdf_root:[other] (OpenVMS), /pmdf/other/ (unix), or C:\pmdf\other\ (NT), or directly from the [other.os2.notes] (OpenVMS), the /other/os2/notes/ (unix), or the \other\os2\notes\ (OS/2) directory on the PMDF distribution CD-ROM (an ISO 9660 with Rockridge extensions CD-ROM directly readable from many platforms including most PC operating systems) and should be installed on your Lotus Notes server system, as described above in Section 37.6.3.2.

The syntax of LN2LDIF is: 


ln2ldif server nsf dnf output-ldif-file
or 


ln2ldif server nsf dnf output-ldif-file "selection-formula"
and the syntax of LDIF2LN is: 


ldif2ln server nsf input-ldif-file
where the meanings of the parameters are as follows:

server

This specifies the name of the Lotus Notes server. The special string - can also be used.

nsf

This specifies the file name of a Notes name and address book.

dnf

This specifies the name of the Lotus Notes directory attribute to use as the distinguished name field---the DN.

output-ldif-file

input_ldif_file

This parameter gives the output LDIF file specification (LN2LDIF) or input LDIF file specification (LDIF2LN).

selection-formula

This optional parameter for LN2LDIF is a Lotus Notes selection formula.

For instance, a sample LN2LDIF invocation line might be: 


ln2ldif - names.nsf FullName c:\tmp\lndump.ldif "select type=\"Person\""
A sample LDIF2LN invocation line might be: 


ldif2ln - names.nsf testupd.ldif

37.6.3.5 Configuring the Lotus Notes Directory Agent on the PMDF System

On the PMDF system, the SYNC_LN channel must be configured. In addition to performing address entry transformations similar to those that a SYNC_LDIF channel might perform, this channel also performs the connection to the LDIF2LNM Lotus Notes Service and receives connections from the LN2LDIFM program; so in addition to configuration options similar to those for a SYNC_LDIF channel, it also requires the setting of TCP/IP connection based configuration options. The channel definition itself should be added to the PMDF configuration file. For instance, if the system on which the PMDF Lotus Notes directory agent runs is called example.com, then you could configure the PMDF Lotus Notes directory agent by adding the line 


lnsync.example.com     $U%lnsync.example.com@LNSYNC-DAEMON
to the rewrite rules section of the PMDF configuration file, and 


sync_ln_local single 
lnsync.example.com
to the channel definition section of the PMDF configuration file. In addition, there are several options that need to be set in the channel option file:
PMDF_TABLE:sync_ln_local_option. (OpenVMS) or
/pmdf/table/sync_ln_local_option (unix) or
C:\pmdf\table\sync_ln_local_option (NT). Required options are:

The available options are:

COOKIE_FILE (file-specification)

The COOKIE_FILE option tells the master channel program where to put the generated cookie, and tells the slave channel program where to find the saved cookie when it receives an LDIF file. The master channel program will overwrite any existing cookie when it generates a new one, and the slave channel program always deletes the cookie file once it has read the cookie.

DIRECTORY_MASTER (RFC 822 address)

This option specifies the e-mail address of a person to whom error reports can be sent.

DIRECTORY_ROBOT (RFC 822 address)

The DIRECTORY_ROBOT option gives the e-mail address of the DIRBOT to which incoming foreign directory information is to be sent once the SYNC_LN channel's slave program has processed it.

DIRNAME (string)

The DIRNAME option specifies the symbolic name of the directory that the SYNC_LN channel's slave program will read in.

NOTES_HOST (string)

The NOTES_HOST option specifies the TCP/IP name of the Lotus Notes server system.

NOTES_PORT (integer)

The NOTES_PORT option specifies the port number on which the LDIF2LNM Lotus Notes Service will be listening for connections from the PMDF system's SYNC_LN channel.

SECRET (string)

The SECRET option specifies the shared secret used by the Lotus Notes directory agent and the DIRBOTs to create and check signatures on directories.

The Dispatcher must also be configured to run the slave (server) portion of the SYNC_LN channel as a service. Such a service definition in the Dispatcher configuration file would on OpenVMS look like: 


[SERVICE=LNDIRSYNC] 
PORT=ln2ldifm-port
IMAGE=PMDF_EXE:sync_ln_slave.exe 
LOGFILE=PMDF_LOG:sync_ln_slave.log 
MIN_PROCS=0 
MAX_PROCS=1 
MIN_CONNS=1 
MAX_CONNS=1 
PARAMETER=channel=sync_ln_local
or on unix would look like: 


[SERVICE=LNDIRSYNC] 
PORT=ln2ldifm-port
IMAGE=/pmdf/bin/sync_ln_slave 
LOGFILE=/pmdf/log/sync_ln_slave.log 
MIN_PROCS=0 
MAX_PROCS=1 
MIN_CONNS=1 
MAX_CONNS=1 
PARAMETER=channel=sync_ln_local
or on NT would look like: 


[SERVICE=LNDIRSYNC] 
PORT=ln2ldifm-port
IMAGE=C:\pmdf\bin\sync_ln_slave 
LOGFILE=C:\pmdf\log\sync_ln_slave.log 
MIN_PROCS=0 
MAX_PROCS=1 
MIN_CONNS=1 
MAX_CONNS=1 
PARAMETER=channel=sync_ln_local
where ln2ldifm-port is the port to which the LN2LDIFM program is configured to send its updates.

Note that it is essential to set up a PORT_ACCESS mapping to control what systems can connect to the ln2ldifm-port so that only the Lotus Notes Server can connect and send updates, and so that no other system can send spoofed updates. By default, if you do not set up such a mapping, any system could potentially attempt to submit updates to the SYNC_LN channel's slave direction.

An overview of the PORT_ACCESS mapping can be found in Section 23.2.1; more generally, the PMDF mapping file itself is discussed in Chapter 5. To prohibit irregular access to the Lotus Notes directory agent port, you will need to have entries such as 


PORT_ACCESS 
 
  TCP|*|ln2ldifm-port|notes-host-ip|*    $Y 
  TCP|*|ln2ldifm-port|*|*                $N

Previous Next Contents Index