Domain LDAP lookup rewrites

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

Domain LDAP lookup rewrites, $V, $Z

The $V and $Z flags interpret the material following (up to the first @ or % character, or $C, $M, $N, $Q, or $T) as a domain name to look up in the LDAP directory; (in Schema 1, this would be a lookup in the DC tree within the directory; in Schema 2, domains are stored as part of the Organization tree so it is a lookup in the Organization tree). $V means succeed if the LDAP lookup of the domain succeeds (i.e., the domain is found, as a local/hosted/vanity domain). $Z means succeed if the LDAP lookup of the domain fails (i.e., the domain is not a local/hosted/vanity domain).

Note that the imsimta test -domain_map utility, and in particular its ENUMERATE command, can be used to probe/check/list domain definitions stored in LDAP.

For instance, a typical Oracle Messaging Server MTA configuration will include a rewrite rule:

$*    $A$E$F$U%$H$V$H@local-channel-official-hostname

where local-channel-official-hostname corresponds to the value of channel:l.official_host_name. Note that this fundamental rewrite rule of Direct LDAP configuration makes use of the Initial match-all rule, $*, so that it is the very first rewrite rule checked for any domain name appearing to the right of the @ sign ($A control sequence) in an envelope To address ($E and $F control sequences).

Note that in Unified Configuration, this same rewrite rule would typically be expressed using the &/IMTA_HOST/ substitution, so appear as:

msconfig> show rewrite * "$*"
role.rewrite.rule = $* $A$E$F$U%$H$V$H@&/IMTA_HOST/

The LDAP server to query, as well as other basic LDAP query parameters relevant in domainMap lookups, are controlled by certain MTA options and/or (in legacy configuration) configutil parameters; see Basic configuration settings relevant to domain LDAP lookups. The MTA options, if explicitly set, take precedence over (override) their corresponding configutil parameters.

Basic configuration settings relevant to domain 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
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
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.
    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
  local.imta.schematag ldap_schematag ims50 The tag for the schema in use
ldap_domain_​filter_schema1   ldap_domain_​filter_schema1 (|(objectclass=​inetDomain)(objectclass=​inetdomainalias)) Specifies the filter for domains when schema 1 is in use
ldap_domain_​filter_schema2   ldap_domain_​filter_schema2   Specifies the filter for domains when schema 2 is in use
ldap_domain_​known_attributes   ldap_domain_​known_attributes -1 This option controls whether the MTA requests the return of all domain attributes, or (the default) requests the return of only "known" domain attributes, specifically the per-domain attributes listed in Table of MTA LDAP attribute name options
    domain_match_url   Specify an additional LDAP query URL to attempt if a domain name cannot be found as a "real" domain; for instance, this option would be set to ldap:///$B?msgVanityDomain?sub?(msgVanityDomain=$D) if one wishes to support vanity domains
    domain_uplevel 0 This option affects how domain names are searched for and used; in particular, it controls whether the MTA iteratively looks "up" for a domain when a subdomain cannot be found
    domain_failure reprocess-daemon$Mtcp_local$1M$1~-error$4000000?Temporary lookup failure What rewrite template to use if a $V or $Z rewrite rule lookup encounters an LDAP error, such as an LDAP connection error
ldap_domain_timeout   ldap_domain_​timeout 900 Time (in seconds) to retain cached results of domain lookups (in the domain map library code cache)
    domain_match_​cache_size 100000 Number of domain lookup results to cache (in the MTA's cache)
    domain_match_​cache_timeout 600 Time (in seconds) to retain (in the MTA's cache) cached results of domain lookups

+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 Basic configuration settings relevant to domain LDAP lookups with Table of Basic configuration settings relevant to alias LDAP lookups.

The domain_match_url and domain_uplevel MTA options further affect domain lookups, with domain_match_url potentially specifying an additional lookup to look for vanity domains (which are not real domains), and with domain_uplevel controlling things such as whether if a subdomain is not found, the MTA then looks instead for the domain "over" the subdomain.

If a $V or $Z lookup attempt encounters an LDAP error condition (such as the LDAP directory being temporarily inaccessible), then the MTA option domain_failure specifies what the MTA will take to be the rewriting process result. The default value for domain_failure means that LDAP error conditions will result in messages being diverted to the reprocess channel for additional subsequent rewriting and lookup attempts.

The results of a domain name lookup due to a $V and $Z flag will be cached; that is, the MTA caches not only whether the domain name lookup was successful, but also (in the case of a successful lookup) any attribute values successfully returned. In its queries, the MTA can request that successful lookups return either all attributes for the domain, or instead request an explicit list of "known to the MTA attributes" (see the per-domain attributes in Table of MTA LDAP attribute name options); note that for some directory setups, there may be an LDAP directory performance difference between requesting all attributes or requesting an explicit (even large explicit) list of attributes. Whether domain name lookup requests are for all attributes, or a list of known attributes, is controlled by the ldap_domain_known_attributes MTA option; the default is to request the return of all domain attributes. For control of domain name lookup result caching at the MTA-level, see the domain_match_cache_size and domain_match_cache_timeout MTA options; note that the underlying domain Map code also does its own caching, with timeout (when called by the MTA) controlled by the ldap_domain_timeout MTA option.

See also: