Aliases in LDAP

From Messaging Server Technical Reference Wiki
Jump to: navigation, search


If at least one of the alias_url0, alias_url1, alias_url2, or alias_url3 MTA options is specified, then for each address matching the local channel (or any channel marked aliaslocal) the MTA will automatically perform the LDAP query specified by the alias_urlN option(s). (If more than one such option is specified, then queries are normally performed in order beginning with alias_url0 and ending with alias_url3; but see the alias_magic MTA option and aliasmagic channel option.)

The LDAP server to query, as well as other basic LDAP query parameters, are controlled by certain MTA options and/or configutil parameters (legacy configuration) or Unified Configuration base options and PAB options; see Table of Basic configuration settings relevant to alias LDAP lookups. The MTA options, if explicitly set, for MTA lookup purposes take precedence over (override) their corresponding configutil parameters (legacy configuration) or base options and PAB options (Unified Configuration).

Note that the MTA's SMTP AUTH user authentication lookups are done using general SASL library code, also used for IMAP, POP, or MSHTTP user logins (authentication). The SASL code does not use the MTA-specific options, but rather uses the configutil parameters or Unified Configuration options.

Basic configuration settings relevant to alias LDAP lookups
msconfig base option configutil parameter MTA option Default Description
ugldaphost local.ugldaphost ldap_host ++ LDAP host to which to connect
ugldapport local.ugldapport ldap_port 389 LDAP port to which to connect
ldapconnecttimeout local.ldapconnecttimeout   10 Time out, in seconds, for LDAP connections
ldapsearchtimeout+ local.ldapsearchtimeout+ ldap_timeout 180000 Time out, in seconds, for LDAP queries
ugldapbinddn local.ugldapbinddn ldap_username   The username with which to bind when doing LDAP queries
ugldapbindcred local.ugldapbindcred ldap_password   The password with which to bind when doing LDAP queries
ugldapusessl local.ugldapusessl   no Whether to use SSL (LDAP-S) to connect to the user/group LDAP directory; also controls use of SSL for LDAP PAB lookups, and "external" LDAP (extldap) lookups. If set to yes, then the MTA will expect to find a certificate located either in the local.ssldbpath directory, if it is specified, or in the MTA's config directory (located as local.instancedir/config, rather than via the usual IMTA_TABLE option value), named local.ssldbprefix.secmod.db. In that directory also must be the password file named sslpassword.conf.
ldaprequiretls     0 (New in 8.0) If SSL is not already being used on a given LDAP connection (e.g., due to ugldapusessl being set or use of an ldaps: URL), then enabling base.ldaprequiretls will require successful negotiation of TLS (using LDAP StartTLS) before proceeding with the connection.
Not used as of 7.0 local.instancedir     Prefix for where Messaging Server is installed. In particular, /config is appended onto this as the location for where to find the certificate (if SSL is being used; that is, if local.ugldapusessl is set).
Deleted in 7.0u4 (never used) service.imta.ldappoolsize   0 The initial number of LDAP connections to start up
    ldap_max_connections 1024 The maximum number of simultaneous LDAP connections to allow using
defaultdomain service.defaultdomain ldap_default_domain   The default domain name
dcroot service.dcroot ldap_domain_root o=internet The base DN for the domain portion of the DIT
ugldapbasedn local.ugldapbasedn ldap_user_root o=isp The LDAP user root, that is, the base DN for the user and group portion of the DIT
  local.imta.schematag ldap_schematag ims50 The tag for the schema in use
    ldap_group_object_classes Varies with the schema tag The object classes required for a group; the default depends upon the schema tag; in particular, for the default schema tag of ims50, the default required object classes are inetLocalMailRecipient+inetmailgroup
    ldap_user_object_classes Varies with the schema tag The object classes required for a user; the default depends upon the schema tag; in particular, for the default schema tag of ims50, the default required object classes are inetLocalMailRecipient+inetmailuser
  local.imta.mailaliases ldap_mail_aliases Varies with schema tag The attributes in which aliases are stored; the default depends upon the schema tag; in particular, for the default schema tag of ims50, the default alias attributes are mail, mailAlternateAddress, and mailEquivalentAddress
hostname local.hostname ldap_local_host   The local host name (official host name for the "l" channel)
  local.imta.hostnamealiases ldap_host_alias_list   Local host aliases
ldappoolrefreshinterval local.ldappoolrefreshinterval   35 Time (minutes) LDAP connections are maintained
ldapcheckcert local.ldapcheckcert   1 Control whether or not to verify the LDAP server's certificate (when SSL is being used, that is, when ugldapusessl is set to 1)
msconfig  PAB option configutil parameter MTA option Default Description
ldaphost local.service.pab.ldaphost ldap_pab_host   (New in 7.0)
ldapbinddn local.service.pab.ldapbinddn ldap_pab_username   (New in Messaging Server 7.0)
ldappasswd local.service.pab.ldappasswd ldap_pab_password   (New in 7.0)
ldapport local.service.pab.ldapport ldap_pab_port ldap_port value (New in 7.0) If neither pab.ldapport nor local.service.pab.ldapport is set, then the ldap_port value is used.
    ldap_pab_max_connections 1024 (New in 7.0u1) Maximum simultaneous connections to the PAB

+The ldapsearchtimeout base option (Unified Configuration) or local.ldapsearchtimeout configutil parameter (legacy configuration) is a global default for all searches done through the LDAP pool API, including those done by the MTA.

++The MTA option ldap_host defaults to the value of the ugldaphost base option, which in turn defaults, if not set, to the loopback interface.


Compare this Table of Basic configuration settings relevant to alias LDAP lookups with Basic configuration settings relevant to domain LDAP lookups.

For the alias_url0, alias_url1, alias_url2, or alias_url3 MTA options, standard LDAP URLs as per RFC 2255 must be used, with the following exception and special interpretations:

  • The LDAP server and port are typically omitted, and are instead specified via MTA options or configutil parameters (legacy configuration) or base options (Unified Configuration), as shown above in Table of Basic LDAP settings relevant to alias lookups. Indeed, prior to Messaging Server 7.0u4, the host and port had to be omitted; as of Messaging Server 7.0u4, specifying the host and port in the URL itself is supported.
  • The MTA makes a distinction between a completely omitted attributes field, which as per RFC 2255 means to request the return of all attributes, and an attributes field consisting of the asterisk character, *, which the MTA instead interprets as meaning to request the return of all known-to-the-MTA attributes, that is, all attributes specified by direct LDAP attribute name MTA options. This distinction is available since for some directory setups, there may be a noticeable performance difference in LDAP directory response to one type of query (all attributes requested) vs. the other type of query (specific, though large, list of attributes requested).
  • Also, certain substitution sequences are available, as shown in Table of LDAP URL substitution sequences.

Thus the LDAP URL value for an alias_urlN option should be specified as


ldap:///dn[?attributes[?scope?filter]]

where the square bracket characters [ and ] shown above indicate optional portions of the URL. The dn is required and is a distinguished name specifying the search base; it might correspond to the organization's top level in the Directory Information Tree. The optional attributes, scope, and filter portions of the URL further refine what information to return. For an alias, the desired attributes to specify returning would typically be the mail attribute (or some similar attribute). The scope may be any of base (the default), one, or sub. And the desired filter would typically be based upon the mailbox (local portion) of the incoming addresses.

Note that the usual LDAP URL encoding rules should be followed; see especially RFC 1738 (Uniform Resource Locators (URL)) and RFC 2255 (LDAP URL Format).

Substitution sequences, as shown in Table of LDAP URL substitution sequences, are available for use in constructing the LDAP URL.

The LDAP URL, before any substitutions, is limited to 256 characters in length (252 characters in iMS 5.2 and earlier); the substitutions may insert additional material and the length after such substitutions is limited to 1024 characters. Note that the substitution of "known" attributes when asterisk, *, is specified as the attribute to return, is not considered as part of the regular substitution; this substitution is performed at a later step and the length after this "known" attributes substitution is limited to 4096 characters.

For instance, at a Messaging Server site using direct LDAP mode, alias_url0 is typically set as follows:


domain_uplevel=2 
alias_url0=ldap:///$V?*?sub?$R 

Here the domain_uplevel=2 setting means that:

  • Since bit 0 (value 1) is not set, domain matches must be exact; (e.g., a domain entry in the DC tree for siroe.com will not imply that host.siroe.com should also be considered a "local" domain).
  • Since bit 2 (value 2) is set, then user alias lookups will be performed looking not only for the exact address presented, but also for that address with the domain name replaced by the "canonical" domain name; for instance, if a domain name is an alias for another domain name (see ldap_domain_attr_alias in Schema 1 mode or ldap_attr_domain2_schema2 in Schema 2 mode), then the user alias lookup will be performed both with the address as originally presented, and with the address with the domain name replaced by the aliased (to) domain name.

The alias_url0 setting means that the result of a previous domainMap lookup will be used as the base for the search (this is the $V substitution), and the MTA will look for its standard set of mail alias attributes (the $R substitution); see the ldap_mail_aliases MTA option.

If a Messaging Server site is using direct LDAP mode with vanity domains enabled, then typical settings are:


domain_uplevel=2 
alias_url0=ldap:///$V?*?sub?$R 
alias_url1=ldap:///$B?*?sub?(&(msgVanityDomain=$D)$R) 
alias_url2=ldap:///$1V?*?sub?(mailAlternateAddress=@$D) 
domain_match_url=ldap:///$B?msgVanityDomain?sub?(msgVanityDomain=$D) 

In addition to the usual settings (see above), notice the additional alias_url1, alias_url2, and domain_match_url settings. Here the domain_match_url setting, used to do an extra lookup when doing domainMap checking, means that the user tree base will be used as the base for the search (the $B substitution), searching for a msgVanityDomain attribute that has the value of the domain name of the address being processed; that is, this is enabling the finding of vanity domain names. The alias_url1 setting means that the user tree base will be used as the base for a search for entries with msgVanityDomain attribute equal to the domain name of the address being processed, and with at least one of the entry's standard mail alias attributes (see the ldap_mail_aliases MTA option) equal to the address being processed. The alias_url2 setting, used if neither the alias_url0 nor alias_url1 searches resulted in a match, is looking for an entry that is the "catch-all" address for the domain or vanity domain of the address being processed.


See also: