PMDF System Manager's Guide

The LDAP directory agent communicates with an LDAP directory, or via LDAP with an X.500 directory. The LDAP directory agent is a PMDF channel, and hence must be added to the PMDF configuration like any other channel. For instance, if the system on which the LDAP directory agent runs is called example.com, then you could configure the LDAP channel by adding the line

ldapsync.example.com $U%ldapsync.example.com@LDAP-DAEMON

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

sync_ldap_local single LDAP-DAEMON

to the channel definition section of the PMDF configuration file.

The master direction of the 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; for instance, every night at 22:00, or every Friday night, or the like, as appropriate for the site. On unix this could be done by adding a line similar to the following to /var/spool/cron/crontabs/pmdf:

17 22 * * 5 pmdf run sync_ldap_local slave

That arranges that the SYNC_LDAP_LOCAL channel is run in slave mode every Friday night at 10:17 PM.

In addition, there are a number of options that need to be set in the channel option file:
PMDF_TABLE:sync_ldap_local_option. (OpenVMS) or
/pmdf/table/sync_ldap_local_option (unix) or
C:\pmdf\table\sync_ldap_local_option (NT). Required options are:

• COOKIE_FILE,
• DIRECTORY_MASTER,
• DIRECTORY_ROBOT,
• DIRNAME,
• LDAP_BASE,
• LDAP_SERVER,
• LDAP_PASSWORD,
• LDAP_USER, and
• SECRET.

The available options are:

COOKIE_FILE (file-specification)

This 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 specifies the e-mail address of a person to whom error reports can be sent.

DIRECTORY_ROBOT (RFC 822 address)

This gives the e-mail address of the DIRBOT to which the directory is to be sent once the LDAP slave program has extracted it from the LDAP or X.500 directory.

DIRNAME (string)

The DIRNAME specifies the enterprise wide name by which this LDAP or X.500 directory is to be known for directory synchronization purposes. This is the name that will be used in SYNC_DIRBOT channel options files in COOK, SERVE, DIFF or BULK_LOAD options.

FILTER (LDAP-filter)

The FILTER option specifies an LDAP filter to be applied to the LDAP directory to limit the information to be extracted to only those entries of interest. If this is not specified, the program uses a filter of (objectclass=*).

LDAP_BASE (distinguished-name)

The LDAP_BASE option specifies the LDAP or X.500 subtree to be extracted by the SYNC_LDAP slave program. Specifying LDAP_BASE=, i.e., with no value, means to extract the entire DIT from the root.

LDAP_BASE_n (distinguished-name)

If you want to extract multiple subtree portions of the LDAP or X.500 DIT, then in addition to specifying the LDAP_BASE option you can also specify LDAP_BASE_1, LDAP_BASE_2, etc., options, telling the channel additional subtree portions to extract.

LDAP_DEREF (0, 1, 2, or 3)

This option can be used to set the level of LDAP dereferencing. The default is LDAP_DEREF=0, which means that aliases are never dereferenced. A value of 1 means that aliases should be dereferenced during a search but not when locating the base object of the search. A value of 2 means that aliases should be dereferenced when locating the base object of a search, but not when doing the searching itself. A value of 3 means to dereference aliases both when locating the base object and for searching.

LDAP_LIMIT (integer)

To allow for overlapped operations, the SYNC_LDAP channel performs several LDAP operations concurrently. Some LDAP servers do not respond well to this optimization. The default value is 2 which seems to give good results with both the LDAP server and with Microsoft Exchange. It can be set to any value between 1 and 32. Use 1 only if 2 does not work as it significantly slows down operations. Increasing the value above 8 seems not to give any benefit.

LDAP_PAGE (integer)

This option affects operational performance of the SYNC_LDAP channel. A value such as 2000 tends to give the best performance for LDAP servers accessing an X.500 back-end; very large values, such as 2**31, tend to give the best performance for stand-alone LDAP directories. If MSX=1 is set, a value of 2**31 will be used, regardless of any setting of LDAP_PAGE.

LDAP_REFERRALS (0 or 1)

This option controls whether or not LDAP referrals are honored when extracting information from an LDAP directory. LDAP_REFERRALS=0, the default, means not to honor referrals; LDAP_REFERRALS=1 means to honor referrals.

LDAP_SERVER (hostname[+port])

The LDAP_SERVER option must be used to specify the LDAP server and port to which to connect. The format of this option is

LDAP_SERVER=host+port

A host must be specified. The port number can optionally be specified; the default port, if none is specified, is port 389---the standard port for LDAP servers.

LDAP_USER (string)

LDAP_PASSWORD (string)

These options specify the credentials to be used by the SYNC_LDAP channel programs to bind to the LDAP server.

LEAF_OBJECT (string)

Setting leaf_object to a named object, e.g., person, advises the SYNC_LDAP channel that that is a leaf object in the DIT (Directory Information Tree). This can halve the time taken to extract the data from the directory.

MSX (0 or 1)

The standard, and efficient, way of obtaining a distinguished name is to request an attribute that doesn't exist. However, some LDAP servers, such as Microsoft Exchange's LDAP server, deviate from the LDAP standard and will not return any data to such requests. Setting MSX=1 causes the SYNC_LDAP channel to perform a higher overhead request that will cause standards-incompliant servers such as Microsoft's to return the desired information. The default value is 0, meaning to perform a normal, efficient request. Note that setting MSX=1 also causes an LDAP_PAGE value of 2**31 to be used.

SECRET (string)

This is the shared secret used by the LDAP agent and the DIRBOTS to create and check signatures on directories.

SCOPE_SUBTREE (0, 1, or 2)

Setting SCOPE_SUBTREE=1 causes the SYNC_LDAP channel to request the entire directory tree at once when extracting information from the directory. The default value of 0 causes the channel to instead request the directory one level at a time. If the directory being queried supports returning the entire subtree, it can be a faster operation than returning levels individually. In particular, setting SCOPE_SUBTREE=1 will cause a several-fold increase in extraction speed when querying an IDDS directory. The default value of 0 is recommended when querying an MS Exchange LDAP directory. Setting SCOPE_SUBTREE=2 causes PMDF to request only the entries that are the immediate children of the LDAP_BASE you have specified.

Example 37-4 Sample SYNC_LDAP Channel Option File on unix

DIRECTORY_MASTER=dirmaster@example.com SECRET=neveryoumind COOKIE_FILE=/pmdf/table/green.cookie DIRECTORY_ROBOT=dirbot@dirsync.example.com DIRNAME=green LDAP_SERVER=example.com LDAP_PASSWORD=noneofyorbusiness LDAP_USER=cn=foo bar LDAP_BASE=o=Green Group FILTER=(objectclass=person) LDAP_LIMIT=2