1LDAP_TABLE(5)                 File Formats Manual                LDAP_TABLE(5)
2
3
4

NAME

6       ldap_table - Postfix LDAP client configuration
7

SYNOPSIS

9       postmap -q "string" ldap:/etc/postfix/filename
10
11       postmap -q - ldap:/etc/postfix/filename <inputfile
12

DESCRIPTION

14       The  Postfix  mail system uses optional tables for address rewriting or
15       mail routing. These tables are usually in dbm or db format.
16
17       Alternatively, lookup tables can be specified as LDAP databases.
18
19       In order to use LDAP lookups, define an LDAP source as a  lookup  table
20       in main.cf, for example:
21
22           alias_maps = ldap:/etc/postfix/ldap-aliases.cf
23
24       The  file /etc/postfix/ldap-aliases.cf has the same format as the Post‐
25       fix main.cf file, and can specify the parameters  described  below.  An
26       example is given at the end of this manual.
27
28       This  configuration  method  is  available with Postfix version 2.1 and
29       later.  See the section "BACKWARDS COMPATIBILITY" below for older Post‐
30       fix versions.
31
32       For  details  about  LDAP  SSL and STARTTLS, see the section on SSL and
33       STARTTLS below.
34

BACKWARDS COMPATIBILITY

36       For backwards compatibility with Postfix version 2.0 and earlier,  LDAP
37       parameters  can  also  be defined in main.cf.  Specify as LDAP source a
38       name that doesn't begin with a slash or a  dot.   The  LDAP  parameters
39       will then be accessible as the name you've given the source in its def‐
40       inition, an underscore, and the name of the parameter.  For example, if
41       the  map is specified as "ldap:ldapsource", the "server_host" parameter
42       below would be defined in main.cf as "ldapsource_server_host".
43
44       Note: with this form, the passwords for the LDAP sources are written in
45       main.cf,  which is normally world-readable.  Support for this form will
46       be removed in a future Postfix version.
47
48       Postfix 2.2 has enhanced query interfaces  for  MySQL  and  PostgreSQL.
49       These include features that were previously available only in the Post‐
50       fix LDAP client. This work also created an opportunity for improvements
51       in  the  LDAP  interface.  The  primary  compatibility  issue  is  that
52       result_filter (a name that has caused some confusion as to its  meaning
53       in the past) has been renamed to result_format.  For backwards compati‐
54       bility with the pre 2.2 LDAP client, result_filter can for now be  used
55       instead  of  result_format,  when the latter parameter is not also set.
56       The new name better reflects the function of the parameter.  This  com‐
57       patibility interface may be removed in a future release.
58

LIST MEMBERSHIP

60       When  using  LDAP  to  store lists such as $mynetworks, $mydestination,
61       $relay_domains, $local_recipient_maps, etc., it is important to  under‐
62       stand that the table must store each list member as a separate key. The
63       table lookup verifies the *existence* of the key.  See  "Postfix  lists
64       versus tables" in the DATABASE_README document for a discussion.
65
66       Do  NOT create tables that return the full list of domains in $mydesti‐
67       nation or $relay_domains etc., or IP addresses in $mynetworks.
68
69       DO create tables with each matching item as a key and with an arbitrary
70       value. With LDAP databases it is not uncommon to return the key itself.
71
72       For example, NEVER do this in a map defining $mydestination:
73
74           query_filter = domain=*
75           result_attribute = domain
76
77       Do this instead:
78
79           query_filter = domain=%s
80           result_attribute = domain
81

GENERAL LDAP PARAMETERS

83       In  the  text  below,  default  values are given in parentheses.  Note:
84       don't use quotes in these variables; at least, not  until  the  Postfix
85       configuration routines understand how to deal with quoted strings.
86
87       server_host (default: localhost)
88              The name of the host running the LDAP server, e.g.
89
90                  server_host = ldap.example.com
91
92              Depending  on the LDAP client library you're using, it should be
93              possible to specify multiple servers here, with the library try‐
94              ing  them  in order should the first one fail. It should also be
95              possible to give each server in the list a different port (over‐
96              riding server_port below), by naming them like
97
98                  server_host = ldap.example.com:1444
99
100              With OpenLDAP, a (list of) LDAP URLs can be used to specify both
101              the hostname(s) and the port(s):
102
103                  server_host = ldap://ldap.example.com:1444
104                              ldap://ldap2.example.com:1444
105
106              All LDAP URLs accepted by the OpenLDAP  library  are  supported,
107              including  connections  over  UNIX  domain sockets, and LDAP SSL
108              (the last one provided that OpenLDAP was compiled  with  support
109              for SSL):
110
111                  server_host = ldapi://%2Fsome%2Fpath
112                              ldaps://ldap.example.com:636
113
114       server_port (default: 389)
115              The port the LDAP server listens on, e.g.
116
117                  server_port = 778
118
119       timeout (default: 10 seconds)
120              The number of seconds a search can take before timing out, e.g.
121
122                  timeout = 5
123
124       search_base (No default; you must configure this)
125              The RFC2253 base DN at which to conduct the search, e.g.
126
127                  search_base = dc=your, dc=com
128
129              With Postfix 2.2 and later this parameter supports the following
130              '%' expansions:
131
132              %%     This is replaced by a literal '%' character.
133
134              %s     This is replaced by the input key.  RFC 2253  quoting  is
135                     used  to  make sure that the input key does not add unex‐
136                     pected metacharacters.
137
138              %u     When the input key is an address of the form user@domain,
139                     %u is replaced by the (RFC 2253) quoted local part of the
140                     address.  Otherwise, %u is replaced by the entire  search
141                     string.   If  the  localpart is empty, the search is sup‐
142                     pressed and returns no results.
143
144              %d     When the input key is an address of the form user@domain,
145                     %d  is  replaced  by the (RFC 2253) quoted domain part of
146                     the address.  Otherwise, the  search  is  suppressed  and
147                     returns no results.
148
149              %[SUD] For the search_base parameter, the upper-case equivalents
150                     of the  above  expansions  behave  identically  to  their
151                     lower-case  counter-parts. With the result_format parame‐
152                     ter (previously called result_filter see the  COMPATIBIL‐
153                     ITY  section and below), they expand to the corresponding
154                     components of input key rather than the result value.
155
156              %[1-9] The patterns %1, %2, ... %9 are replaced  by  the  corre‐
157                     sponding  most  significant  component of the input key's
158                     domain. If the input key is  user@mail.example.com,  then
159                     %1 is com, %2 is example and %3 is mail. If the input key
160                     is unqualified or does not have enough domain  components
161                     to satisfy all the specified patterns, the search is sup‐
162                     pressed and returns no results.
163
164       query_filter (default: mailacceptinggeneralid=%s)
165              The RFC2254 filter used to search the directory, where %s  is  a
166              substitute for the address Postfix is trying to resolve, e.g.
167
168                  query_filter = (&(mail=%s)(paid_up=true))
169
170              This parameter supports the following '%' expansions:
171
172              %%     This is replaced by a literal '%' character. (Postfix 2.2
173                     and later).
174
175              %s     This is replaced by the input key.  RFC 2254  quoting  is
176                     used  to  make sure that the input key does not add unex‐
177                     pected metacharacters.
178
179              %u     When the input key is an address of the form user@domain,
180                     %u is replaced by the (RFC 2254) quoted local part of the
181                     address.  Otherwise, %u is replaced by the entire  search
182                     string.   If  the  localpart is empty, the search is sup‐
183                     pressed and returns no results.
184
185              %d     When the input key is an address of the form user@domain,
186                     %d  is  replaced  by the (RFC 2254) quoted domain part of
187                     the address.  Otherwise, the  search  is  suppressed  and
188                     returns no results.
189
190              %[SUD] The upper-case equivalents of the above expansions behave
191                     in the query_filter parameter identically to their lower-
192                     case  counter-parts.  With  the  result_format  parameter
193                     (previously called result_filter  see  the  COMPATIBILITY
194                     section and below), they expand to the corresponding com‐
195                     ponents of input key rather than the result value.
196
197                     The above %S, %U and %D  expansions  are  available  with
198                     Postfix 2.2 and later.
199
200              %[1-9] The  patterns  %1,  %2, ... %9 are replaced by the corre‐
201                     sponding most significant component of  the  input  key's
202                     domain.  If  the input key is user@mail.example.com, then
203                     %1 is com, %2 is example and %3 is mail. If the input key
204                     is  unqualified or does not have enough domain components
205                     to satisfy all the specified patterns, the search is sup‐
206                     pressed and returns no results.
207
208                     The above %1, ..., %9 expansions are available with Post‐
209                     fix 2.2 and later.
210
211              The "domain" parameter described below limits the input keys  to
212              addresses  in  matching  domains. When the "domain" parameter is
213              non-empty, LDAP queries for unqualified addresses  or  addresses
214              in non-matching domains are suppressed and return no results.
215
216              NOTE: DO NOT put quotes around the query_filter parameter.
217
218       result_format (default: %s)
219              Called  result_filter  in Postfix releases prior to 2.2.  Format
220              template applied to result attributes.  Most  commonly  used  to
221              append  (or prepend) text to the result. This parameter supports
222              the following '%' expansions:
223
224              %%     This is replaced by a literal '%' character. (Postfix 2.2
225                     and later).
226
227              %s     This  is  replaced  by the value of the result attribute.
228                     When result is empty it is skipped.
229
230              %u     When the result attribute value is an address of the form
231                     user@domain,  %u  is  replaced  by  the local part of the
232                     address. When the result has an  empty  localpart  it  is
233                     skipped.
234
235              %d     When  a  result attribute value is an address of the form
236                     user@domain, %d is replaced by the  domain  part  of  the
237                     attribute  value.  When  the  result is unqualified it is
238                     skipped.
239
240              %[SUD1-9]
241                     The upper-case and decimal digit  expansions  interpolate
242                     the  parts of the input key rather than the result. Their
243                     behavior is identical to that described  with  query_fil‐
244                     ter,  and  in  fact  because  the  input  key is known in
245                     advance, lookups whose  key  does  not  contain  all  the
246                     information  specified  in  the  result template are sup‐
247                     pressed and return no results.
248
249                     The above %S, %U, %D  and  %1,  ...,  %9  expansions  are
250                     available with Postfix 2.2 and later.
251
252              For example, using "result_format = smtp:[%s]" allows one to use
253              a mailHost attribute as the basis of a transport(5) table. After
254              applying  the result format, multiple values are concatenated as
255              comma separated  strings.  The  expansion_limit  and  size_limit
256              parameters  explained  below allow one to restrict the number of
257              values in the result, which is especially useful for  maps  that
258              should return a single value.
259
260              The  default value %s specifies that each attribute value should
261              be used as is.
262
263              This parameter was  called  result_filter  in  Postfix  releases
264              prior  to  2.2. If no "result_format" is specified, the value of
265              "result_filter" will be used instead  before  resorting  to  the
266              default  value.  This provides compatibility with old configura‐
267              tion files.
268
269              NOTE: DO NOT put quotes around the result format!
270
271       domain (default: no domain list)
272              This is a list of domain names, paths to files, or dictionaries.
273              When  specified,  only  fully qualified search keys with a *non-
274              empty* localpart and a matching domain are eligible for  lookup:
275              'user'  lookups,  bare  domain lookups and "@domain" lookups are
276              not performed. This can significantly reduce the query  load  on
277              the LDAP server.
278
279                  domain = postfix.org, hash:/etc/postfix/searchdomains
280
281              It  is  best  not  to use LDAP to store the domains eligible for
282              LDAP lookups.
283
284              NOTE: DO NOT define this parameter for local(8) aliases.
285
286              This feature is available in Postfix 1.0 and later.
287
288       result_attribute (default: maildrop)
289              The attribute(s) Postfix will read from  any  directory  entries
290              returned by the lookup, to be resolved to an email address.
291
292                  result_attribute = mailbox, maildrop
293
294       special_result_attribute (default: empty)
295              The  attribute(s)  of  directory entries that can contain DNs or
296              URLs. If found, a recursive  subsequent  search  is  done  using
297              their values.
298
299                  special_result_attribute = memberdn
300
301              DN  recursion  retrieves  the same result_attributes as the main
302              query, including the special attributes for  further  recursion.
303              URI processing retrieves only those attributes that are included
304              in   the   URI   definition   and   are   *also*    listed    in
305              "result_attribute".  If  the  URI lists any of the map's special
306              result attributes, these are  also  retrieved  and  used  recur‐
307              sively.
308
309       terminal_result_attribute (default: empty)
310              When one or more terminal result attributes are found in an LDAP
311              entry, all other result attributes are ignored and only the ter‐
312              minal  result  attributes are returned. This is useful for dele‐
313              gating expansion of group members to a particular host, by using
314              an optional "maildrop" attribute on selected groups to route the
315              group to a specific host, where the group is expanded,  possibly
316              via mailing-list manager or other special processing.
317
318                  terminal_result_attribute = maildrop
319
320              This feature is available with Postfix 2.4 or later.
321
322       leaf_result_attribute (default: empty)
323              When  one  or more special result attributes are found in a non-
324              terminal (see above) LDAP  entry,  leaf  result  attributes  are
325              excluded  from  the expansion of that entry. This is useful when
326              expanding groups and the desired mail  address  attribute(s)  of
327              the  member  objects  obtained  via DN or URI recursion are also
328              present in the group object. To only return the attribute values
329              from  the  leaf  objects  and  not the containing group, add the
330              attribute  to  the  leaf_result_attribute  list,  and  not   the
331              result_attribute  list,  which  is  always  expanded.  Note, the
332              default value of "result_attribute" is not empty, you  may  want
333              to set it explicitly empty when using "leaf_result_attribute" to
334              expand the group to a list of member  DN  addresses.  If  groups
335              have both member DN references AND attributes that hold multiple
336              string valued rfc822 addresses, then the string attributes go in
337              "result_attribute".   The  attributes  that  represent the email
338              addresses of objects referenced via a DN (or  LDAP  URI)  go  in
339              "leaf_result_attribute".
340
341                  result_attribute = memberaddr
342                  special_result_attribute = memberdn
343                  terminal_result_attribute = maildrop
344                  leaf_result_attribute = mail
345
346              This feature is available with Postfix 2.4 or later.
347
348       scope (default: sub)
349              The  LDAP search scope: sub, base, or one.  These translate into
350              LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE, and LDAP_SCOPE_ONELEVEL.
351
352       bind (default: yes)
353              Whether or not to bind to the LDAP server. Newer LDAP  implemen‐
354              tations  don't  require clients to bind, which saves time. Exam‐
355              ple:
356
357                  bind = no
358
359              If you do need to bind, you might consider  configuring  Postfix
360              to  connect  to the local machine on a port that's an SSL tunnel
361              to your LDAP server. If your LDAP server doesn't  natively  sup‐
362              port  SSL,  put  a  tunnel (wrapper, proxy, whatever you want to
363              call it) on that system too. This should  prevent  the  password
364              from traversing the network in the clear.
365
366       bind_dn (default: empty)
367              If  you  do  have  to  bind, do it with this distinguished name.
368              Example:
369
370                  bind_dn = uid=postfix, dc=your, dc=com
371
372       bind_pw (default: empty)
373              The password for the distinguished name above. If  you  have  to
374              use  this,  you probably want to make the map configuration file
375              readable only by the  Postfix  user.  When  using  the  obsolete
376              ldap:ldapsource  syntax,  with  map parameters in main.cf, it is
377              not possible to  securely  store  the  bind  password.  This  is
378              because  main.cf  needs  to  be  world  readable  to allow local
379              accounts to submit mail via the sendmail command. Example:
380
381                  bind_pw = postfixpw
382
383       cache (IGNORED with a warning)
384
385       cache_expiry (IGNORED with a warning)
386
387       cache_size (IGNORED with a warning)
388              The above parameters are NO LONGER SUPPORTED by Postfix.   Cache
389              support has been dropped from OpenLDAP as of release 2.1.13.
390
391       recursion_limit (default: 1000)
392              A  limit  on  the  nesting  depth  of  DN and URL special result
393              attribute evaluation. The limit must be a non-zero positive num‐
394              ber.
395
396       expansion_limit (default: 0)
397              A  limit  on  the total number of result elements returned (as a
398              comma separated list) by a lookup against the map.  A setting of
399              zero  disables the limit. Lookups fail with a temporary error if
400              the limit is exceeded.  Setting the  limit  to  1  ensures  that
401              lookups do not return multiple values.
402
403       size_limit (default: $expansion_limit)
404              A  limit  on  the  number of LDAP entries returned by any single
405              LDAP search performed as part of the lookup. A setting of 0 dis‐
406              ables  the  limit.   Expansion of DN and URL references involves
407              nested LDAP queries, each of which is  separately  subjected  to
408              this limit.
409
410              Note:  even  a  single  LDAP  entry can generate multiple lookup
411              results, via  multiple  result  attributes  and/or  multi-valued
412              result  attributes. This limit caps the per search resource uti‐
413              lization on the LDAP server, not the final multiplicity  of  the
414              lookup   result.   It   is  analogous  to  the  "-z"  option  of
415              "ldapsearch".
416
417       dereference (default: 0)
418              When to dereference LDAP aliases. (Note that this has nothing do
419              with  Postfix aliases.) The permitted values are those legal for
420              the OpenLDAP/UM LDAP implementations:
421
422              0      never
423
424              1      when searching
425
426              2      when locating the base object for the search
427
428              3      always
429
430              See ldap.h or the ldap_open(3) or ldapsearch(1)  man  pages  for
431              more  information.  And if you're using an LDAP package that has
432              other possible values, please bring it to the attention  of  the
433              postfix-users@postfix.org mailing list.
434
435       chase_referrals (default: 0)
436              Sets  (or  clears)  LDAP_OPT_REFERRALS  (requires LDAP version 3
437              support).
438
439       version (default: 2)
440              Specifies the LDAP protocol version to use.
441
442       debuglevel (default: 0)
443              What level to set for debugging in the OpenLDAP libraries.
444

LDAP SSL AND STARTTLS PARAMETERS

446       If you're using the OpenLDAP libraries compiled with SSL support, Post‐
447       fix can connect to LDAP SSL servers and can issue the STARTTLS command.
448
449       LDAP  SSL  service  can  be  requested  by  using a LDAP SSL URL in the
450       server_host parameter:
451
452           server_host = ldaps://ldap.example.com:636
453
454       STARTTLS can be turned on with the start_tls parameter:
455
456           start_tls = yes
457
458       Both forms require LDAP protocol version 3, which has to be set explic‐
459       itly with:
460
461           version = 3
462
463       If  any  of the Postfix programs querying the map is configured in mas‐
464       ter.cf to run chrooted, all the certificates and keys involved have  to
465       be  copied  to the chroot jail. Of course, the private keys should only
466       be readable by the user "postfix".
467
468       The following parameters are relevant to LDAP SSL and STARTTLS:
469
470       start_tls (default: no)
471              Whether or not to issue STARTTLS upon connection to the  server.
472              Don't set this with LDAP SSL (the SSL session is setup automati‐
473              cally when the TCP connection is opened).
474
475       tls_ca_cert_dir (No default; set either this or tls_ca_cert_file)
476              Directory containing X509 Certificate Authority certificates  in
477              PEM  format  which are to be recognized by the client in SSL/TLS
478              connections. The files each contain  one  CA  certificate.   The
479              files  are  looked  up  by the CA subject name hash value, which
480              must hence be available. If more than one  CA  certificate  with
481              the  same name hash value exist, the extension must be different
482              (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search  is  performed  in
483              the  ordering of the extension number, regardless of other prop‐
484              erties of the certificates. Use the c_rehash utility  (from  the
485              OpenSSL distribution) to create the necessary links.
486
487       tls_ca_cert_file (No default; set either this or tls_ca_cert_dir)
488              File  containing  the X509 Certificate Authority certificates in
489              PEM format which are to be recognized by the client  in  SSL/TLS
490              connections. This setting takes precedence over tls_ca_cert_dir.
491
492       tls_cert (No default; you must set this)
493              File  containing  client's  X509  certificate  to be used by the
494              client in SSL/ TLS connections.
495
496       tls_key (No default; you must set this)
497              File containing the  private  key  corresponding  to  the  above
498              tls_cert.
499
500       tls_require_cert (default: no)
501              Whether  or  not  to request server's X509 certificate and check
502              its validity when establishing SSL/TLS connections.
503
504       tls_random_file (No default)
505              Path of a file to obtain random bits from when /dev/[u]random is
506              not available, to be used by the client in SSL/TLS connections.
507
508       tls_cipher_suite (No default)
509              Cipher suite to use in SSL/TLS negotiations.
510

EXAMPLE

512       Here's  a  basic  example  for  using LDAP to look up local(8) aliases.
513       Assume that in main.cf, you have:
514
515           alias_maps = hash:/etc/aliases,
516                   ldap:/etc/postfix/ldap-aliases.cf
517
518       and in ldap:/etc/postfix/ldap-aliases.cf you have:
519
520           server_host = ldap.example.com
521           search_base = dc=example, dc=com
522
523       Upon receiving mail for a local address "ldapuser" that isn't found  in
524       the  /etc/aliases database, Postfix will search the LDAP server listen‐
525       ing at port 389 on ldap.example.com.  It will bind anonymously,  search
526       for  any  directory  entries  whose mailacceptinggeneralid attribute is
527       "ldapuser", read the "maildrop" attributes of those found, and build  a
528       list  of  their maildrops, which will be treated as RFC822 addresses to
529       which the message will be delivered.
530

SEE ALSO

532       postmap(1), Postfix lookup table manager
533       postconf(5), configuration parameters
534       mysql_table(5), MySQL lookup tables
535       pgsql_table(5), PostgreSQL lookup tables
536

README FILES

538       Use "postconf readme_directory" or "postconf html_directory" to  locate
539       this information.
540       DATABASE_README, Postfix lookup table overview
541       LDAP_README, Postfix LDAP client guide
542

LICENSE

544       The Secure Mailer license must be distributed with this software.
545

AUTHOR(S)

547       Carsten  Hoeger, Hery Rakotoarisoa, John Hensley, Keith Stevenson, LaM‐
548       ont Jones, Liviu Daia, Manuel Guesdon, Mike Mattice, Prabhat  K  Singh,
549       Sami Haahtinen, Samuel Tardieu, Victor Duchovni, and many others.
550
551
552
553                                                                 LDAP_TABLE(5)
Impressum