1LDAP_TABLE(5) File Formats Manual LDAP_TABLE(5)
2
6 ldap_table - Postfix LDAP client configuration
7
9 postmap -q "string" ldap:/etc/postfix/filename
10 postmap -q - ldap:/etc/postfix/filename <inputfile
12
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 Alternatively, lookup tables can be specified as LDAP databases.
18 In order to use LDAP lookups, define an LDAP source as a lookup table
20 in main.cf, for example:
21 alias_maps = ldap:/etc/postfix/ldap-aliases.cf
23 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 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 For details about LDAP SSL and STARTTLS, see the section on SSL and
33 STARTTLS below.
34
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 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 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
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 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 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 For example, NEVER do this in a map defining $mydestination:
73 query_filter = domain=*
75 result_attribute = domain
76 Do this instead:
78 query_filter = domain=%s
80 result_attribute = domain
81
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 server_host (default: localhost)
88 The name of the host running the LDAP server, e.g.
89 server_host = ldap.example.com
91 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 server_host = ldap.example.com:1444
99 With OpenLDAP, a (list of) LDAP URLs can be used to specify both
101 the hostname(s) and the port(s):
102 server_host = ldap://ldap.example.com:1444
104 ldap://ldap2.example.com:1444
105 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 server_host = ldapi://%2Fsome%2Fpath
112 ldaps://ldap.example.com:636
113 server_port (default: 389)
115 The port the LDAP server listens on, e.g.
116 server_port = 778
118 timeout (default: 10 seconds)
120 The number of seconds a search can take before timing out, e.g.
121 timeout = 5
123 search_base (No default; you must configure this)
125 The RFC2253 base DN at which to conduct the search, e.g.
126 search_base = dc=your, dc=com
128 With Postfix 2.2 and later this parameter supports the following
130 '%' expansions:
131 %% This is replaced by a literal '%' character.
133 %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 %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 %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 %[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 %[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 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 query_filter = (&(mail=%s)(paid_up=true))
169 This parameter supports the following '%' expansions:
171 %% This is replaced by a literal '%' character. (Postfix 2.2
173 and later).
174 %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 %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 %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 %[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 The above %S, %U and %D expansions are available with
198 Postfix 2.2 and later.
199 %[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 The above %1, ..., %9 expansions are available with Post‐
209 fix 2.2 and later.
210 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 NOTE: DO NOT put quotes around the query_filter parameter.
217 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 %% This is replaced by a literal '%' character. (Postfix 2.2
225 and later).
226 %s This is replaced by the value of the result attribute.
228 When result is empty it is skipped.
229 %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 %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 %[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 The above %S, %U, %D and %1, ..., %9 expansions are
250 available with Postfix 2.2 and later.
251 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 The default value %s specifies that each attribute value should
261 be used as is.
262 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 NOTE: DO NOT put quotes around the result format!
270 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 domain = postfix.org, hash:/etc/postfix/searchdomains
280 It is best not to use LDAP to store the domains eligible for
282 LDAP lookups.
283 NOTE: DO NOT define this parameter for local(8) aliases.
285 This feature is available in Postfix 1.0 and later.
287 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 result_attribute = mailbox, maildrop
293 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 special_result_attribute = memberdn
300 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 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 terminal_result_attribute = maildrop
319 This feature is available with Postfix 2.4 or later.
321 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 result_attribute = memberaddr
342 special_result_attribute = memberdn
343 terminal_result_attribute = maildrop
344 leaf_result_attribute = mail
345 This feature is available with Postfix 2.4 or later.
347 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 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 bind = no
358 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 bind_dn (default: empty)
367 If you do have to bind, do it with this distinguished name.
368 Example:
369 bind_dn = uid=postfix, dc=your, dc=com
371 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 bind_pw = postfixpw
382 cache (IGNORED with a warning)
384 cache_expiry (IGNORED with a warning)
386 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 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 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 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 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 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 0 never
423 1 when searching
425 2 when locating the base object for the search
427 3 always
429 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 chase_referrals (default: 0)
436 Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP version 3
437 support).
438 version (default: 2)
440 Specifies the LDAP protocol version to use.
441 debuglevel (default: 0)
443 What level to set for debugging in the OpenLDAP libraries.
444
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 LDAP SSL service can be requested by using a LDAP SSL URL in the
450 server_host parameter:
451 server_host = ldaps://ldap.example.com:636
453 STARTTLS can be turned on with the start_tls parameter:
455 start_tls = yes
457 Both forms require LDAP protocol version 3, which has to be set explic‐
459 itly with:
460 version = 3
462 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 The following parameters are relevant to LDAP SSL and STARTTLS:
469 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 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 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 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 tls_key (No default; you must set this)
497 File containing the private key corresponding to the above
498 tls_cert.
499 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. The sup‐
503 ported values are no and yes.
504 With no, the server certificate trust chain is not checked, but
506 with OpenLDAP prior to 2.1.13, the name in the server certifi‐
507 cate must still match the LDAP server name. With OpenLDAP 2.0.0
508 to 2.0.11 the server name is not necessarily what you specified,
509 rather it is determined (by reverse lookup) from the IP address
510 of the LDAP server connection. With OpenLDAP prior to 2.0.13,
511 subjectAlternativeName extensions in the LDAP server certificate
512 are ignored: the server name must match the subject CommonName.
513 The no setting corresponds to the never value of TLS_REQCERT in
514 LDAP client configuration files.
515 Don't use TLS with OpenLDAP 2.0.x (and especially with x <= 11)
517 if you can avoid it.
518 With yes, the server certificate must be issued by a trusted CA,
520 and not be expired. The LDAP server name must match one of the
521 name(s) found in the certificate (see above for OpenLDAP library
522 version dependent behavior). The yes setting corresponds to the
523 demand value of TLS_REQCERT in LDAP client configuration files.
524 The "try" and "never" values of TLS_REQCERT have no equivalents
526 here. They are not available with OpenLDAP 2.0, and in any case
527 have questionable security properties. Either you want TLS veri‐
528 fied LDAP connections, or you don't.
529 The yes value only works correctly with Postfix 2.5 and later,
531 or with OpenLDAP 2.0. Earlier Postfix releases or later OpenLDAP
532 releases don't work together with this setting. Support for LDAP
533 over TLS was added to Postfix based on the OpenLDAP 2.0 API.
534 tls_random_file (No default)
536 Path of a file to obtain random bits from when /dev/[u]random is
537 not available, to be used by the client in SSL/TLS connections.
538 tls_cipher_suite (No default)
540 Cipher suite to use in SSL/TLS negotiations.
541
543 Here's a basic example for using LDAP to look up local(8) aliases.
544 Assume that in main.cf, you have:
545 alias_maps = hash:/etc/aliases,
547 ldap:/etc/postfix/ldap-aliases.cf
548 and in ldap:/etc/postfix/ldap-aliases.cf you have:
550 server_host = ldap.example.com
552 search_base = dc=example, dc=com
553 Upon receiving mail for a local address "ldapuser" that isn't found in
555 the /etc/aliases database, Postfix will search the LDAP server listen‐
556 ing at port 389 on ldap.example.com. It will bind anonymously, search
557 for any directory entries whose mailacceptinggeneralid attribute is
558 "ldapuser", read the "maildrop" attributes of those found, and build a
559 list of their maildrops, which will be treated as RFC822 addresses to
560 which the message will be delivered.
561
563 postmap(1), Postfix lookup table manager
564 postconf(5), configuration parameters
565 mysql_table(5), MySQL lookup tables
566 pgsql_table(5), PostgreSQL lookup tables
567
569 Use "postconf readme_directory" or "postconf html_directory" to locate
570 this information.
571 DATABASE_README, Postfix lookup table overview
572 LDAP_README, Postfix LDAP client guide
573
575 The Secure Mailer license must be distributed with this software.
576
578 Carsten Hoeger, Hery Rakotoarisoa, John Hensley, Keith Stevenson, LaM‐
579 ont Jones, Liviu Daia, Manuel Guesdon, Mike Mattice, Prabhat K Singh,
580 Sami Haahtinen, Samuel Tardieu, Victor Duchovni, and many others.
581 LDAP_TABLE(5)