PMDF System Manager's Guide

The LDIF directory agent is a generic agent, used where there is not a specific agent for a directory. The generic LDIF directory agent can be combined with PMDF-DIRSYNC command line utilities, or site supplied procedures, to form an effective directory agent for a wide variety of directories. Examples of directories where an LDIF directory agent could be used include cc:Mail, Microsoft Mail, GroupWise, and ALL-IN-1. Discussions of these sorts of usages can be found in Section 37.6.4.1, Section 37.6.4.2, Section 37.6.4.3, and Section 37.6.4.4 below.

For cc:Mail, for instance, there is no programmatic interface to the cc:Mail directory, and hence there is no PMDF channel specifically for communicating with a cc:Mail directory. However, there is a utility which takes an LDIF file and generates a cc:Mail directory import file, and another utility which takes a cc:Mail directory export file and generates an LDIF file. Combining the LDIF directory agent with these two utilities, packaged in some procedure to run periodically, produces an effective "directory agent" for cc:Mail.

The LDIF directory agent is implemented as a PMDF channel, the SYNC_LDIF channel. When a DIRBOT sends a directory update to an SYNC_LDIF channel, the SYNC_LDIF channel arranges for the delivery of the LDIF file to the PMDF-DIRSYNC work directory with all the checking of signatures and cookies, but does no other direct processing of the file, though a hook is provided for sites to supply their own commands for further processing of the file. The file that the SYNC_LDIF channel writes to the work directory will be named dirname.ldif where dirname is the symbolic name of the directory (from a parameter on the directory information in the incoming message). When the slave direction of the SYNC_LDIF channel is executed, the SYNC_LDIF channel optionally executes a site supplied script of commands and then reads in an LDIF file and sends it to a DIRBOT for further processing.

As with any other channel, the SYNC_LDIF channel requires some configuration, starting with defining it in the PMDF configuration file. For instance if the machine on which the LDIF directory agent is called example.com, then you could configure the SYNC_LDIF channel by adding the line

ldifsync.example.com $U%ldifsync.example.com@LDIF-DAEMON

to the rewrite rules section of the PMDF configuration file, and

sync_ldif_local single LDIF-DAEMON

to the channel definition section.

The master direction of the SYNC_LDIF channel will be run automatically, just as for any other master channel. The slave direction of the channel needs to be scheduled to run at an appropriate time, every night at 22:00, or every Friday night or whatever is appropriate for the site. On unix this could be done by adding a line similar to the following to /var/spool/cron/crontabs/pmdf:

57 22 * * 5 pmdf run sync_ldif_local slave

That arranges that the SYNC_LDIF_LOCAL channel's slave direction is run every Friday night at 10:57 PM.

In addition, there are a number of options that need to be set in the channel option file:
PMDF_TABLE:sync_ldif_local_option. (OpenVMS) or
/pmdf/table/sync_ldif_local_option (unix) or
C:\pmdf\table\sync_ldif_local_option (NT). These 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 will overwrite any existing cookie when it generates a new one, and the slave 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_LDIF channel's slave program has processed it.

DIRNAME (string)

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

MASTER_COMMAND (DCL command (OpenVMS) or shell command (unix and NT))

This option can be used to specify a DCL or shell command to execute after the LDIF channel's master program has finished its own processing and deposited an LDIF file in the PMDF-DIRSYNC work directory; this is a "hook" so that sites can execute their own site-specific procedures for actually updating the directory. The name of the LDIF file that the SYNC_LDIF channel has created will be passed as a parameter to the shell command; specifically, the name of the file is always PMDF_DIRSYNC:dirname.ldif on OpenVMS, or /pmdf/dirsync/dirname.ldif on unix or typically C:\pmdf\dirsync\dirname.ldif on NT, where dirname is the symbolic name of the directory (from a parameter on the directory information in the incoming message).

SECRET (string)

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

SLAVE_COMMAND (DCL command (OpenVMS) or shell command (unix and NT))

This option can be used to specify a DCL or shell command to execute before the LDIF channel's slave program begins its own processing; this is a "hook" so that sites can execute their own site-specific procedures for actually fetching a foreign directory. The name of the LDIF file that the LDIF channel will expect to read in after the command is executed, i.e., the value of the SLAVE_FILE option, will be passed as a parameter to the shell command.

SLAVE_FILE (file-specification)

The SLAVE_FILE option specifies the file originating from a foreign directory that is to be read in by the SYNC_LDIF channel and sent to the DIRBOT; that is, the name of the file read by the channel's slave program. For instance,

SLAVE_FILE=/pmdf/dirsync/ccmail2pmdf.ldif

Example 37-5 shows a sample generic LDIF channel option file, for a SYNC_LDIF channel that simply generates an LDIF file. Examples of additional SYNC_LDIF channel option files of the sort that might be used when using a SYNC_LDIF channel as part of some specific sort of directory agen, can be found in the subsections below.

Example 37-5 Sample SYNC_LDIF Channel Option File on unix

DIRECTORY_MASTER=dirmaster@example.com SECRET=neveryoumind COOKIE_FILE=/pmdf/table/genericldif.cookie DIRECTORY_ROBOT=dirbot@dirsync.example.com DIRNAME=genericldif SLAVE_FILE=/pmdf/dirsync/ldif2dir.ldif

37.6.4.1 Producing a cc:Mail Directory Agent

So with a master command script as shown in Example 37-7 and a slave command script as shown in Example 37-8, a SYNC_LDIF channel option file could be as shown in Example 37-6.

Example 37-6 Sample SYNC_LDIF Channel Option File for a cc:Mail Directory Agent on unix

DIRECTORY_MASTER=dirmaster@example.com SECRET=neveryoumind COOKIE_FILE=/pmdf/table/ccmail.cookie DIRECTORY_ROBOT=dirbot@dirsync.example.com DIRNAME=ccmail MASTER_COMMAND=/ccsync/dir2cc.sh SLAVE_COMMAND=/ccsync/cc2dir.sh SLAVE_FILE=/pmdf/dirsync/cc.ldif

Example 37-7 Sample Master Command Script for cc:Mail Directory Updating

pmdf dirsync -convert LDIF=/pmdf/dirsync/cc.ldif \ CC=/pmdf/dirsync/ccupdate.ldif # # Trigger execution of some job that transfers the ccupdate.ldif # file to the cc:Mail postoffice system and then triggers import # of the file into cc:Mail. #

Example 37-8 Sample Slave Command Script for cc:Mail Directory Input

pmdf dirsync -convert CC=/pmdf/dirsync/ccdump.ldif \ LDIF=/pmdf/dirsync/cc.ldif

The above example command scripts do not show taking care of actually transferring the cc:Mail directory information to an actual cc:Mail system and importing and exporting the cc:Mail directory information to a cc:Mail postoffice directory.

The Lotus IMPORT command for importing directory information into a cc:Mail directory from a specially formatted file (which is the file format created by the PMDF DIRSYNC LDIF=file-spec CC=file-spec (OpenVMS) or pmdf dirsync -convert LDIF=file-spec CC=file-spec (unix and NT) utility) has the syntax:

IMPORT po password po-path dir-file DIRECTORY/options

and the Lotus EXPORT command for exporting directory information from a cc:Mail directory into a specially formatted file (which can be processed into an LDIF file using the PMDF DIRSYNC/CONVERT CC=file-spec LDIF=file-spec (OpenVMS) or pmdf dirsync -convert CC=file-spec LDIF=file-spec (unix and NT) utility) has the syntax:

EXPORT po password po-path dir-file DIRECTORY/options

where po is the name of the cc:Mail postoffice to which to import the directory update, password is the password for that cc:Mail postoffice, po-path is the full file path specification for the location of the cc:Mail postoffice files, dir-file is the cc:Mail directory update file to import, the DIRECTORY parameter is required, and additional optional option qualifiers to the DIRECTORY parameter can be specified.

See your Lotus cc:Mail IMPORT/EXPORT documentation for further details on use of these Lotus utilities.

37.6.4.2 Producing a Microsoft Mail Directory Agent

So with a master command script as shown in Example 37-10 and a slave command script as shown in Example 37-11, a SYNC_LDIF channel option file could be as shown in Example 37-9.

Example 37-9 Sample SYNC_LDIF Channel Option File for a Microsoft Mail Directory Agent on unix

DIRECTORY_MASTER=dirmaster@example.com SECRET=neveryoumind COOKIE_FILE=/pmdf/table/msmail.cookie DIRECTORY_ROBOT=dirbot@dirsync.example.com DIRNAME=msmail MASTER_COMMAND=/mssync/dir2ms.sh SLAVE_COMMAND=/mssync/ms2dir.sh SLAVE_FILE=/pmdf/dirsync/msm.ldif

Example 37-10 Sample Master Command Script for Microsoft Mail Directory Updating

pmdf dirsync -convert LDIF=/pmdf/dirsync/msm.ldif \ MSMAIL=/pmdf/dirsync/msupd.ldif # # Trigger execution of some job that transfers the msupd.ldif # file to the MS Mail postoffice system and then triggers import # of the file into MS Mail. #

Example 37-11 Sample Slave Command Script for Microsoft Mail Directory Input

pmdf dirsync -convert MSMAIL=/pmdf/dirsync/ms2dump.ldif \ LDIF=/pmdf/dirsync/msm.ldif

The above example command scripts do not show taking care of actually transferring the Microsoft Mail directory information to an actual Microsoft Mail system and importing and exporting the Microsoft Mail directory information to a Microsoft Mail postoffice directory.

The Microsoft command for importing directory information into a Microsoft Mail directory from a specially formatted file (which is the file format created by the PMDF DIRSYNC/CONVERT LDIF=file-spec MSMAIL=file-spec (OpenVMS) or pmdf dirsync -convert LDIF=file-spec MSMAIL=file-spec (unix and NT) utility) has the syntax:

IMPORT ADMIN -Ppassword -X -Ffile-spec -T

and the Microsoft export command for exporting directory information from a Microsoft Mail directory into a specially formatted file (which can be processed into an LDIF file using the PMDF DIRSYNC/CONVERT MSMAIL=file-spec LDIF=file-spec (OpenVMS) or pmdf dirsync -convert MSMAIL=file-spec LDIF=file-spec (unix and NT) utility) has the syntax:

IMPORT ADMIN -Ppassword -Ffile-spec -A

where password is the Administrator password for the Microsoft Mail postoffice from which or to which directory information is being exchanged, and file-spec is the directory update file to import or export, respectively. The -X switch makes the operation an export (from Microsoft Mail's directory to a file), rather than an import (from a file to Microsoft Mail's directory). The -T switch on exports causes preservation of template file information. The -A switch on imports puts all of the imported addresses into the main postoffice address list. If you want to have the imported addresses propogated to other Microsoft Mail postoffices, you should also include the -E switch.

For further details on the use of the Microsoft IMPORT ADMIN command, see your Microsoft Mail documentation, particularly the Microsoft Mail Administrator's Guide.

37.6.4.3 Producing a WordPerfect Office (GroupWise) Directory Agent

37.6.4.4 Producing an ALL-IN-1 Directory Agent (OpenVMS)

So a sample SYNC_LDIF channel option file for an ALL-IN-1 directory agent could be as shown in Example 37-12.

Example 37-12 Sample SYNC_LDIF Channel Option File for an ALL-IN-1 Directory Agent

DIRECTORY_MASTER=dirmaster@example.com SECRET=neveryoumind COOKIE_FILE=PMDF_TABLE:a1.cookie DIRECTORY_ROBOT=dirbot@dirsync.example.com DIRNAME=a1 MASTER_COMMAND=PMDF DIRSYNC/CONVERT LDIF=PMDF_DIRSYNC:a1.ldif \ A1/OPTION=PMDF_TABLE:sync_ldif_a1_option. SLAVE_COMMAND=PMDF DIRSYNC/CONVERT A1 \ LDIF=PMDF_DIRSYNC:a12dir.ldif/OPTION=PMDF_TABLE:sync_ldif_a1_option.

37.6.4.5 Producing a DDS Directory Agent (OpenVMS)

So a SYNC_LDIF channel option file for a DDS directory agent could be as shown in Example 37-13.

Example 37-13 Sample SYNC_LDIF Channel Option File for a DDS Directory Agent

DIRECTORY_MASTER=dirmaster@example.com SECRET=neveryoumind COOKIE_FILE=PMDF_TABLE:dds.cookie DIRECTORY_ROBOT=dirbot@dirsync.example.com DIRNAME=dds MASTER_COMMAND=PMDF DIRSYNC/CONVERT LDIF=PMDF_DIRSYNC:dds.ldif \ DDS/OPTION=PMDF_TABLE:sync_ldif_dds_option. SLAVE_COMMAND=PMDF DIRSYNC/CONVERT DDS \ LDIF=PMDF_DIRSYNC:dds2dir.ldif/OPTION=PMDF_TABLE:sync_ldif_dds_option.