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 (default: no)</b>
 611               Whether or not to use SASL  binds  to  the  server.
 612               Can be yes or no.
 613
 614        <b>sasl_mechs (default: empty)</b>
 615               Space separated list of SASL mechanism(s) to try.
 616
 617        <b>sasl_realm (default: empty)</b>
 618               SASL Realm to use, if applicable.
 619
 620        <b>sasl_authz_id (default: empty)</b>
 621               The  SASL  authorization  identity  to  assert,  if
 622               applicable.
 623
 624        <b>sasl_minssf (default: 0)</b>
 625               The minimum required sasl security factor  required
 626               to establish a connection.
 627
 628 <b>LDAP SSL AND STARTTLS PARAMETERS</b>
 629        If  you're  using the OpenLDAP libraries compiled with SSL
 630        support, Postfix can connect to LDAP SSL servers  and  can
 631        issue the STARTTLS command.
 632
 633        LDAP  SSL service can be requested by using a LDAP SSL URL
 634        in the server_host parameter:
 635
 636            server_host = ldaps://ldap.example.com:636
 637
 638        STARTTLS can be turned on with the start_tls parameter:
 639
 640            start_tls = yes
 641
 642        Both forms require LDAP protocol version 3, which  has  to
 643        be set explicitly with:
 644
 645            version = 3
 646
 647        If any of the Postfix programs querying the map is config-
 648        ured in <a href="master.5.html">master.cf</a> to run chrooted,  all  the  certificates
 649        and keys involved have to be copied to the chroot jail. Of
 650        course, the private keys should only be  readable  by  the
 651        user "postfix".
 652
 653        The  following  parameters  are  relevant  to LDAP SSL and
 654        STARTTLS:
 655
 656        <b>start_tls (default: no)</b>
 657               Whether or not to issue STARTTLS upon connection to
 658               the  server.  Don't set this with LDAP SSL (the SSL
 659               session is setup automatically when the TCP connec-
 660               tion is opened).
 661
 662        <b>tls_ca_cert_dir   (No   default;   set   either   this  or</b>
 663        <b>tls_ca_cert_file)</b>
 664               Directory  containing  X509  Certificate  Authority
 665               certificates in PEM format which are to  be  recog-
 666               nized  by  the  client  in SSL/TLS connections. The
 667               files each contain one CA certificate.   The  files
 668               are  looked  up  by the CA subject name hash value,
 669               which must hence be available. If more than one  CA
 670               certificate  with  the  same name hash value exist,
 671               the extension must be different  (e.g.  9d66eef0.0,
 672               9d66eef0.1  etc).  The  search  is performed in the
 673               ordering of the  extension  number,  regardless  of
 674               other  properties  of  the  certificates.  Use  the
 675               c_rehash utility (from the OpenSSL distribution) to
 676               create the necessary links.
 677
 678        <b>tls_ca_cert_file   (No   default;   set   either  this  or</b>
 679        <b>tls_ca_cert_dir)</b>
 680               File containing the X509 Certificate Authority cer-
 681               tificates in PEM format which are to be  recognized
 682               by  the client in SSL/TLS connections. This setting
 683               takes precedence over tls_ca_cert_dir.
 684
 685        <b>tls_cert (No default; you must set this)</b>
 686               File containing client's  X509  certificate  to  be
 687               used by the client in SSL/ TLS connections.
 688
 689        <b>tls_key (No default; you must set this)</b>
 690               File  containing  the  private key corresponding to
 691               the above tls_cert.
 692
 693        <b>tls_require_cert (default: no)</b>
 694               Whether or not to request server's X509 certificate
 695               and  check  its  validity when establishing SSL/TLS
 696               connections.  The supported values are <b>no</b> and  <b>yes</b>.
 697
 698               With  <b>no</b>, the server certificate trust chain is not
 699               checked, but with OpenLDAP  prior  to  2.1.13,  the
 700               name in the server certificate must still match the
 701               LDAP server name. With OpenLDAP 2.0.0 to 2.0.11 the
 702               server  name is not necessarily what you specified,
 703               rather it is determined (by  reverse  lookup)  from
 704               the  IP address of the LDAP server connection. With
 705               OpenLDAP prior  to  2.0.13,  subjectAlternativeName
 706               extensions  in  the  LDAP  server  certificate  are
 707               ignored: the server name  must  match  the  subject
 708               CommonName. The <b>no</b> setting corresponds to the <b>never</b>
 709               value of <b>TLS_REQCERT</b> in LDAP  client  configuration
 710               files.
 711
 712               Don't  use  TLS with OpenLDAP 2.0.x (and especially
 713               with x &lt;= 11) if you can avoid it.
 714
 715               With <b>yes</b>, the server certificate must be issued  by
 716               a  trusted  CA, and not be expired. The LDAP server
 717               name must match one of the  name(s)  found  in  the
 718               certificate (see above for OpenLDAP library version
 719               dependent behavior). The <b>yes</b> setting corresponds to
 720               the <b>demand</b> value of <b>TLS_REQCERT</b> in LDAP client con-
 721               figuration files.
 722
 723               The "try" and "never" values of <b>TLS_REQCERT</b> have no
 724               equivalents  here.  They  are  not  available  with
 725               OpenLDAP 2.0, and in  any  case  have  questionable
 726               security  properties.  Either you want TLS verified
 727               LDAP connections, or you don't.
 728
 729               The <b>yes</b> value only works correctly with Postfix 2.5
 730               and  later,  or  with OpenLDAP 2.0. Earlier Postfix
 731               releases or  later  OpenLDAP  releases  don't  work
 732               together  with  this setting. Support for LDAP over
 733               TLS was added to Postfix based on the OpenLDAP  2.0
 734               API.
 735
 736        <b>tls_random_file (No default)</b>
 737               Path  of  a  file  to  obtain random bits from when
 738               /dev/[u]random is not available, to be used by  the
 739               client in SSL/TLS connections.
 740
 741        <b>tls_cipher_suite (No default)</b>
 742               Cipher suite to use in SSL/TLS negotiations.
 743
 744 <b>EXAMPLE</b>
 745        Here's  a basic example for using LDAP to look up <a href="local.8.html">local(8)</a>
 746        aliases.  Assume that in <a href="postconf.5.html">main.cf</a>, you have:
 747
 748            <a href="postconf.5.html#alias_maps">alias_maps</a> = hash:/etc/aliases,
 749                    <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
 750
 751        and in <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf you have:
 752
 753            server_host = ldap.example.com
 754            search_base = dc=example, dc=com
 755
 756        Upon receiving mail for a local  address  "ldapuser"  that
 757        isn't  found  in  the  /etc/aliases database, Postfix will
 758        search the LDAP server listening at port 389 on ldap.exam-
 759        ple.com.   It will bind anonymously, search for any direc-
 760        tory entries  whose  mailacceptinggeneralid  attribute  is
 761        "ldapuser", read the "maildrop" attributes of those found,
 762        and build a list of their maildrops, which will be treated
 763        as  <a href="http://tools.ietf.org/html/rfc822">RFC822</a>  addresses  to which the message will be deliv-
 764        ered.
 765
 766 <b>SEE ALSO</b>
 767        <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
 768        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 769        <a href="mysql_table.5.html">mysql_table(5)</a>, MySQL lookup tables
 770        <a href="pgsql_table.5.html">pgsql_table(5)</a>, PostgreSQL lookup tables
 771
 772 <b>README FILES</b>
 773        <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
 774        <a href="LDAP_README.html">LDAP_README</a>, Postfix LDAP client guide
 775
 776 <b>LICENSE</b>
 777        The  Secure  Mailer  license must be distributed with this
 778        software.
 779
 780 <b>AUTHOR(S)</b>
 781        Carsten Hoeger, Hery  Rakotoarisoa,  John  Hensley,  Keith
 782        Stevenson,  LaMont Jones, Liviu Daia, Manuel Guesdon, Mike
 783        Mattice, Prabhat K Singh, Sami Haahtinen, Samuel  Tardieu,
 784        Victor Duchovni, and many others.
 785
 786                                                                  LDAP_TABLE(5)
 787 </pre> </body> </html>