1
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2
"http://www.w3.org/TR/html4/loose.dtd">
4
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
5
<title> Postfix manual - ldap_table(5) </title>
7
LDAP_TABLE(5) LDAP_TABLE(5)
10
ldap_table - Postfix LDAP client configuration
13
<b>postmap -q "</b><i>string</i><b>" <a href="ldap_table.5.html">ldap</a>:/etc/postfix/filename</b>
15
<b>postmap -q - <a href="ldap_table.5.html">ldap</a>:/etc/postfix/</b><i>filename</i> <<i>inputfile</i>
18
The Postfix mail system uses optional tables for address
19
rewriting or mail routing. These tables are usually in <b>dbm</b>
22
Alternatively, lookup tables can be specified as LDAP
25
In order to use LDAP lookups, define an LDAP source as a
26
lookup table in main.cf, for example:
27
<a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
29
The file /etc/postfix/ldap-aliases.cf has the same format
30
as the Postfix main.cf file, and can specify the parame-
31
ters described below. An example is given at the end of
34
This configuration method is available with Postfix ver-
35
sion 2.1 and later. See the section "BACKWARDS COMPATI-
36
BILITY" below for older Postfix versions.
38
For details about LDAP SSL and STARTTLS, see the section
39
on SSL and STARTTLS below.
41
<b>BACKWARDS COMPATIBILITY</b>
42
For backwards compatibility with Postfix version 2.0 and
43
earlier, LDAP parameters can also be defined in main.cf.
44
Specify as LDAP source a name that doesn't begin with a
45
slash or a dot. The LDAP parameters will then be accessi-
46
ble as the name you've given the source in its definition,
47
an underscore, and the name of the parameter. For exam-
48
ple, if the map is specified as "<a href="ldap_table.5.html">ldap</a>:<i>ldapsource</i>", the
49
"server_host" parameter below would be defined in main.cf
50
as "<i>ldapsource</i>_server_host".
52
Note: with this form, the passwords for the LDAP sources
53
are written in main.cf, which is normally world-readable.
54
Support for this form will be removed in a future Postfix
57
<b>LIST MEMBERSHIP</b>
58
When using LDAP to store lists such as $<a href="postconf.5.html#mynetworks">mynetworks</a>,
59
$<a href="postconf.5.html#mydestination">mydestination</a>, $<a href="postconf.5.html#relay_domains">relay_domains</a>, $<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a>,
60
etc., it is important to understand that the table must
61
store each list member as a separate key. The table lookup
62
verifies the *existence* of the key. See "Postfix lists
63
versus tables" in the <a href="DATABASE_README.html">DATABASE_README</a> document for a dis-
66
Do NOT create tables that return the full list of domains
67
in $<a href="postconf.5.html#mydestination">mydestination</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP addresses
68
in $<a href="postconf.5.html#mynetworks">mynetworks</a>.
70
DO create tables with each matching item as a key and with
71
an arbitrary value. With LDAP databases it is not uncommon
72
to return the key itself.
74
For example, NEVER do this in a map defining $<a href="postconf.5.html#mydestination">mydestina</a>-
75
<a href="postconf.5.html#mydestination">tion</a>:
76
query_filter = domain=*
77
result_attribute = domain
80
query_filter = domain=%s
81
result_attribute = domain
83
<b>GENERAL LDAP PARAMETERS</b>
84
In the text below, default values are given in parenthe-
85
ses. Note: don't use quotes in these variables; at least,
86
not until the Postfix configuration routines understand
87
how to deal with quoted strings.
89
<b>server_host (default: localhost)</b>
90
The name of the host running the LDAP server, e.g.
91
server_host = ldap.your.com
93
Depending on the LDAP client library you're using,
94
it should be possible to specify multiple servers
95
here, with the library trying them in order should
96
the first one fail. It should also be possible to
97
give each server in the list a different port
98
(overriding <b>server_port</b> below), by naming them like
99
server_host = ldap.your.com:1444
101
With OpenLDAP, a (list of) LDAP URLs can be used to
102
specify both the hostname(s) and the port(s):
103
server_host = <a href="ldap_table.5.html">ldap</a>://ldap.your.com:1444
105
All LDAP URLs accepted by the OpenLDAP library are
106
supported, including connections over UNIX domain
107
sockets, and LDAP SSL (the last one provided that
108
OpenLDAP was compiled with support for SSL):
109
server_host = ldapi://%2Fsome%2Fpath
110
server_host = ldaps://ldap.your.com:636
112
<b>server_port (default: 389)</b>
113
The port the LDAP server listens on, e.g.
116
<b>search_base (No default; you must configure this)</b>
117
The <a href="http://www.faqs.org/rfcs/rfc2253.html">RFC2253</a> base DN at which to conduct the search,
119
search_base = dc=your, dc=com
121
<b>timeout (default: 10 seconds)</b>
122
The number of seconds a search can take before tim-
126
<b>query_filter (default: mailacceptinggeneralid=%s)</b>
127
The <a href="http://www.faqs.org/rfcs/rfc2254.html">RFC2254</a> filter used to search the directory,
128
where <b>%s</b> is a substitute for the address Postfix is
129
trying to resolve, e.g.
130
query_filter = (&(mail=%s)(paid_up=true))
132
This parameter supports the following '%' expan-
135
<b>%s</b> This is replaced by the input key. <a href="http://www.faqs.org/rfcs/rfc2254.html">RFC 2254</a>
136
quoting is used to make sure that the input
137
key does not add unexpected metacharacters.
139
<b>%u</b> When the input key is an address of the form
140
user@domain, <b>%u</b> is replaced by the (RFC
141
2254) quoted local part of the address. If
142
no domain is specified, <b>%u</b> is replaced by
143
the entire search string.
145
<b>%d</b> When the input key is an address of the form
146
user@domain, <b>%d</b> is replaced by the (RFC
147
2254) quoted domain part of the address.
148
When the input key has no domain qualifier,
149
<b>%d</b> is replaced by the entire search string.
151
The "domain" parameter described below limits the
152
input keys to addresses in matching domains. When
153
the "domain" parameter is non-empty, LDAP queries
154
for unqualified addresses or addresses in non-
155
matching domains are suppressed and return no
158
NOTE: DO NOT put quotes around the query filter.
160
<b>result_filter (default: %s</b>)
161
Format template applied to result attributes. Sup-
162
ports the same expansions as the query_filter, and
163
can be easily used to append (or prepend) text.
164
This parameter supports the following '%' expan-
167
<b>%s</b> This is replaced by the value of the result
170
<b>%u</b> When the result attribute is an address of
171
the form user@domain, <b>%u</b> is replaced local
172
part of the address, if the result attribute
173
is unqualified, <b>%u</b> is replaced by the entire
176
<b>%d</b> When a result attribute is an address of the
177
form user@domain, <b>%d</b> is replaced by the
178
domain part of the attribute value. If an
179
attribute value is unqualified <b>%d</b> is
180
replaced by the entire attribute value.
182
For example, using "result_filter = <a href="smtp.8.html">smtp</a>:[%s]"
183
allows one to use a mailHost attribute as the basis
184
of a <a href="transport.5.html">transport(5)</a> table. After applying the result
185
filter, multiple values are concatenated as comma
186
separated strings. The expansion_limit and
187
size_limit parameters explained below allow one to
188
restrict the number of values in the result, which
189
is especially useful for maps that should return a
192
The default value <b>%s</b> specifies that each attribute
193
value should be used as is.
195
NOTE: DO NOT put quotes around the result filter!
197
<b>domain (default: no domain list)</b>
198
This is a list of domain names, paths to files, or
199
dictionaries. When specified, only fully qualified
200
search keys with a *non-empty* localpart and a
201
matching domain are eligible for lookup: 'user'
202
lookups, bare domain lookups and "@domain" lookups
203
are not performed. This can significantly reduce
204
the query load on the LDAP server.
205
domain = postfix.org, hash:/etc/postfix/search-
208
It is best not to use LDAP to store the domains
209
eligible for LDAP lookups.
211
NOTE: DO NOT define this parameter for <a href="local.8.html">local(8)</a>
214
<b>result_attribute (default: maildrop)</b>
215
The attribute(s) Postfix will read from any direc-
216
tory entries returned by the lookup, to be resolved
218
result_attribute = mailbox,maildrop
220
<b>special_result_attribute (No default)</b>
221
The attribute(s) of directory entries that can con-
222
tain DNs or URLs. If found, a recursive subsequent
223
search is done using their values.
224
special_result_attribute = member
226
DN recursion retrieves the same result_attributes
227
as the main query, including the special attributes
228
for further recursion. URI processing retrieves
229
only those attributes that are included in the URI
230
definition and are *also* listed in
231
"result_attribute". If the URI lists any of the
232
map's special result attributes, these are also
233
retrieved and used recursively.
235
<b>scope (default: sub)</b>
236
The LDAP search scope: <b>sub</b>, <b>base</b>, or <b>one</b>. These
237
translate into LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE,
238
and LDAP_SCOPE_ONELEVEL.
240
<b>bind (default: yes)</b>
241
Whether or not to bind to the LDAP server. Newer
242
LDAP implementations don't require clients to bind,
243
which saves time. Example:
246
If you do need to bind, you might consider config-
247
uring Postfix to connect to the local machine on a
248
port that's an SSL tunnel to your LDAP server. If
249
your LDAP server doesn't natively support SSL, put
250
a tunnel (wrapper, proxy, whatever you want to call
251
it) on that system too. This should prevent the
252
password from traversing the network in the clear.
254
<b>bind_dn (default: empty)</b>
255
If you do have to bind, do it with this distin-
256
guished name. Example:
257
bind_dn = uid=postfix, dc=your, dc=com
259
<b>bind_pw (default: empty)</b>
260
The password for the distinguished name above. If
261
you have to use this, you probably want to make the
262
map configuration file readable only by the Postfix
263
user. When using the obsolete <a href="ldap_table.5.html">ldap</a>:ldapsource syn-
264
tax, with map parameters in main.cf, it is not pos-
265
sible to securely store the bind password. This is
266
because main.cf needs to be world readable to allow
267
local accounts to submit mail via the sendmail com-
271
<b>cache (IGNORED with a warning)</b>
273
<b>cache_expiry (IGNORED with a warning)</b>
275
<b>cache_size (IGNORED with a warning)</b>
276
The above parameters are NO LONGER SUPPORTED by
277
Postfix. Cache support has been dropped from
278
OpenLDAP as of release 2.1.13.
280
<b>recursion_limit (default: 1000)</b>
281
A limit on the nesting depth of DN and URL special
282
result attribute evaluation. The limit must be a
283
non-zero positive number.
285
<b>expansion_limit (default: 0)</b>
286
A limit on the total number of result elements
287
returned (as a comma separated list) by a lookup
288
against the map. A setting of zero disables the
289
limit. Lookups fail with a temporary error if the
290
limit is exceeded. Setting the limit to 1 ensures
291
that lookups do not return multiple values.
293
<b>size_limit (default: $expansion_limit)</b>
294
A limit on the number of LDAP entries returned by
295
any single LDAP query performed as part of the
296
lookup. A setting of 0 disables the limit. Expan-
297
sion of DN and URL references involves nested LDAP
298
queries, each of which is separately subjected to
301
Note: even a single LDAP entry can generate multi-
302
ple lookup results, via multiple result attributes
303
and/or multi-valued result attributes. This limit
304
caps the per query resource utilization on the LDAP
305
server, not the final multiplicity of the lookup
306
result. It is analogous to the "-z" option of
309
<b>dereference (default: 0)</b>
310
When to dereference LDAP aliases. (Note that this
311
has nothing do with Postfix aliases.) The permitted
312
values are those legal for the OpenLDAP/UM LDAP
319
2 when locating the base object for the search
323
See ldap.h or the ldap_open(3) or ldapsearch(1) man
324
pages for more information. And if you're using an
325
LDAP package that has other possible values, please
326
bring it to the attention of the postfix-
327
users@postfix.org mailing list.
329
<b>chase_referrals (default: 0)</b>
330
Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP
333
<b>version (default: 2)</b>
334
Specifies the LDAP protocol version to use.
336
<b>debuglevel (default: 0)</b>
337
What level to set for debugging in the OpenLDAP
340
<b>LDAP SSL AND STARTTLS PARAMETERS</b>
341
If you're using the OpenLDAP libraries compiled with SSL
342
support, Postfix can connect to LDAP SSL servers and can
343
issue the STARTTLS command.
345
LDAP SSL service can be requested by using a LDAP SSL URL
346
in the server_host parameter:
347
server_host = ldaps://ldap.your.com:636
349
STARTTLS can be turned on with the start_tls parameter:
352
Both forms require LDAP protocol version 3, which has to
353
be set explicitly with:
356
If any of the Postfix programs querying the map is config-
357
ured in master.cf to run chrooted, all the certificates
358
and keys involved have to be copied to the chroot jail. Of
359
course, the private keys should only be readable by the
362
The following parameters are relevant to LDAP SSL and
365
<b>start_tls (default: no)</b>
366
Whether or not to issue STARTTLS upon connection to
367
the server. Don't set this with LDAP SSL (the SSL
368
session is setup automatically when the TCP connec-
371
<b>tls_ca_cert_dir (No default; set either this or</b>
372
<b>tls_ca_cert_file)</b>
373
Directory containing X509 Certificate Authority
374
certificates in PEM format which are to be recog-
375
nized by the client in SSL/TLS connections. The
376
files each contain one CA certificate. The files
377
are looked up by the CA subject name hash value,
378
which must hence be available. If more than one CA
379
certificate with the same name hash value exist,
380
the extension must be different (e.g. 9d66eef0.0,
381
9d66eef0.1 etc). The search is performed in the
382
ordering of the extension number, regardless of
383
other properties of the certificates. Use the
384
c_rehash utility (from the OpenSSL distribution) to
385
create the necessary links.
387
<b>tls_ca_cert_file (No default; set either this or</b>
388
<b>tls_ca_cert_dir)</b>
389
File containing the X509 Certificate Authority cer-
390
tificates in PEM format which are to be recognized
391
by the client in SSL/TLS connections. This setting
392
takes precedence over tls_ca_cert_dir.
394
<b>tls_cert (No default; you must set this)</b>
395
File containing client's X509 certificate to be
396
used by the client in SSL/ TLS connections.
398
<b>tls_key (No default; you must set this)</b>
399
File containing the private key corresponding to
402
<b>tls_require_cert (default: no)</b>
403
Whether or not to request server's X509 certificate
404
and check its validity when establishing SSL/TLS
407
<b>tls_random_file (No default)</b>
408
Path of a file to obtain random bits from when
409
/dev/[u]random is not available, to be used by the
410
client in SSL/TLS connections.
412
<b>tls_cipher_suite (No default)</b>
413
Cipher suite to use in SSL/TLS negotiations.
416
Here's a basic example for using LDAP to look up <a href="local.8.html">local(8)</a>
417
aliases. Assume that in main.cf, you have:
418
<a href="postconf.5.html#alias_maps">alias_maps</a> = hash:/etc/aliases,
419
<a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
421
and in <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf you have:
422
server_host = ldap.my.com
423
search_base = dc=my, dc=com
425
Upon receiving mail for a local address "ldapuser" that
426
isn't found in the /etc/aliases database, Postfix will
427
search the LDAP server listening at port 389 on
428
ldap.my.com. It will bind anonymously, search for any
429
directory entries whose mailacceptinggeneralid attribute
430
is "ldapuser", read the "maildrop" attributes of those
431
found, and build a list of their maildrops, which will be
432
treated as <a href="http://www.faqs.org/rfcs/rfc822.html">RFC822</a> addresses to which the message will be
436
<a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
437
<a href="postconf.5.html">postconf(5)</a>, configuration parameters
438
<a href="mysql_table.5.html">mysql_table(5)</a>, MySQL lookup tables
439
<a href="pgsql_table.5.html">pgsql_table(5)</a>, PostgreSQL lookup tables
442
<a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
443
<a href="LDAP_README.html">LDAP_README</a>, Postfix LDAP client guide
446
The Secure Mailer license must be distributed with this
450
Carsten Hoeger, Hery Rakotoarisoa, John Hensley, Keith
451
Stevenson, LaMont Jones, Liviu Daia, Manuel Guesdon, Mike
452
Mattice, Prabhat K Singh, Sami Haahtinen, Samuel Tardieu,
453
Victor Duchovni, and many others.
456
</pre> </body> </html>
added
removed
html/ldap_table.5.html
