5 # Postfix LDAP client configuration
7 # \fBpostmap -q "\fIstring\fB" ldap:/etc/postfix/filename\fR
9 # \fBpostmap -q - ldap:/etc/postfix/\fIfilename\fR <\fIinputfile\fR
11 # The Postfix mail system uses optional tables for address
12 # rewriting or mail routing. These tables are usually in
13 # \fBdbm\fR or \fBdb\fR format.
15 # Alternatively, lookup tables can be specified as LDAP databases.
17 # In order to use LDAP lookups, define an LDAP source as a lookup
18 # table in main.cf, for example:
21 # alias_maps = ldap:/etc/postfix/ldap-aliases.cf
24 # The file /etc/postfix/ldap-aliases.cf has the same format as
25 # the Postfix main.cf file, and can specify the parameters
26 # described below. An example is given at the end of this manual.
28 # This configuration method is available with Postfix version
29 # 2.1 and later. See the section "BACKWARDS COMPATIBILITY"
30 # below for older Postfix versions.
32 # For details about LDAP SSL and STARTTLS, see the section
33 # on SSL and STARTTLS below.
34 # BACKWARDS COMPATIBILITY
37 # For backwards compatibility with Postfix version 2.0 and earlier,
38 # LDAP parameters can also be defined in main.cf. Specify
39 # as LDAP source a name that doesn't begin with a slash or
40 # a dot. The LDAP parameters will then be accessible as the
41 # name you've given the source in its definition, an underscore,
42 # and the name of the parameter. For example, if the map is
43 # specified as "ldap:\fIldapsource\fR", the "server_host"
44 # parameter below would be defined in main.cf as
45 # "\fIldapsource\fR_server_host".
47 # Note: with this form, the passwords for the LDAP sources are
48 # written in main.cf, which is normally world-readable. Support
49 # for this form will be removed in a future Postfix version.
51 # Postfix 2.2 has enhanced query interfaces for MySQL and PostgreSQL.
52 # These include features that were previously available only in the
53 # Postfix LDAP client. This work also created an opportunity for
54 # improvements in the LDAP interface. The primary compatibility
55 # issue is that \fBresult_filter\fR (a name that has caused some
56 # confusion as to its meaning in the past) has been renamed to
57 # \fBresult_format\fR. For backwards compatibility with the pre
58 # 2.2 LDAP client, \fBresult_filter\fR can for now be used instead
59 # of \fBresult_format\fR, when the latter parameter is not also set.
60 # The new name better reflects the function of the parameter. This
61 # compatibility interface may be removed in a future release.
65 # When using LDAP to store lists such as $mynetworks,
66 # $mydestination, $relay_domains, $local_recipient_maps,
67 # etc., it is important to understand that the table must
68 # store each list member as a separate key. The table lookup
69 # verifies the *existence* of the key. See "Postfix lists
70 # versus tables" in the DATABASE_README document for a
73 # Do NOT create tables that return the full list of domains
74 # in $mydestination or $relay_domains etc., or IP addresses
77 # DO create tables with each matching item as a key and with
78 # an arbitrary value. With LDAP databases it is not uncommon to
79 # return the key itself.
81 # For example, NEVER do this in a map defining $mydestination:
84 # query_filter = domain=*
85 # result_attribute = domain
91 # query_filter = domain=%s
92 # result_attribute = domain
94 # GENERAL LDAP PARAMETERS
97 # In the text below, default values are given in parentheses.
98 # Note: don't use quotes in these variables; at least, not until the
99 # Postfix configuration routines understand how to deal with quoted
101 # .IP "\fBserver_host (default: localhost)\fR"
102 # The name of the host running the LDAP server, e.g.
105 # server_host = ldap.example.com
108 # Depending on the LDAP client library you're using, it should
109 # be possible to specify multiple servers here, with the library
110 # trying them in order should the first one fail. It should also
111 # be possible to give each server in the list a different port
112 # (overriding \fBserver_port\fR below), by naming them like
115 # server_host = ldap.example.com:1444
118 # With OpenLDAP, a (list of) LDAP URLs can be used to specify both
119 # the hostname(s) and the port(s):
122 # server_host = ldap://ldap.example.com:1444
123 # ldap://ldap2.example.com:1444
126 # All LDAP URLs accepted by the OpenLDAP library are supported,
127 # including connections over UNIX domain sockets, and LDAP SSL
128 # (the last one provided that OpenLDAP was compiled with support
132 # server_host = ldapi://%2Fsome%2Fpath
133 # ldaps://ldap.example.com:636
135 # .IP "\fBserver_port (default: 389)\fR"
136 # The port the LDAP server listens on, e.g.
141 # .IP "\fBtimeout (default: 10 seconds)\fR"
142 # The number of seconds a search can take before timing out, e.g.
147 # .IP "\fBsearch_base (No default; you must configure this)\fR"
148 # The RFC2253 base DN at which to conduct the search, e.g.
151 # search_base = dc=your, dc=com
154 # With Postfix 2.2 and later this parameter supports the
155 # following '%' expansions:
157 # .IP "\fB\fB%%\fR\fR"
158 # This is replaced by a literal '%' character.
159 # .IP "\fB\fB%s\fR\fR"
160 # This is replaced by the input key.
161 # RFC 2253 quoting is used to make sure that the input key
162 # does not add unexpected metacharacters.
163 # .IP "\fB\fB%u\fR\fR"
164 # When the input key is an address of the form user@domain, \fB%u\fR
165 # is replaced by the (RFC 2253) quoted local part of the address.
166 # Otherwise, \fB%u\fR is replaced by the entire search string.
167 # If the localpart is empty, the search is suppressed and returns
169 # .IP "\fB\fB%d\fR\fR"
170 # When the input key is an address of the form user@domain, \fB%d\fR
171 # is replaced by the (RFC 2253) quoted domain part of the address.
172 # Otherwise, the search is suppressed and returns no results.
173 # .IP "\fB\fB%[SUD]\fR\fR"
174 # For the \fBsearch_base\fR parameter, the upper-case equivalents
175 # of the above expansions behave identically to their lower-case
176 # counter-parts. With the \fBresult_format\fR parameter (previously
177 # called \fBresult_filter\fR see the COMPATIBILITY section and below),
178 # they expand to the corresponding components of input key rather
179 # than the result value.
180 # .IP "\fB\fB%[1-9]\fR\fR"
181 # The patterns %1, %2, ... %9 are replaced by the corresponding
182 # most significant component of the input key's domain. If the
183 # input key is \fIuser@mail.example.com\fR, then %1 is \fBcom\fR,
184 # %2 is \fBexample\fR and %3 is \fBmail\fR. If the input key is
185 # unqualified or does not have enough domain components to satisfy
186 # all the specified patterns, the search is suppressed and returns
189 # .IP "\fBquery_filter (default: mailacceptinggeneralid=%s)\fR"
190 # The RFC2254 filter used to search the directory, where \fB%s\fR
191 # is a substitute for the address Postfix is trying to resolve,
195 # query_filter = (&(mail=%s)(paid_up=true))
198 # This parameter supports the following '%' expansions:
200 # .IP "\fB\fB%%\fR\fR"
201 # This is replaced by a literal '%' character. (Postfix 2.2 and later).
202 # .IP "\fB\fB%s\fR\fR"
203 # This is replaced by the input key.
204 # RFC 2254 quoting is used to make sure that the input key
205 # does not add unexpected metacharacters.
206 # .IP "\fB\fB%u\fR\fR"
207 # When the input key is an address of the form user@domain, \fB%u\fR
208 # is replaced by the (RFC 2254) quoted local part of the address.
209 # Otherwise, \fB%u\fR is replaced by the entire search string.
210 # If the localpart is empty, the search is suppressed and returns
212 # .IP "\fB\fB%d\fR\fR"
213 # When the input key is an address of the form user@domain, \fB%d\fR
214 # is replaced by the (RFC 2254) quoted domain part of the address.
215 # Otherwise, the search is suppressed and returns no results.
216 # .IP "\fB\fB%[SUD]\fR\fR"
217 # The upper-case equivalents of the above expansions behave in the
218 # \fBquery_filter\fR parameter identically to their lower-case
219 # counter-parts. With the \fBresult_format\fR parameter (previously
220 # called \fBresult_filter\fR see the COMPATIBILITY section and below),
221 # they expand to the corresponding components of input key rather
222 # than the result value.
224 # The above %S, %U and %D expansions are available with Postfix 2.2
226 # .IP "\fB\fB%[1-9]\fR\fR"
227 # The patterns %1, %2, ... %9 are replaced by the corresponding
228 # most significant component of the input key's domain. If the
229 # input key is \fIuser@mail.example.com\fR, then %1 is \fBcom\fR,
230 # %2 is \fBexample\fR and %3 is \fBmail\fR. If the input key is
231 # unqualified or does not have enough domain components to satisfy
232 # all the specified patterns, the search is suppressed and returns
235 # The above %1, ..., %9 expansions are available with Postfix 2.2
239 # The "domain" parameter described below limits the input
240 # keys to addresses in matching domains. When the "domain"
241 # parameter is non-empty, LDAP queries for unqualified
242 # addresses or addresses in non-matching domains are suppressed
243 # and return no results.
245 # NOTE: DO NOT put quotes around the \fBquery_filter\fR parameter.
246 # .IP "\fBresult_format (default: \fB%s\fR)\fR"
247 # Called \fBresult_filter\fR in Postfix releases prior to 2.2.
248 # Format template applied to result attributes. Most commonly used
249 # to append (or prepend) text to the result. This parameter supports
250 # the following '%' expansions:
252 # .IP "\fB\fB%%\fR\fR"
253 # This is replaced by a literal '%' character. (Postfix 2.2 and later).
254 # .IP "\fB\fB%s\fR\fR"
255 # This is replaced by the value of the result attribute. When
256 # result is empty it is skipped.
258 # When the result attribute value is an address of the form
259 # user@domain, \fB%u\fR is replaced by the local part of the
260 # address. When the result has an empty localpart it is skipped.
261 # .IP "\fB\fB%d\fR\fR"
262 # When a result attribute value is an address of the form
263 # user@domain, \fB%d\fR is replaced by the domain part of
264 # the attribute value. When the result is unqualified it
266 # .IP "\fB\fB%[SUD1-9]\fR\fB"
267 # The upper-case and decimal digit expansions interpolate
268 # the parts of the input key rather than the result. Their
269 # behavior is identical to that described with \fBquery_filter\fR,
270 # and in fact because the input key is known in advance, lookups
271 # whose key does not contain all the information specified in
272 # the result template are suppressed and return no results.
274 # The above %S, %U, %D and %1, ..., %9 expansions are available with
275 # Postfix 2.2 and later.
278 # For example, using "result_format = smtp:[%s]" allows one
279 # to use a mailHost attribute as the basis of a transport(5)
280 # table. After applying the result format, multiple values
281 # are concatenated as comma separated strings. The expansion_limit
282 # and size_limit parameters explained below allow one to
283 # restrict the number of values in the result, which is
284 # especially useful for maps that should return a single
287 # The default value \fB%s\fR specifies that each
288 # attribute value should be used as is.
290 # This parameter was called \fBresult_filter\fR in Postfix
291 # releases prior to 2.2. If no "result_format" is specified,
292 # the value of "result_filter" will be used instead before
293 # resorting to the default value. This provides compatibility
294 # with old configuration files.
296 # NOTE: DO NOT put quotes around the result format!
297 # .IP "\fBdomain (default: no domain list)\fR"
298 # This is a list of domain names, paths to files, or
299 # dictionaries. When specified, only fully qualified search
300 # keys with a *non-empty* localpart and a matching domain
301 # are eligible for lookup: 'user' lookups, bare domain lookups
302 # and "@domain" lookups are not performed. This can significantly
303 # reduce the query load on the LDAP server.
306 # domain = postfix.org, hash:/etc/postfix/searchdomains
309 # It is best not to use LDAP to store the domains eligible
312 # NOTE: DO NOT define this parameter for local(8) aliases.
314 # This feature is available in Postfix 1.0 and later.
315 # .IP "\fBresult_attribute (default: maildrop)\fR"
316 # The attribute(s) Postfix will read from any directory
317 # entries returned by the lookup, to be resolved to an email
321 # result_attribute = mailbox, maildrop
323 # .IP "\fBspecial_result_attribute (default: empty)\fR"
324 # The attribute(s) of directory entries that can contain DNs
325 # or URLs. If found, a recursive subsequent search is done
326 # using their values.
329 # special_result_attribute = memberdn
332 # DN recursion retrieves the same result_attributes as the
333 # main query, including the special attributes for further
334 # recursion. URI processing retrieves only those attributes
335 # that are included in the URI definition and are *also*
336 # listed in "result_attribute". If the URI lists any of the
337 # map's special result attributes, these are also retrieved
338 # and used recursively.
339 # .IP "\fBterminal_result_attribute (default: empty)\fR"
340 # When one or more terminal result attributes are found in an LDAP
341 # entry, all other result attributes are ignored and only the terminal
342 # result attributes are returned. This is useful for delegating expansion
343 # of group members to a particular host, by using an optional "maildrop"
344 # attribute on selected groups to route the group to a specific host,
345 # where the group is expanded, possibly via mailing-list manager or
346 # other special processing.
349 # terminal_result_attribute = maildrop
352 # This feature is available with Postfix 2.4 or later.
353 # .IP "\fBleaf_result_attribute (default: empty)\fR"
354 # When one or more special result attributes are found in a non-terminal
355 # (see above) LDAP entry, leaf result attributes are excluded from the
356 # expansion of that entry. This is useful when expanding groups and the
357 # desired mail address attribute(s) of the member objects obtained via
358 # DN or URI recursion are also present in the group object. To only
359 # return the attribute values from the leaf objects and not the
360 # containing group, add the attribute to the leaf_result_attribute list,
361 # and not the result_attribute list, which is always expanded. Note,
362 # the default value of "result_attribute" is not empty, you may want to
363 # set it explicitly empty when using "leaf_result_attribute" to expand
364 # the group to a list of member DN addresses. If groups have both
365 # member DN references AND attributes that hold multiple string valued
366 # rfc822 addresses, then the string attributes go in "result_attribute".
367 # The attributes that represent the email addresses of objects
368 # referenced via a DN (or LDAP URI) go in "leaf_result_attribute".
371 # result_attribute = memberaddr
372 # special_result_attribute = memberdn
373 # terminal_result_attribute = maildrop
374 # leaf_result_attribute = mail
377 # This feature is available with Postfix 2.4 or later.
378 # .IP "\fBscope (default: sub)\fR"
379 # The LDAP search scope: \fBsub\fR, \fBbase\fR, or \fBone\fR.
380 # These translate into LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE,
381 # and LDAP_SCOPE_ONELEVEL.
382 # .IP "\fBbind (default: yes)\fR"
383 # Whether or not to bind to the LDAP server. Newer LDAP
384 # implementations don't require clients to bind, which saves
391 # If you do need to bind, you might consider configuring
392 # Postfix to connect to the local machine on a port that's
393 # an SSL tunnel to your LDAP server. If your LDAP server
394 # doesn't natively support SSL, put a tunnel (wrapper, proxy,
395 # whatever you want to call it) on that system too. This
396 # should prevent the password from traversing the network in
398 # .IP "\fBbind_dn (default: empty)\fR"
399 # If you do have to bind, do it with this distinguished name. Example:
402 # bind_dn = uid=postfix, dc=your, dc=com
404 # .IP "\fBbind_pw (default: empty)\fR"
405 # The password for the distinguished name above. If you have
406 # to use this, you probably want to make the map configuration
407 # file readable only by the Postfix user. When using the
408 # obsolete ldap:ldapsource syntax, with map parameters in
409 # main.cf, it is not possible to securely store the bind
410 # password. This is because main.cf needs to be world readable
411 # to allow local accounts to submit mail via the sendmail
415 # bind_pw = postfixpw
417 # .IP "\fBcache (IGNORED with a warning)\fR"
418 # .IP "\fBcache_expiry (IGNORED with a warning)\fR"
419 # .IP "\fBcache_size (IGNORED with a warning)\fR"
420 # The above parameters are NO LONGER SUPPORTED by Postfix.
421 # Cache support has been dropped from OpenLDAP as of release
423 # .IP "\fBrecursion_limit (default: 1000)\fR"
424 # A limit on the nesting depth of DN and URL special result
425 # attribute evaluation. The limit must be a non-zero positive
427 # .IP "\fBexpansion_limit (default: 0)\fR"
428 # A limit on the total number of result elements returned
429 # (as a comma separated list) by a lookup against the map.
430 # A setting of zero disables the limit. Lookups fail with a
431 # temporary error if the limit is exceeded. Setting the
432 # limit to 1 ensures that lookups do not return multiple
434 # .IP "\fBsize_limit (default: $expansion_limit)\fR"
435 # A limit on the number of LDAP entries returned by any single
436 # LDAP search performed as part of the lookup. A setting of
437 # 0 disables the limit. Expansion of DN and URL references
438 # involves nested LDAP queries, each of which is separately
439 # subjected to this limit.
441 # Note: even a single LDAP entry can generate multiple lookup
442 # results, via multiple result attributes and/or multi-valued
443 # result attributes. This limit caps the per search resource
444 # utilization on the LDAP server, not the final multiplicity
445 # of the lookup result. It is analogous to the "-z" option
447 # .IP "\fBdereference (default: 0)\fR"
448 # When to dereference LDAP aliases. (Note that this has
449 # nothing do with Postfix aliases.) The permitted values are
450 # those legal for the OpenLDAP/UM LDAP implementations:
457 # when locating the base object for the search
462 # See ldap.h or the ldap_open(3) or ldapsearch(1) man pages
463 # for more information. And if you're using an LDAP package
464 # that has other possible values, please bring it to the
465 # attention of the postfix-users@postfix.org mailing list.
466 # .IP "\fBchase_referrals (default: 0)\fR"
467 # Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP version
469 # .IP "\fBversion (default: 2)\fR"
470 # Specifies the LDAP protocol version to use.
471 # .IP "\fBdebuglevel (default: 0)\fR"
472 # What level to set for debugging in the OpenLDAP libraries.
473 # LDAP SSL AND STARTTLS PARAMETERS
476 # If you're using the OpenLDAP libraries compiled with SSL
477 # support, Postfix can connect to LDAP SSL servers and can
478 # issue the STARTTLS command.
480 # LDAP SSL service can be requested by using a LDAP SSL URL
481 # in the server_host parameter:
484 # server_host = ldaps://ldap.example.com:636
487 # STARTTLS can be turned on with the start_tls parameter:
493 # Both forms require LDAP protocol version 3, which has to be set
500 # If any of the Postfix programs querying the map is configured in
501 # master.cf to run chrooted, all the certificates and keys involved
502 # have to be copied to the chroot jail. Of course, the private keys
503 # should only be readable by the user "postfix".
505 # The following parameters are relevant to LDAP SSL and STARTTLS:
506 # .IP "\fBstart_tls (default: no)\fR"
507 # Whether or not to issue STARTTLS upon connection to the
508 # server. Don't set this with LDAP SSL (the SSL session is setup
509 # automatically when the TCP connection is opened).
510 # .IP "\fBtls_ca_cert_dir (No default; set either this or tls_ca_cert_file)\fR"
511 # Directory containing X509 Certificate Authority certificates
512 # in PEM format which are to be recognized by the client in
513 # SSL/TLS connections. The files each contain one CA certificate.
514 # The files are looked up by the CA subject name hash value,
515 # which must hence be available. If more than one CA certificate
516 # with the same name hash value exist, the extension must be
517 # different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is
518 # performed in the ordering of the extension number, regardless
519 # of other properties of the certificates. Use the c_rehash
520 # utility (from the OpenSSL distribution) to create the
522 # .IP "\fBtls_ca_cert_file (No default; set either this or tls_ca_cert_dir)\fR"
523 # File containing the X509 Certificate Authority certificates
524 # in PEM format which are to be recognized by the client in
525 # SSL/TLS connections. This setting takes precedence over
527 # .IP "\fBtls_cert (No default; you must set this)\fR"
528 # File containing client's X509 certificate to be used by
529 # the client in SSL/ TLS connections.
530 # .IP "\fBtls_key (No default; you must set this)\fR"
531 # File containing the private key corresponding to the above
533 # .IP "\fBtls_require_cert (default: no)\fR"
534 # Whether or not to request server's X509 certificate and
535 # check its validity when establishing SSL/TLS connections.
536 # The supported values are \fBno\fR and \fByes\fR.
538 # With \fBno\fR, the server certificate trust chain is not checked,
539 # but with OpenLDAP prior to 2.1.13, the name in the server
540 # certificate must still match the LDAP server name. With OpenLDAP
541 # 2.0.0 to 2.0.11 the server name is not necessarily what you
542 # specified, rather it is determined (by reverse lookup) from the
543 # IP address of the LDAP server connection. With OpenLDAP prior to
544 # 2.0.13, subjectAlternativeName extensions in the LDAP server
545 # certificate are ignored: the server name must match the subject
546 # CommonName. The \fBno\fR setting corresponds to the \fBnever\fR
547 # value of \fBTLS_REQCERT\fR in LDAP client configuration files.
549 # Don't use TLS with OpenLDAP 2.0.x (and especially with x <= 11)
550 # if you can avoid it.
552 # With \fByes\fR, the server certificate must be issued by a trusted
553 # CA, and not be expired. The LDAP server name must match one of the
554 # name(s) found in the certificate (see above for OpenLDAP library
555 # version dependent behavior). The \fByes\fR setting corresponds to the
556 # \fBdemand\fR value of \fBTLS_REQCERT\fR in LDAP client configuration
559 # The "try" and "never" values of \fBTLS_REQCERT\fR have no equivalents
560 # here. They are not available with OpenLDAP 2.0, and in any case have
561 # questionable security properties. Either you want TLS verified LDAP
562 # connections, or you don't.
564 # The \fByes\fR value only works correctly with Postfix 2.5 and later,
565 # or with OpenLDAP 2.0. Earlier Postfix releases or later OpenLDAP
566 # releases don't work together with this setting. Support for LDAP
567 # over TLS was added to Postfix based on the OpenLDAP 2.0 API.
568 # .IP "\fBtls_random_file (No default)\fR"
569 # Path of a file to obtain random bits from when /dev/[u]random
570 # is not available, to be used by the client in SSL/TLS
572 # .IP "\fBtls_cipher_suite (No default)\fR"
573 # Cipher suite to use in SSL/TLS negotiations.
577 # Here's a basic example for using LDAP to look up local(8)
579 # Assume that in main.cf, you have:
582 # alias_maps = hash:/etc/aliases,
583 # ldap:/etc/postfix/ldap-aliases.cf
586 # and in ldap:/etc/postfix/ldap-aliases.cf you have:
589 # server_host = ldap.example.com
590 # search_base = dc=example, dc=com
593 # Upon receiving mail for a local address "ldapuser" that
594 # isn't found in the /etc/aliases database, Postfix will
595 # search the LDAP server listening at port 389 on ldap.example.com.
596 # It will bind anonymously, search for any directory entries
597 # whose mailacceptinggeneralid attribute is "ldapuser", read
598 # the "maildrop" attributes of those found, and build a list
599 # of their maildrops, which will be treated as RFC822 addresses
600 # to which the message will be delivered.
602 # postmap(1), Postfix lookup table manager
603 # postconf(5), configuration parameters
604 # mysql_table(5), MySQL lookup tables
605 # pgsql_table(5), PostgreSQL lookup tables
609 # Use "\fBpostconf readme_directory\fR" or
610 # "\fBpostconf html_directory\fR" to locate this information.
613 # DATABASE_README, Postfix lookup table overview
614 # LDAP_README, Postfix LDAP client guide
618 # The Secure Mailer license must be distributed with this software.