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