PMDF System Manager's Guide

When a service type of 2 is specified, the directory channel performs LDAP queries, querying an LDAP directory or X.500 DSA via an LDAP server, to look up mailbox names. The types of queries can be controlled with an LDAP filter file (e.g., exact matches, fuzzy matches, searches down the entire directory, etc.). In the event of an ambiguous match, the possible choices can be returned along with the original message to the message originator.

The directory channel queries an LDAP directory or X.500 DSA via either a local or remote LDAP server. TCP/IP is used to communicate with the LDAP server; on OpenVMS systems UCX emulation is required of your TCP/IP package.

3.2.7.1 Required Options

3.2.7.1.1 LDAP_SERVERS Option

LDAP_SERVERS=host1+port1|host2+port2|host3+port3...

At least one host must be specified. Hosts may be specified either by name, or by IP address. The port number may optionally be specified. Additional hosts and ports may optionally be specified; when multiple hosts are specified, they will be tried in left to right order. The default port, if none is specified, is port 389---the standard port for LDAP servers. For example,

LDAP_SERVERS=ldap.example.com

or

LDAP_SERVERS=192.135.12.1

or

LDAP_SERVERS=ldap.example.com+389

3.2.7.1.2 LDAP_BASE Option

LDAP_BASE=o=Example Computing,st=California,c=US

3.2.7.2 TLS Options

TLS_MODE (1 or 2)

The TLS_MODE option is used to specify whether to use TLS. A value of 1 tells the directory channel to try to use TLS, but continue without it if TLS is not available. A value of 2 tells the directory channel to require TLS. The default is to not use TLS.

CACERTFILE (file name)

You may need to have the Certificate Authority (CA) certificate to be used by LDAP on your PMDF system. If so, by default the CA certificate should be placed in the file pmdf_table:ldap-cacert.pem. Use the CACERTFILE option if you wish to specify a different file name, for example if you need to use different CA certificates for different domains.

An example directory channel option file which includes TLS options is as follows:

example.org=2 example.org_ldap_servers=ldap.example.org example.org_ldap_base=dc=ldap.example,dc=com example.org_tls_mode=2 example.org_cacertfile=/pmdf/table/example-cacert.pem

3.2.7.3 Additional Options

BIND (0 or 1)

The BIND option is used to specify whether an LDAP bind operation is sent to the LDAP directory before a search operation is attempted. Unlike LDAPv2, LDAPv3 does not require a bind operation to take place. The default value is 1, meaning that a bind operation will be performed. If authentication is not required on the LDAPv3 server, performance can be improved by disabling bind operations by setting BIND=0. The BIND option is ignored when using the connectionless protocol over a UDP transport.

DISPLAY_MAIL_TYPE (attribute type)

When multiple matches to a search are found, the directory channel returns choices to the sender. The directory channel returns the distinguished name and e-mail address. By default, the e-mail address which the channel would use to deliver the mail (as specified by the MAIL_TYPE option) is displayed in such returns. The DISPLAY_MAIL_TYPE option can be used to specify an alternate mail address attribute to be returned. In particular, when redefining MAIL_TYPE to something other than the mail attribute, you may still want the directory channel to display the mail attribute when returning address choices to users. For example:

DISPLAY_MAIL_TYPE=mail

DISPLAY_MAIL_TYPE defaults to the value of MAIL_TYPE if not specified.

DN

The DN option is used to specify the LDAP or X.500 Distinguished Name used to bind to the LDAP directory or X.500 DSA --- the DN is essentially the username to use to login to the server --- although when using the directory channel over UDP transport, the DN is used by the LDAP server only for logging purposes and it is not passed to an X.500 DSA (if an X.500 DSA is backing up the LDAP server) during the bind. The DN is specified in LDAP DN syntax according to RFC 1485; e.g.,

DN=cn=Directory Channel,o=Example Computing,st=California,c=US

FILTERFILE

The directory channel processes each name by performing a regular expression match on the pmdf_dirchan group of rules in the ldapfilter.conf file in the PMDF table directory, i.e., the file PMDF_TABLE:ldapfilter.conf (OpenVMS) or the file /pmdf/table/ldapfilter.conf (UNIX) or normally (the exact drive may be different depending upon installation) the file C:\pmdf\table\ldapfilter.conf (NT). Do not modify the supplied ldapfilter.conf file, as your changes will be lost when you upgrade or reinstall PMDF. Instead, to use a different file, specify the FILTERFILE option with the filename of the desired file. For example, on OpenVMS

FILTERFILE=PMDF_TABLE:example_ldapfilter.txt

or on UNIX

FILTERFILE=/pmdf/table/example_ldapfilter.txt

or on NT

FILTERFILE=C:\pmdf\table\example_ldapfilter.txt

The default ldapfilter.conf file contains a rich set of default rules which provide for exact and approximate matching of names and initials. However, if you want to make changes, see the comments in the file and Section 3.2.7.6 for details. The filters specified in this file are as defined in RFC 2254 (which obsoletes RFCs 1960 and 1558, the earlier descriptions of such filters).

FILTERTAG

The directory channel processes each name by performing a regular expression match on a group of rules found in the file specified by the FILTERFILE option. The FILTERTAG option is used to specify the group of rules to use. For example:

FILTERTAG=example_dirchan

The default is pmdf_dirchan. Do not modify the supplied ldapfilter.conf file, as your changes will be lost when you upgrade or reinstall PMDF. Instead, to use a different file, see the FILTERFILE option.

HINT_TYPE

When multiple matches to a search are found, the directory channel returns choices to the sender. In addition to the distinguished name and e-mail address, the directory channel can optionally return one more attribute from the entries to help the sender choose between them. For example,

HINT_TYPE=title

While any attribute can be specified, some suggestions are title, uid, telephoneNumber, or description.

LDAP_BASE (distinguished name)

The LDAP_BASE specifies the distinguished name of the location in the LDAP or X.500 directory information tree from which to base searches. See Section 3.2.7.1.2 for details.

LDAP_SERVERS (domain name or IP address)

The LDAP_SERVERS option is used to specify the IP address or domain name of the LDAP server to use. See Section 3.2.7.1.1 for details.

MAIL_TYPE (attribute type)

When the directory channel searches the LDAP directory or X.500 directory for a name, it requests that an e-mail address be returned. The MAIL_TYPE option is used to specify the attribute type requested from the directory. MAIL_TYPE must match the attribute type returned by your LDAP server; (while servers may accept aliases, they return one specific attribute type with the value). The default is MAIL_TYPE=mail. You may need to specify this option if you are using a non-PMDF LDAP server or you are using an LDAP or X.500 schema other than COSINE/Internet schema (RFC 1274). You will want to specify this option if you use a different directory attribute, such as pMDFMailAddress to specify a local delivery address. For example:

MAIL_TYPE=pMDFMailAddress

PASSWORD (string)

The PASSWORD option is used to specify a simple authentication credential to be sent with the DN (that specified by the DN option) when binding to the LDAP directory or X.500 DSA. This can be used to allow the directory channel more access to the directory than is allowed for anonymous users. For example:

PASSWORD=secret

If a PASSWORD is specified, a DN must also be specified, although a DN may be specified without a PASSWORD. The PASSWORD value is ignored when using the connectionless protocol over a UDP transport.

SIZELIMIT (integer >= -1)

When the directory channel performs a search for an e-mail address, many entries may match the search criteria. If this is the case, the original mail message is returned to the sender along with a list of possible address choices. The SIZELIMIT option controls the maximum number of choices which are returned; e.g.,

SIZELIMIT=10

The default value for SIZELIMIT is 50. You may want to make this limit smaller to reduce "trawling" of your database. Note that this limit may be superseded by a smaller limit which has been imposed by the manager of the LDAP directory or X.500 DSA. Specify a value of -1 to allow any number of matches to be returned; specify a value of 0 to suppress the return of possible matches. Note that this is a change of behavior from versions of PMDF prior to V5.1-9 when a value of 0 allowed any number of matches to be returned.

TRANSPORT (TCP or UDP)

The TRANSPORT option is used to specify whether to use connection oriented LDAP protocol over TCP or connectionless oriented protocol over UDP. For example:

TRANSPORT=UDP

The default is TRANSPORT=TCP. When running over UDP, the slightly different CLDAP protocol is actually used. CLDAP is more suited for lower overhead over reliable network connections. Use LDAP over TCP if you may have packet loss to your server. When using UDP, all information must fit in a single UDP datagram. If you use UDP, it is suggested that you specify a small SIZELIMIT option, e.g., 10 or less. If the response from the LDAP server exceeds the size of a UDP datagram, you will not get any choices returned for ambiguous names.

TRIM (integer)

When multiple matches to a search are found, the directory channel returns to the sender a list of the matches. TRIM affects the level of detail provided in the returned information. If TRIM is a positive integer, it specifies how many elements to trim off of each matching distinguished name starting with the most general element and working down to the most specific element. A TRIM value of zero specifies that no trimming is to be done. A negative value specifies the number of elements to leave. For example, if the returned match is Joe User, Accounting, Example Computing, California, US then the following table shows the results of various TRIM values.

TRIM	Result
4	Joe User
3	Joe User, Accounting
0	Joe User, Accounting, Example Computing, California, US
-1	Joe User
-2	Joe User, Accounting

The default value of TRIM is -1 so that only the most specific element is returned. A common choice for TRIM is the number of elements in your LDAP_BASE distinguished name.

3.2.7.4 Example Option Files

example.com=2 LDAP_SERVERS=ldap.example.com LDAP_BASE=o=Example Computing,st=California,c=US

The example.com=2 option specifies that LDAP directory or X.500 directory operations are to be done for the example.com pseudo domain. The LDAP server ldap.example.com is used; queries will begin at the position o=Example Computing, st=California, c=US in the LDAP or X.500 directory hierarchy.

Shown below is an example of an option file for a directory channel which services two different pseudo domains.

example.com=2 sales.example.com=2 LDAP_SERVERS=ldap.example.com example.com_LDAP_BASE=o=Example Computing, st=California, c=US example.com_TRIM=3 example.com_HINT_TYPE=title sales.example.com_LDAP_BASE=ou=Sales, o=Example Computing, st=California, c=US sales.example.com_TRIM=4 sales.example.com_HINT_TYPE=telephoneNumber

3.2.7.5 Default Mailbox Syntax Supported

"Joe Wilson"@example.com Joe_Wilson@example.com Joe.Wilson@example.com J.Wilson@example.com Wilson@example.com Wilsen@example.com title=President@example.com

The last example is valid if the value of title in Joe Wilson's entry is President.

3.2.7.6 LDAP Filter Configuration File, ldapfilter.conf

3.2.7.6.1 Filter Sets

3.2.7.6.2 Filter Lists

1. The value pattern is a regular expression that is matched against the search value passed by the client to select the filter list to be used.
2. The delimiter list is a list of characters (in the form of a single string) that are used to break the search value into distinct words.
3. The filter template is used to construct an LDAP filter. Standard LDAP filter format as specified in RFC 1960 (which obsoletes RFC 1558) is used. The filter template is similar in concept to a C language printf style format string. Everything is taken literally except for the character sequences:

   Sequence	Description
   %v	Substitute with entire search string value
   %v$	Substitute with last word of search string value
   %v n	Substitute word n ; n is a single digit 1-9
   %v m - n	Substitute words m through n
   %v m -	Substitute word m through the last word

   Words are numbered from 1 to 9, left to right.
4. The match description is used as information to describe the sort of LDAP search that took place. It should correctly complete both of the following phrases:

   One "match description" match was found for...

   and

   Three "match description" matches were found for....

5. The search scope is optional, and should be one of base onelevel, or subtree. If search scope is not provided, the default is subtree.

The remaining lines of the filter list should each contain two or three tokens: A filter template, a match description and an optional search scope. The value pattern and delimiter list tokens are the same as previously specified.

3.2.7.6.3 Example LDAP Filter Configuration File

Example 3-6 Sample LDAP Filter File

# ldap filter file # pmdf_lookup "[0-9][0-9-]*" " " "(telephoneNumber=*%v)" "phone number" "@" " " "(mail=%v)" "email address" "(mail=%v*)" "start of email address" "=" " " "%v" "arbitrary filter"