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.6.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.6.2 , may be used to
control other aspects of the LDAP querying process.
3.2.6.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.acme.comor
LDAP_SERVERS=192.135.12.1or
LDAP_SERVERS=ldap.acme.com+389
3.2.6.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=Acme Computing,st=California,c=US
3.2.6.2 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_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 and the DISPLAY_FILTERTAG option are used to specify the groups of rules to use. FILTERTAG specifies the rules used to deliver the message and DISPLAY_FILTERTAG specifies the rules used to generate a list of possible choices should the FILTERTAG rules not generate a single unique match. Normally, the FILTERTAG option is used to specify the same group of rules used to both deliver the message and to generate a list of possible choices. If DISPLAY_FILTERTAG is specified, FILTERTAG will only be used to deliver message and DISPLAY_FILTERTAG will be used to generated a list of possible choices for the sender to choose from. For instance, a site might wish to only forward e-mail onwards when an exact match can be found (have a rather restricted set of matching rules for the FILTERTAG option's rules), but to send back a more expansive list of approximate matches when an exact match cannot be found (have the DISPLAY_FILTERTAG option include some more lenient approximate matching rules). The default is pmdf_dirchan. Do not modify the suppliedldapfilter.conffile, as your changes will be lost when you upgrade or reinstall PMDF. Instead, to use a different file, see the FILTERFILE option.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 wish the directory channel to display the mail attribute when returning address choices to users. For example:DISPLAY_MAIL_TYPE=mailDISPLAY_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=Acme Computing,st=California,c=USFILTERFILE
The directory channel processes each name by performing a regular expression match on thepmdf_dirchangroup of rules in theldapfilter.conffile in the PMDF table directory, i.e., the filePMDF_TABLE:ldapfilter.conf(OpenVMS) or the file/pmdf/table/ldapfilter.conf(UNIX) or normally (the exact drive may be different depending upon installation) the fileC:\pmdf\table\ldapfilter.conf(NT). Do not modify the suppliedldapfilter.conffile, 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 OpenVMSFILTERFILE=PMDF_TABLE:acme_ldapfilter.txtor on UNIXFILTERFILE=/pmdf/table/acme_ldapfilter.txtor on NTFILTERFILE=C:\pmdf\table\acme_ldapfilter.txtThe defaultldapfilter.conffile contains a rich set of default rules which provide for exact and approximate matching of names and initials. However, if you wish to make changes, see the comments in the file and Section 3.2.6.5 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=acme_dirchanThe default ispmdf_dirchan. Do not modify the suppliedldapfilter.conffile, 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=titleWhile 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.6.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.6.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=pMDFMailAddressPASSWORD (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=secretIf 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=10The 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=UDPThe 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, Acme Computing, California, US" then the following table shows the results of various TRIM values.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.
TRIM Result 4 Joe User 3 Joe User, Accounting 0 Joe User, Accounting, Acme Computing, California, US -1 Joe User -2 Joe User, Accounting
3.2.6.3 Example option files
An example option file is shown below.
acme.com=2 LDAP_SERVERS=ldap.acme.com LDAP_BASE=o=Acme Computing,st=California,c=USThe acme.com=2 option specifies that LDAP directory or X.500 directory operations are to be done for the acme.com pseudo domain. The LDAP server ldap.acme.com is used; queries will begin at the position o=Acme 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.
acme.com=2 sales.acme.com=2 LDAP_SERVERS=ldap.acme.com acme.com_LDAP_BASE=o=Acme Computing, st=California, c=US acme.com_TRIM=3 acme.com_HINT_TYPE=title sales.acme.com_LDAP_BASE=ou=Sales, o=Acme Computing, st=California, c=US sales.acme.com_TRIM=4 sales.acme.com_HINT_TYPE=telephoneNumber
3.2.6.4 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.6.5 . Here
are a few examples of syntaxes that are likely to match "Joe
Wilson":
"Joe Wilson"@acme.com Joe_Wilson@acme.com Joe.Wilson@acme.com J.Wilson@acme.com Wilson@acme.com Wilsen@acme.com title=President@acme.comThe last example is valid if the value of title in Joe Wilson's entry is President.
3.2.6.5 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.6.5.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.6.5.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.
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
|
One "match description" match was found for...and
Three "match description" matches were found for....
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.6.5.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"