Rewrite LDAP query URL substitutions

Rewrite LDAP query URL substitutions, $&#x5d;...&#x5b;, $=, $.text., $..
A substitution of the form     is handled  specially.   is interpreted as an LDAP query URL and the result of the LDAP query is substituted. (If the LDAP query fails, it is as if the rewrite rule never matched in the first  place.)  Standard LDAP URLs as per RFC 2255 are used, with the host and port  typically omitted; the host and port are instead typically specified  via the    and    MTA options. (Indeed, prior to MS 7.0u4 the host and port could not be specified in the URL itself; as of MS 7.0u4  explicitly specifying the host and/or port in the URL is supported.)  That is, the LDAP URL should be specified as  ldap:///dn&#x5b;?attributes&#x5b;?scope?filter&#x5d;&#x5d; or if specifying the LDAP host and LDAP port explicitly ldap://ldap-host:ldap-port/dn&#x5b;?attributes&#x5b;?scope?filter&#x5d;&#x5d; where the square bracket characters   and   shown above indicate optional portions of the  URL. The   is required and is a distinguished name specifying the search base. The optional  ,  , and    portions of the URL further refine what  information to return. For a rewrite rule, the desired   to specify returning might be a    attribute (or some similar attribute). The   may be any of  (the  default), , or. And the desired   might be to request the return of the  object whose   value matches the domain being  rewritten.

For instance, at a site domain.com with an LDAP server running on port 389 of the system ldap.domain.com, a legacy configuration  MTA option file might set LDAP_HOST=ldap.domain.com LDAP_PORT=389 or in Unified Configuration msconfig&#x3e; show mta.ldap_host role.mta.ldap_host = ldap.domain.com msconfig&#x3e; show mta.ldap_port msconfig&#x3e; show -default mta.ldap_port mta.ldap_port: 389 If the LDAP directory schema includes attributes   and , then a  possible rewrite rule to determine to which system to route a given  sort of address might appear as: .domain.com \ $U%$H$D@$&#x5d;ldap:///o=domain.com?mailRoutingSystem?sub?(mailDomain=$D)&#x5b; where here the rewrite substitution sequence  is used to  substitute in the current domain name into the LDAP query constructed;  for ease in reading, the backslash character, , is used  to continue the single logical rewrite rule line onto a second physical  line.

Note that LDAP URLs have special character quoting (encoding) requirements. The  metacharacter forces subsequent material to be  properly quoted (encoded) for LDAP URL usage as shown in  LDAP character encoding rules. Note that the "leave case as-is" substitution,, discussed in  Rewrite case control substitutions can be used to turn off LDAP URL character encoding.

That is, any of the characters $ &+,:;=? will be converted to the percent character, " ", followed by the hexadecimal representation of their location in  US-ASCII; any of the characters &#x2a; will be converted to " " followed by the hexadecimal representation of their location in US-ASCII (the encoded form of the  backslash character followed by the hexadecimal for the particular  character); while the backslash character itself \ will be converted to " ".

The overall length of the LDAP URL (after any substitutions are performed) is limited to 252 characters in iMS 5.2, limited to 256  characters in MS 6.0 through MS 6.2, and limited to 1024  characters as of MS 6.3. Note also that the length of the original template in which such an LDAP URL appears is limited: to 252  characters in iMS 5.2 and earlier, or to 256 characters as of MS  6.0 and later; but substitutions in the template, and in particular  substitutions used to construct the LDAP URL, may increase the LDAP URL  length.

By default, temporary LDAP failures cause the current rewrite rule to fail. This is problematic in cases where different actions need to be taken depending on whether the LDAP lookup failed to find anything versus the directory server being unavailable or misconfigured. As of MS 6.3, the   metacharacter sequence can be used in a  rewrite rule to establish a string which will be processed as the rewrite rule result in the event of a temporary LDAP lookup failure. The temporary failure string is terminated by an unescaped " ". Thus the format is text  in its complete form.

For rewrite rules, (unlike the similar  text  mechanism available in mapping tables where the temporary failure string is "sticky"),  a temporary failure string remains set only for the duration of the current rewrite rule. " " can be used to return to the default  state where no temporary failure string is set and temporary LDAP failures cause  rewrite rule failure.

Note that all errors other than failure to match an entry in the directory are considered to be temporary errors; in general it isn&#x27;t possible to distinguish between errors caused by incorrect LDAP URLs and errors caused by directory server configuration problems.

See also:
 * ldap_host MTA Option
 * ldap_port MTA Option
 * Mapping entry templates
 * Rewrite case control substitutions
 * Rewrite rule template substitutions and control sequences