postfix-master/ldap_table.5.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html> <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   5 <title> Postfix manual - ldap_table(5) </title>
   6 </head> <body> <pre>
   7 LDAP_TABLE(5)                                                    LDAP_TABLE(5)
   8
   9 <b>NAME</b>
  10        ldap_table - Postfix LDAP client configuration
  11
  12 <b>SYNOPSIS</b>
  13        <b>postmap -q "</b><i>string</i><b>" <a href="ldap_table.5.html">ldap</a>:/etc/postfix/filename</b>
  14
  15        <b>postmap -q - <a href="ldap_table.5.html">ldap</a>:/etc/postfix/</b><i>filename</i> &lt;<i>inputfile</i>
  16
  17 <b>DESCRIPTION</b>
  18        The  Postfix  mail system uses optional tables for address
  19        rewriting or mail routing. These tables are usually in <b>dbm</b>
  20        or <b>db</b> format.
  21
  22        Alternatively,  lookup  tables  can  be  specified as LDAP
  23        databases.
  24
  25        In order to use LDAP lookups, define an LDAP source  as  a
  26        lookup table in <a href="postconf.5.html">main.cf</a>, for example:
  27
  28            <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
  29
  30        The  file /etc/postfix/ldap-aliases.cf has the same format
  31        as the Postfix <a href="postconf.5.html">main.cf</a> file, and can specify  the  parame-
  32        ters  described  below.  An example is given at the end of
  33        this manual.
  34
  35        This configuration method is available with  Postfix  ver-
  36        sion  2.1  and later.  See the section "BACKWARDS COMPATI-
  37        BILITY" below for older Postfix versions.
  38
  39        For details about LDAP SSL and STARTTLS, see  the  section
  40        on SSL and STARTTLS below.
  41
  42 <b>BACKWARDS COMPATIBILITY</b>
  43        For  backwards  compatibility with Postfix version 2.0 and
  44        earlier, LDAP parameters can also be defined  in  <a href="postconf.5.html">main.cf</a>.
  45        Specify  as  LDAP  source a name that doesn't begin with a
  46        slash or a dot.  The LDAP parameters will then be accessi-
  47        ble as the name you've given the source in its definition,
  48        an underscore, and the name of the parameter.   For  exam-
  49        ple,  if  the  map  is specified as "<a href="ldap_table.5.html">ldap</a>:<i>ldapsource</i>", the
  50        "server_host" parameter below would be defined in  <a href="postconf.5.html">main.cf</a>
  51        as "<i>ldapsource</i>_server_host".
  52
  53        Note:  with  this form, the passwords for the LDAP sources
  54        are written in <a href="postconf.5.html">main.cf</a>, which is normally  world-readable.
  55        Support  for this form will be removed in a future Postfix
  56        version.
  57
  58        For backwards compatibility with the pre 2.2 LDAP clients,
  59        <b>result_filter</b>  can  for now be used instead of <b>result_for-</b>
  60        <b>mat</b>, when the latter parameter is not also set.   The  new
  61        name  better  reflects the function of the parameter. This
  62        compatibility  interface  may  be  removed  in  a   future
  63        release.
  64
  65 <b>LIST MEMBERSHIP</b>
  66        When  using  LDAP  to  store  lists  such  as $<a href="postconf.5.html#mynetworks">mynetworks</a>,
  67        $<a href="postconf.5.html#mydestination">mydestination</a>,   $<a href="postconf.5.html#relay_domains">relay_domains</a>,   $<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a>,
  68        etc.,  it  is  important to understand that the table must
  69        store each list member as a separate key. The table lookup
  70        verifies  the  *existence*  of the key. See "Postfix lists
  71        versus tables" in the <a href="DATABASE_README.html">DATABASE_README</a> document for a  dis-
  72        cussion.
  73
  74        Do  NOT create tables that return the full list of domains
  75        in $<a href="postconf.5.html#mydestination">mydestination</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP  addresses
  76        in $<a href="postconf.5.html#mynetworks">mynetworks</a>.
  77
  78        DO create tables with each matching item as a key and with
  79        an arbitrary value. With LDAP databases it is not uncommon
  80        to return the key itself.
  81
  82        For  example,  NEVER do this in a map defining $<a href="postconf.5.html#mydestination">mydestina</a>-
  83        <a href="postconf.5.html#mydestination">tion</a>:
  84
  85            query_filter = domain=*
  86            result_attribute = domain
  87
  88        Do this instead:
  89
  90            query_filter = domain=%s
  91            result_attribute = domain
  92
  93 <b>GENERAL LDAP PARAMETERS</b>
  94        In the text below, default values are given  in  parenthe-
  95        ses.  Note: don't use quotes in these variables; at least,
  96        not until the Postfix  configuration  routines  understand
  97        how to deal with quoted strings.
  98
  99        <b>server_host (default: localhost)</b>
 100               The  name of the host running the LDAP server, e.g.
 101
 102                   server_host = ldap.example.com
 103
 104               Depending on the LDAP client library you're  using,
 105               it  should  be possible to specify multiple servers
 106               here, with the library trying them in order  should
 107               the  first  one fail. It should also be possible to
 108               give each server  in  the  list  a  different  port
 109               (overriding <b>server_port</b> below), by naming them like
 110
 111                   server_host = ldap.example.com:1444
 112
 113               With OpenLDAP, a (list of) LDAP URLs can be used to
 114               specify both the hostname(s) and the port(s):
 115
 116                   server_host = <a href="ldap_table.5.html">ldap</a>://ldap.example.com:1444
 117                               <a href="ldap_table.5.html">ldap</a>://ldap2.example.com:1444
 118
 119               All  LDAP URLs accepted by the OpenLDAP library are
 120               supported, including connections over  UNIX  domain
 121               sockets,  and  LDAP SSL (the last one provided that
 122               OpenLDAP was compiled with support for SSL):
 123
 124                   server_host = ldapi://%2Fsome%2Fpath
 125                               ldaps://ldap.example.com:636
 126
 127        <b>server_port (default: 389)</b>
 128               The port the LDAP server listens on, e.g.
 129
 130                   server_port = 778
 131
 132        <b>timeout (default: 10 seconds)</b>
 133               The number of seconds a search can take before tim-
 134               ing out, e.g.
 135
 136                   timeout = 5
 137
 138        <b>search_base (No default; you must configure this)</b>
 139               The <a href="http://tools.ietf.org/html/rfc2253">RFC2253</a> base DN at which to conduct the search,
 140               e.g.
 141
 142                   search_base = dc=your, dc=com
 143
 144               With Postfix 2.2 and later this parameter  supports
 145               the following '%' expansions:
 146
 147               <b>%%</b>     This is replaced by a literal '%' character.
 148
 149               <b>%s</b>     This is replaced by the input key.  <a href="http://tools.ietf.org/html/rfc2253">RFC 2253</a>
 150                      quoting  is used to make sure that the input
 151                      key does not add unexpected  metacharacters.
 152
 153               <b>%u</b>     When the input key is an address of the form
 154                      user@domain, <b>%u</b>  is  replaced  by  the  (<a href="http://tools.ietf.org/html/rfc2253">RFC</a>
 155                      <a href="http://tools.ietf.org/html/rfc2253">2253</a>)  quoted  local  part  of  the address.
 156                      Otherwise, <b>%u</b>  is  replaced  by  the  entire
 157                      search  string.   If the localpart is empty,
 158                      the search  is  suppressed  and  returns  no
 159                      results.
 160
 161               <b>%d</b>     When the input key is an address of the form
 162                      user@domain, <b>%d</b>  is  replaced  by  the  (<a href="http://tools.ietf.org/html/rfc2253">RFC</a>
 163                      <a href="http://tools.ietf.org/html/rfc2253">2253</a>)  quoted  domain  part  of the address.
 164                      Otherwise,  the  search  is  suppressed  and
 165                      returns no results.
 166
 167               <b>%[SUD]</b> For  the  <b>search_base</b>  parameter, the upper-
 168                      case equivalents  of  the  above  expansions
 169                      behave   identically   to  their  lower-case
 170                      counter-parts. With the <b>result_format</b> param-
 171                      eter  (previously  called  <b>result_filter</b> see
 172                      the COMPATIBILITY section and  below),  they
 173                      expand  to  the  corresponding components of
 174                      input key rather than the result value.
 175
 176               <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced  by
 177                      the corresponding most significant component
 178                      of the input key's domain. If the input  key
 179                      is <i>user@mail.example.com</i>, then %1 is <b>com</b>, %2
 180                      is <b>example</b> and %3 is <b>mail</b>. If the input  key
 181                      is  unqualified  or  does  not  have  enough
 182                      domain components to satisfy all the  speci-
 183                      fied  patterns, the search is suppressed and
 184                      returns no results.
 185
 186        <b>query_filter (default: mailacceptinggeneralid=%s)</b>
 187               The <a href="http://tools.ietf.org/html/rfc2254">RFC2254</a> filter used to  search  the  directory,
 188               where <b>%s</b> is a substitute for the address Postfix is
 189               trying to resolve, e.g.
 190
 191                   query_filter = (&amp;(mail=%s)(paid_up=true))
 192
 193               This parameter supports the  following  '%'  expan-
 194               sions:
 195
 196               <b>%%</b>     This is replaced by a literal '%' character.
 197                      (Postfix 2.2 and later).
 198
 199               <b>%s</b>     This is replaced by the input key.  <a href="http://tools.ietf.org/html/rfc2254">RFC 2254</a>
 200                      quoting  is used to make sure that the input
 201                      key does not add unexpected  metacharacters.
 202
 203               <b>%u</b>     When the input key is an address of the form
 204                      user@domain, <b>%u</b>  is  replaced  by  the  (<a href="http://tools.ietf.org/html/rfc2254">RFC</a>
 205                      <a href="http://tools.ietf.org/html/rfc2254">2254</a>)  quoted  local  part  of  the address.
 206                      Otherwise, <b>%u</b>  is  replaced  by  the  entire
 207                      search  string.   If the localpart is empty,
 208                      the search  is  suppressed  and  returns  no
 209                      results.
 210
 211               <b>%d</b>     When the input key is an address of the form
 212                      user@domain, <b>%d</b>  is  replaced  by  the  (<a href="http://tools.ietf.org/html/rfc2254">RFC</a>
 213                      <a href="http://tools.ietf.org/html/rfc2254">2254</a>)  quoted  domain  part  of the address.
 214                      Otherwise,  the  search  is  suppressed  and
 215                      returns no results.
 216
 217               <b>%[SUD]</b> The  upper-case  equivalents  of  the  above
 218                      expansions behave in the <b>query_filter</b> param-
 219                      eter   identically   to   their   lower-case
 220                      counter-parts. With the <b>result_format</b> param-
 221                      eter  (previously  called  <b>result_filter</b> see
 222                      the COMPATIBILITY section and  below),  they
 223                      expand  to  the  corresponding components of
 224                      input key rather than the result value.
 225
 226                      The above  %S,  %U  and  %D  expansions  are
 227                      available with Postfix 2.2 and later.
 228
 229               <b>%[1-9]</b> The  patterns %1, %2, ... %9 are replaced by
 230                      the corresponding most significant component
 231                      of  the input key's domain. If the input key
 232                      is <i>user@mail.example.com</i>, then %1 is <b>com</b>, %2
 233                      is  <b>example</b> and %3 is <b>mail</b>. If the input key
 234                      is  unqualified  or  does  not  have  enough
 235                      domain  components to satisfy all the speci-
 236                      fied patterns, the search is suppressed  and
 237                      returns no results.
 238
 239                      The  above %1, ..., %9 expansions are avail-
 240                      able with Postfix 2.2 and later.
 241
 242               The "domain" parameter described below  limits  the
 243               input  keys  to addresses in matching domains. When
 244               the "domain" parameter is non-empty,  LDAP  queries
 245               for  unqualified  addresses  or  addresses  in non-
 246               matching  domains  are  suppressed  and  return  no
 247               results.
 248
 249               NOTE:  DO  NOT  put  quotes around the <b>query_filter</b>
 250               parameter.
 251
 252        <b>result_format (default: %s</b>)
 253               Called <b>result_filter</b> in Postfix releases  prior  to
 254               2.2.  Format template applied to result attributes.
 255               Most commonly used to append (or prepend)  text  to
 256               the  result.  This parameter supports the following
 257               '%' expansions:
 258
 259               <b>%%</b>     This is replaced by a literal '%' character.
 260                      (Postfix 2.2 and later).
 261
 262               <b>%s</b>     This  is replaced by the value of the result
 263                      attribute.  When  result  is  empty  it   is
 264                      skipped.
 265
 266               <b>%u</b>     When   the  result  attribute  value  is  an
 267                      address  of  the  form  user@domain,  <b>%u</b>  is
 268                      replaced  by  the local part of the address.
 269                      When the result has an empty localpart it is
 270                      skipped.
 271
 272               <b>%d</b>     When  a result attribute value is an address
 273                      of the form user@domain, <b>%d</b> is  replaced  by
 274                      the domain part of the attribute value. When
 275                      the result is unqualified it is skipped.
 276
 277               <b>%[SUD1-9]</b>
 278                      The upper-case and decimal digit  expansions
 279                      interpolate  the  parts  of  the  input  key
 280                      rather than the result.  Their  behavior  is
 281                      identical  to that described with <b>query_fil-</b>
 282                      <b>ter</b>, and in fact because the  input  key  is
 283                      known in advance, lookups whose key does not
 284                      contain all the information specified in the
 285                      result template are suppressed and return no
 286                      results.
 287
 288                      The above %S, %U, %D and %1, ..., %9  expan-
 289                      sions  are  available  with  Postfix 2.2 and
 290                      later.
 291
 292               For  example,  using  "result_format  =  <a href="smtp.8.html">smtp</a>:[%s]"
 293               allows one to use a mailHost attribute as the basis
 294               of a <a href="transport.5.html">transport(5)</a> table. After applying the  result
 295               format,  multiple  values are concatenated as comma
 296               separated   strings.   The   expansion_limit    and
 297               size_limit  parameters explained below allow one to
 298               restrict the number of values in the result,  which
 299               is  especially useful for maps that should return a
 300               single value.
 301
 302               The default value <b>%s</b> specifies that each  attribute
 303               value should be used as is.
 304
 305               This  parameter was called <b>result_filter</b> in Postfix
 306               releases prior to 2.2.  If  no  "result_format"  is
 307               specified,  the  value  of  "result_filter" will be
 308               used instead before resorting to the default value.
 309               This  provides compatibility with old configuration
 310               files.
 311
 312               NOTE: DO NOT put quotes around the result format!
 313
 314        <b>domain (default: no domain list)</b>
 315               This is a list of domain names, paths to files,  or
 316               dictionaries.  When specified, only fully qualified
 317               search keys with  a  *non-empty*  localpart  and  a
 318               matching  domain  are  eligible  for lookup: 'user'
 319               lookups, bare domain lookups and "@domain"  lookups
 320               are  not  performed.  This can significantly reduce
 321               the query load on the LDAP server.
 322
 323                   domain = postfix.org, hash:/etc/postfix/searchdomains
 324
 325               It is best not to use LDAP  to  store  the  domains
 326               eligible for LDAP lookups.
 327
 328               NOTE:  DO  NOT  define  this parameter for <a href="local.8.html">local(8)</a>
 329               aliases.
 330
 331               This feature is available in Postfix 1.0 and later.
 332
 333        <b>result_attribute (default: maildrop)</b>
 334               The  attribute(s) Postfix will read from any direc-
 335               tory entries returned by the lookup, to be resolved
 336               to an email address.
 337
 338                   result_attribute = mailbox, maildrop
 339
 340               Don't  rely  on the default value ("maildrop"). Set
 341               the result_attribute explicitly in all  ldap  table
 342               configuration  files. This is particularly relevant
 343               when no result_attribute is applicable, e.g.  cases
 344               in   which   leaf_result_attribute   and/or  termi-
 345               nal_result_attribute are used instead. The  default
 346               value is harmless if "maildrop" is also listed as a
 347               leaf or terminal result attribute, but it  is  best
 348               to not leave this to chance.
 349
 350        <b>special_result_attribute (default: empty)</b>
 351               The attribute(s) of directory entries that can con-
 352               tain DNs or <a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a> LDAP URLs. If found, a  recur-
 353               sive search is performed to retrieve the entry ref-
 354               erenced by the DN, or the entries  matched  by  the
 355               URL query.
 356
 357                   special_result_attribute = memberdn
 358
 359               DN  recursion  retrieves the same result_attributes
 360               as the main query, including the special attributes
 361               for further recursion.
 362
 363               URL processing retrieves only those attributes that
 364               are included in both  the  URL  definition  and  as
 365               result  attributes (ordinary, special, leaf or ter-
 366               minal) in the Postfix table definition.  If the URL
 367               lists any of the table's special result attributes,
 368               these are retrieved and  used  recursively.  A  URL
 369               that  does  not specify any attribute selection, is
 370               equivalent (<a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a>) to a  URL  that  selects  all
 371               attributes,  in  which case the selected attributes
 372               will be the full set of result  attributes  in  the
 373               Postfix table.
 374
 375               If  an  LDAP URL attribute-descriptor or the corre-
 376               sponding Postfix LDAP table result  attribute  (but
 377               not   both)   uses   <a href="http://tools.ietf.org/html/rfc2255">RFC   2255</a>   sub-type  options
 378               ("attr;option"), the attribute requested  from  the
 379               LDAP  server  will  include the sub-type option. In
 380               all other cases, the URL attribute  and  the  table
 381               attribute   must  match  exactly.  Attributes  with
 382               options in both the URL and the Postfix  table  are
 383               requested only when the options are identical. LDAP
 384               attribute-descriptor options are very rarely  used,
 385               most LDAP users will not need to concern themselves
 386               with this level of nuanced detail.
 387
 388        <b>terminal_result_attribute (default: empty)</b>
 389               When one or more  terminal  result  attributes  are
 390               found in an LDAP entry, all other result attributes
 391               are ignored and only the terminal result attributes
 392               are  returned. This is useful for delegating expan-
 393               sion of group members  to  a  particular  host,  by
 394               using  an optional "maildrop" attribute on selected
 395               groups to route the group to a specific host, where
 396               the  group  is  expanded, possibly via mailing-list
 397               manager or other special processing.
 398
 399                   result_attribute =
 400                   terminal_result_attribute = maildrop
 401
 402               When using terminal and/or leaf result  attributes,
 403               the  result_attribute is best set to an empty value
 404               when it is not used, or else explicitly set to  the
 405               desired  value,  even  if  it  is the default value
 406               "maildrop".
 407
 408               This feature  is  available  with  Postfix  2.4  or
 409               later.
 410
 411        <b>leaf_result_attribute (default: empty)</b>
 412               When  one  or  more  special  result attributes are
 413               found in a non-terminal  (see  above)  LDAP  entry,
 414               leaf result attributes are excluded from the expan-
 415               sion of that entry. This is useful  when  expanding
 416               groups and the desired mail address attribute(s) of
 417               the member objects obtained via DN or URI recursion
 418               are  also  present  in  the  group  object. To only
 419               return the attribute values from the  leaf  objects
 420               and  not the containing group, add the attribute to
 421               the  leaf_result_attribute  list,   and   not   the
 422               result_attribute  list,  which  is always expanded.
 423               Note, the default value  of  "result_attribute"  is
 424               not  empty, you may want to set it explicitly empty
 425               when using "leaf_result_attribute"  to  expand  the
 426               group  to  a list of member DN addresses. If groups
 427               have both member DN references AND attributes  that
 428               hold  multiple string valued rfc822 addresses, then
 429               the string  attributes  go  in  "result_attribute".
 430               The  attributes  that represent the email addresses
 431               of objects referenced via a DN (or LDAP URI) go  in
 432               "leaf_result_attribute".
 433
 434                   result_attribute = memberaddr
 435                   special_result_attribute = memberdn
 436                   terminal_result_attribute = maildrop
 437                   leaf_result_attribute = mail
 438
 439               When  using terminal and/or leaf result attributes,
 440               the result_attribute is best set to an empty  value
 441               when  it is not used, or else explicitly set to the
 442               desired value, even if  it  is  the  default  value
 443               "maildrop".
 444
 445               This  feature  is  available  with  Postfix  2.4 or
 446               later.
 447
 448        <b>scope (default: sub)</b>
 449               The LDAP search scope: <b>sub</b>, <b>base</b>,  or  <b>one</b>.   These
 450               translate into LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE,
 451               and LDAP_SCOPE_ONELEVEL.
 452
 453        <b>bind (default: yes)</b>
 454               Whether or how to bind to the  LDAP  server.  Newer
 455               LDAP implementations don't require clients to bind,
 456               which saves time. Example:
 457
 458                   # Don't bind
 459                   bind = no
 460                   # Use SIMPLE bind
 461                   bind = yes
 462                   # Use SASL bind
 463                   bind = sasl
 464
 465               Postfix versions prior to 2.8 only support "bind  =
 466               no"  which means don't bind, and "bind = yes" which
 467               means do a SIMPLE bind.  Postfix 2.8 and later also
 468               supports "bind = SASL" when compiled with LDAP SASL
 469               support as described in <a href="LDAP_README.html">LDAP_README</a>, it  also  adds
 470               the  synonyms "bind = none" and "bind = simple" for
 471               "bind = no" and "bind = yes" respectively. See  the
 472               SASL section below for additional parameters avail-
 473               able with "bind = sasl".
 474
 475               If you do need to bind, you might consider  config-
 476               uring  Postfix to connect to the local machine on a
 477               port that's an SSL tunnel to your LDAP  server.  If
 478               your  LDAP server doesn't natively support SSL, put
 479               a tunnel (wrapper, proxy, whatever you want to call
 480               it)  on  that  system  too. This should prevent the
 481               password from traversing the network in the  clear.
 482
 483        <b>bind_dn (default: empty)</b>
 484               If  you  do  have  to bind, do it with this distin-
 485               guished name. Example:
 486
 487                   bind_dn = uid=postfix, dc=your, dc=com
 488               With "bind =  sasl"  (see  above)  the  DN  may  be
 489               optional  for some SASL mechanisms, don't specify a
 490               DN if not needed.
 491
 492        <b>bind_pw (default: empty)</b>
 493               The password for the distinguished name  above.  If
 494               you have to use this, you probably want to make the
 495               map configuration file readable only by the Postfix
 496               user.  When using the obsolete <a href="ldap_table.5.html">ldap</a>:ldapsource syn-
 497               tax, with map parameters in <a href="postconf.5.html">main.cf</a>, it is not pos-
 498               sible  to securely store the bind password. This is
 499               because <a href="postconf.5.html">main.cf</a> needs to be world readable to allow
 500               local accounts to submit mail via the sendmail com-
 501               mand. Example:
 502
 503                   bind_pw = postfixpw
 504               With "bind = sasl" (see above) the password may  be
 505               optional  for some SASL mechanisms, don't specify a
 506               password if not needed.
 507
 508        <b>cache (IGNORED with a warning)</b>
 509
 510        <b>cache_expiry (IGNORED with a warning)</b>
 511
 512        <b>cache_size (IGNORED with a warning)</b>
 513               The above parameters are  NO  LONGER  SUPPORTED  by
 514               Postfix.   Cache  support  has  been  dropped  from
 515               OpenLDAP as of release 2.1.13.
 516
 517        <b>recursion_limit (default: 1000)</b>
 518               A limit on the nesting depth of DN and URL  special
 519               result  attribute  evaluation.  The limit must be a
 520               non-zero positive number.
 521
 522        <b>expansion_limit (default: 0)</b>
 523               A limit on the  total  number  of  result  elements
 524               returned  (as  a  comma separated list) by a lookup
 525               against the map.  A setting of  zero  disables  the
 526               limit.  Lookups  fail with a temporary error if the
 527               limit is exceeded.  Setting the limit to 1  ensures
 528               that lookups do not return multiple values.
 529
 530        <b>size_limit (default: $expansion_limit)</b>
 531               A  limit  on the number of LDAP entries returned by
 532               any single LDAP search performed  as  part  of  the
 533               lookup.  A setting of 0 disables the limit.  Expan-
 534               sion of DN and URL references involves nested  LDAP
 535               queries,  each  of which is separately subjected to
 536               this limit.
 537
 538               Note: even a single LDAP entry can generate  multi-
 539               ple  lookup results, via multiple result attributes
 540               and/or multi-valued result attributes.  This  limit
 541               caps  the  per  search  resource utilization on the
 542               LDAP server, not  the  final  multiplicity  of  the
 543               lookup  result.  It is analogous to the "-z" option
 544               of "ldapsearch".
 545
 546        <b>dereference (default: 0)</b>
 547               When to dereference LDAP aliases. (Note  that  this
 548               has nothing do with Postfix aliases.) The permitted
 549               values are those legal  for  the  OpenLDAP/UM  LDAP
 550               implementations:
 551
 552               0      never
 553
 554               1      when searching
 555
 556               2      when locating the base object for the search
 557
 558               3      always
 559
 560               See ldap.h or the ldap_open(3) or ldapsearch(1) man
 561               pages  for more information. And if you're using an
 562               LDAP package that has other possible values, please
 563               bring   it   to   the  attention  of  the  postfix-
 564               users@postfix.org mailing list.
 565
 566        <b>chase_referrals (default: 0)</b>
 567               Sets (or clears) LDAP_OPT_REFERRALS (requires  LDAP
 568               version 3 support).
 569
 570        <b>version (default: 2)</b>
 571               Specifies the LDAP protocol version to use.
 572
 573        <b>debuglevel (default: 0)</b>
 574               What  level  to  set  for debugging in the OpenLDAP
 575               libraries.
 576
 577 <b>LDAP SASL PARAMETERS</b>
 578        If you're using the OpenLDAP libraries compiled with  SASL
 579        support,  Postfix  2.8 and later built with LDAP SASL sup-
 580        port as described in <a href="LDAP_README.html">LDAP_README</a> can authenticate to  LDAP
 581        servers via SASL.
 582
 583        This  enables authentication to the LDAP server via mecha-
 584        nisms other than a simple password. The added  flexibility
 585        has  a  cost: it is no longer practical to set an explicit
 586        timeout on the duration of an LDAP bind  operation.  Under
 587        adverse  conditions,  whether a SASL bind times out, or if
 588        it does, the duration of the timeout is determined by  the
 589        LDAP and SASL libraries.
 590
 591        It  is  best  to  use tables that use SASL binds via <a href="proxymap.8.html">prox-</a>
 592        <a href="proxymap.8.html">ymap(8)</a>, this way the requesting process can time-out  the
 593        proxymap  request.  This  also lets you tailer the process
 594        environment by overriding the <a href="proxymap.8.html">proxymap(8)</a>  import_environ-
 595        ment setting in <a href="master.5.html">master.cf</a>(5). Special environment settings
 596        may be needed to configure  GSSAPI  credential  caches  or
 597        other  SASL mechanism specific options. The GSSAPI creden-
 598        tials used for LDAP lookups may need to be different  than
 599        say those used for the Postfix SMTP client to authenticate
 600        to remote servers.
 601
 602        Using SASL mechanisms requires LDAP  protocol  version  3,
 603        the  default  protocol version is 2 for backwards compati-
 604        bility. You must set "version = 3" in addition to "bind  =
 605        sasl".
 606
 607        The  following  parameters are relevant to using LDAP with
 608        SASL
 609
 610        <b>sasl_mechs (default: empty)</b>
 611               Space separated list of SASL mechanism(s) to try.
 612
 613        <b>sasl_realm (default: empty)</b>
 614               SASL Realm to use, if applicable.
 615
 616        <b>sasl_authz_id (default: empty)</b>
 617               The  SASL  authorization  identity  to  assert,  if
 618               applicable.
 619
 620        <b>sasl_minssf (default: 0)</b>
 621               The  minimum required sasl security factor required
 622               to establish a connection.
 623
 624 <b>LDAP SSL AND STARTTLS PARAMETERS</b>
 625        If you're using the OpenLDAP libraries compiled  with  SSL
 626        support,  Postfix  can connect to LDAP SSL servers and can
 627        issue the STARTTLS command.
 628
 629        LDAP SSL service can be requested by using a LDAP SSL  URL
 630        in the server_host parameter:
 631
 632            server_host = ldaps://ldap.example.com:636
 633
 634        STARTTLS can be turned on with the start_tls parameter:
 635
 636            start_tls = yes
 637
 638        Both  forms  require LDAP protocol version 3, which has to
 639        be set explicitly with:
 640
 641            version = 3
 642
 643        If any of the Postfix programs querying the map is config-
 644        ured  in  <a href="master.5.html">master.cf</a>  to run chrooted, all the certificates
 645        and keys involved have to be copied to the chroot jail. Of
 646        course,  the  private  keys should only be readable by the
 647        user "postfix".
 648
 649        The following parameters are  relevant  to  LDAP  SSL  and
 650        STARTTLS:
 651
 652        <b>start_tls (default: no)</b>
 653               Whether or not to issue STARTTLS upon connection to
 654               the server.  Don't set this with LDAP SSL (the  SSL
 655               session is setup automatically when the TCP connec-
 656               tion is opened).
 657
 658        <b>tls_ca_cert_dir  (No   default;   set   either   this   or</b>
 659        <b>tls_ca_cert_file)</b>
 660               Directory  containing  X509  Certificate  Authority
 661               certificates  in  PEM format which are to be recog-
 662               nized by the client  in  SSL/TLS  connections.  The
 663               files  each  contain one CA certificate.  The files
 664               are looked up by the CA subject  name  hash  value,
 665               which  must hence be available. If more than one CA
 666               certificate with the same name  hash  value  exist,
 667               the  extension  must be different (e.g. 9d66eef0.0,
 668               9d66eef0.1 etc). The search  is  performed  in  the
 669               ordering  of  the  extension  number, regardless of
 670               other  properties  of  the  certificates.  Use  the
 671               c_rehash utility (from the OpenSSL distribution) to
 672               create the necessary links.
 673
 674        <b>tls_ca_cert_file  (No  default;   set   either   this   or</b>
 675        <b>tls_ca_cert_dir)</b>
 676               File containing the X509 Certificate Authority cer-
 677               tificates  in PEM format which are to be recognized
 678               by the client in SSL/TLS connections. This  setting
 679               takes precedence over tls_ca_cert_dir.
 680
 681        <b>tls_cert (No default; you must set this)</b>
 682               File  containing  client's  X509  certificate to be
 683               used by the client in SSL/ TLS connections.
 684
 685        <b>tls_key (No default; you must set this)</b>
 686               File containing the private  key  corresponding  to
 687               the above tls_cert.
 688
 689        <b>tls_require_cert (default: no)</b>
 690               Whether or not to request server's X509 certificate
 691               and check its validity  when  establishing  SSL/TLS
 692               connections.   The supported values are <b>no</b> and <b>yes</b>.
 693
 694               With <b>no</b>, the server certificate trust chain is  not
 695               checked,  but  with  OpenLDAP  prior to 2.1.13, the
 696               name in the server certificate must still match the
 697               LDAP server name. With OpenLDAP 2.0.0 to 2.0.11 the
 698               server name is not necessarily what you  specified,
 699               rather  it  is  determined (by reverse lookup) from
 700               the IP address of the LDAP server connection.  With
 701               OpenLDAP  prior  to  2.0.13, subjectAlternativeName
 702               extensions  in  the  LDAP  server  certificate  are
 703               ignored:  the  server  name  must match the subject
 704               CommonName. The <b>no</b> setting corresponds to the <b>never</b>
 705               value  of  <b>TLS_REQCERT</b> in LDAP client configuration
 706               files.
 707
 708               Don't use TLS with OpenLDAP 2.0.x  (and  especially
 709               with x &lt;= 11) if you can avoid it.
 710
 711               With  <b>yes</b>, the server certificate must be issued by
 712               a trusted CA, and not be expired. The  LDAP  server
 713               name  must  match  one  of the name(s) found in the
 714               certificate (see above for OpenLDAP library version
 715               dependent behavior). The <b>yes</b> setting corresponds to
 716               the <b>demand</b> value of <b>TLS_REQCERT</b> in LDAP client con-
 717               figuration files.
 718
 719               The "try" and "never" values of <b>TLS_REQCERT</b> have no
 720               equivalents  here.  They  are  not  available  with
 721               OpenLDAP  2.0,  and  in  any case have questionable
 722               security properties. Either you want  TLS  verified
 723               LDAP connections, or you don't.
 724
 725               The <b>yes</b> value only works correctly with Postfix 2.5
 726               and later, or with OpenLDAP  2.0.  Earlier  Postfix
 727               releases  or  later  OpenLDAP  releases  don't work
 728               together with this setting. Support for  LDAP  over
 729               TLS  was added to Postfix based on the OpenLDAP 2.0
 730               API.
 731
 732        <b>tls_random_file (No default)</b>
 733               Path of a file to  obtain  random  bits  from  when
 734               /dev/[u]random  is not available, to be used by the
 735               client in SSL/TLS connections.
 736
 737        <b>tls_cipher_suite (No default)</b>
 738               Cipher suite to use in SSL/TLS negotiations.
 739
 740 <b>EXAMPLE</b>
 741        Here's a basic example for using LDAP to look up  <a href="local.8.html">local(8)</a>
 742        aliases.  Assume that in <a href="postconf.5.html">main.cf</a>, you have:
 743
 744            <a href="postconf.5.html#alias_maps">alias_maps</a> = hash:/etc/aliases,
 745                    <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
 746
 747        and in <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf you have:
 748
 749            server_host = ldap.example.com
 750            search_base = dc=example, dc=com
 751
 752        Upon  receiving  mail  for a local address "ldapuser" that
 753        isn't found in the  /etc/aliases  database,  Postfix  will
 754        search the LDAP server listening at port 389 on ldap.exam-
 755        ple.com.  It will bind anonymously, search for any  direc-
 756        tory  entries  whose  mailacceptinggeneralid  attribute is
 757        "ldapuser", read the "maildrop" attributes of those found,
 758        and build a list of their maildrops, which will be treated
 759        as <a href="http://tools.ietf.org/html/rfc822">RFC822</a> addresses to which the message  will  be  deliv-
 760        ered.
 761
 762 <b>SEE ALSO</b>
 763        <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
 764        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 765        <a href="mysql_table.5.html">mysql_table(5)</a>, MySQL lookup tables
 766        <a href="pgsql_table.5.html">pgsql_table(5)</a>, PostgreSQL lookup tables
 767
 768 <b>README FILES</b>
 769        <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
 770        <a href="LDAP_README.html">LDAP_README</a>, Postfix LDAP client guide
 771
 772 <b>LICENSE</b>
 773        The Secure Mailer license must be  distributed  with  this
 774        software.
 775
 776 <b>AUTHOR(S)</b>
 777        Carsten  Hoeger,  Hery  Rakotoarisoa,  John Hensley, Keith
 778        Stevenson, LaMont Jones, Liviu Daia, Manuel Guesdon,  Mike
 779        Mattice,  Prabhat K Singh, Sami Haahtinen, Samuel Tardieu,
 780        Victor Duchovni, and many others.
 781
 782                                                                  LDAP_TABLE(5)
 783 </pre> </body> </html>