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.
188.8.131.52 Required Options
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 184.108.40.206, may be used to control other aspects of the LDAP
220.127.116.11.1 LDAP_SERVERS Option
LDAP_SERVERS option must be used to specify the LDAP
server and port to which to connect. The format of this option is
18.104.22.168.2 LDAP_BASE Option
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
LDAP_BASE is specified in
DN syntax according to RFC 1485; e.g.,
22.214.171.124 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_MODEoption 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
CACERTFILEoption if you wish to specify a different file name, for example if you need to use different CA certificates for different domains.
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
126.96.36.199 Additional Options
Additional channel options are shown below:
BIND (0 or 1)The
BINDoption is used to specify whether an LDAP bind operation is sent to the
LDAPdirectory 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
BINDoption 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
directorychannel returns choices to the sender. The
directorychannel 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_TYPEoption) is displayed in such returns. The
DISPLAY_MAIL_TYPEoption can be used to specify an alternate mail address attribute to be returned. In particular, when redefining
MAIL_TYPEto 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_TYPEdefaults to the value of
MAIL_TYPEif not specified.
DNThe DN option is used to specify the
X.500 Distinguished Nameused to bind to the
X.500 DSA--- the
DNis essentially the username to use to login to the server --- although when using the
directorychannel over UDP transport, the
DNis 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 DNsyntax according to RFC 1485; e.g.,
DN=cn=Directory Channel,o=Example Computing,st=California,c=US
FILTERFILEThe directory channel processes each name by performing a regular expression match on the
pmdf_dirchangroup of rules in the
ldapfilter.conffile 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.conffile, as your changes will be lost when you upgrade or reinstall PMDF. Instead, to use a different file, specify the
FILTERFILEoption with the filename of the desired file. For example, on OpenVMS
or on UNIX
or on NT
ldapfilter.conffile 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 188.8.131.52 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).
directorychannel processes each name by performing a regular expression match on a group of rules found in the file specified by the
FILTERTAGoption is used to specify the group of rules to use. For example:
The default is
pmdf_dirchan. Do not modify the supplied
ldapfilter.conffile, as your changes will be lost when you upgrade or reinstall PMDF. Instead, to use a different file, see the
HINT_TYPEWhen multiple matches to a search are found, the
directorychannel returns choices to the sender. In addition to the distinguished name and e-mail address, the
directorychannel can optionally return one more attribute from the entries to help the sender choose between them. For example,
While any attribute can be specified, some suggestions are title, uid, telephoneNumber, or description.
LDAP_BASE (distinguished name)The
LDAP_BASEspecifies the distinguished name of the location in the
X.500directory information tree from which to base searches. See Section 184.108.40.206.2 for details.
LDAP_SERVERS (domain name or IP address)The
LDAP_SERVERSoption is used to specify the IP address or domain name of the LDAP server to use. See Section 220.127.116.11.1 for details.
MAIL_TYPE (attribute type)When the directory channel searches the
X.500directory for a name, it requests that an e-mail address be returned. The
MAIL_TYPEoption is used to specify the attribute type requested from the directory.
MAIL_TYPEmust 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
pMDFMailAddressto specify a local delivery address. For example:
PASSWORDoption is used to specify a simple authentication credential to be sent with the
DN(that specified by the DN option) when binding to the
LDAPdirectory or X.500 DSA. This can be used to allow the
directorychannel more access to the directory than is allowed for anonymous users. For example:
PASSWORDis specified, a
DNmust also be specified, although a DN may be specified without a
PASSWORDvalue is ignored when using the connectionless protocol over a UDP transport.
SIZELIMIT (integer >= -1)When the
directorychannel 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
SIZELIMIToption controls the maximum number of choices which are returned; e.g.,
The default value for
SIZELIMITis 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
LDAPdirectory or X.500 DSA. Specify a value of
-1to allow any number of matches to be returned; specify a value of
0to 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
0allowed any number of matches to be returned.
TRANSPORT (TCP or UDP)The
TRANSPORToption is used to specify whether to use connection oriented
LDAPprotocol over TCP or connectionless oriented protocol over UDP. For example:
The default is
TRANSPORT=TCP. When running over UDP, the slightly different
CLDAPprotocol is actually used.
CLDAPis 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
SIZELIMIToption, 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
directorychannel returns to the sender a list of the matches.
TRIMaffects the level of detail provided in the returned information. If
TRIMis 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
TRIMvalue 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, USthen the following table shows the results of various
The default value of
TRIM Result 4 Joe User 3 Joe User, Accounting 0 Joe User, Accounting, Example Computing, California, US -1 Joe User -2 Joe User, Accounting
-1so that only the most specific element is returned. A common choice for
TRIMis the number of elements in your
18.104.22.168 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
example.com=2option specifies that LDAP directory or X.500 directory operations are to be done for the example.com pseudo domain. The LDAP server
ldap.example.comis 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
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
22.214.171.124 Default Mailbox Syntax Supported
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 126.96.36.199. Here
are a few examples of syntaxes that are likely to match "Joe
"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
188.8.131.52 LDAP Filter Configuration File, ldapfilter.conf
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
#, 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.,
184.108.40.206.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.
220.127.116.11.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.
printfstyle format string. Everything is taken literally except for the character sequences:
||Substitute with entire search string value|
||Substitute with last word of search string value|
One "match description" match was found for...
Three "match description" matches were found for....
subtree. If search scope is not provided, the default is
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.
18.104.22.168.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
|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"