PMDF System Manager's Guide
Previous Contents Index

3.2.7 LDAP or X.500 Directory Operations

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

When performing LDAP or X.500 directory look ups, the directory channel needs to know the LDAP server to which to connect and the point in the LDAP/X.500 hierarchy to which to bind and from which to base searches. Additional options, described in Section 3.2.7.3, may be used to control other aspects of the LDAP querying process.

3.2.7.1.1 LDAP_SERVERS Option

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


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

The LDAP_BASE option must also be specified in the option file. This option specifies the distinguished name of the location in the LDAP or X.500 directory information tree from which to base searches. The LDAP_BASE is specified in LDAP DN syntax according to RFC 1485; e.g., 


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

3.2.7.2 TLS Options

PMDF has the ability to access LDAP servers using TLS authentication. Note that in order to use this feature, your LDAP server must be set up to do TLS. To configure the directory channel to use TLS, you must specify the following 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

Additional channel options are shown below:

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

An example option file is shown below. 


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

The ldapfilter.conf file provided with PMDF supports a number of syntaxes. For the exact syntaxes supported, see the file itself, located in the PMDF table directory, and Section 3.2.7.6. Here are a few examples of syntaxes that are likely to match "Joe Wilson": 


"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

The file ldapfilter.conf contains information used by LDAP clients, e.g., the PMDF directory channel doing an LDAP or X.500 directory lookup. Blank lines and lines that start with the hash character, # , are treated as comments and ignored. The configuration information consists of lines that contain one to five tokens. Tokens are separated by white space. Double quotes can be used to include white space inside a token, e.g., "text moretext" .

3.2.7.6.1 Filter Sets

The file consists of a sequence of one or more filter sets. A filter set begins with a line containing a single token called a tag. The tag is used by the client to select the filter set.

3.2.7.6.2 Filter Lists

A filter set consists of a sequence of one or more filter lists. The first line in a filter list must contain four or five tokens: The value pattern, the delimiter list, a filter template, a match description, and an optional search scope.
  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 shows a sample LDAP filter configuration file containing one filter set, pmdf_lookup , which contains three filter lists.

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"

Previous Next Contents Index