10
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>
13
<b>postmap -q "</b><i>string</i><b>" <a href="ldap_table.5.html">ldap</a>:/etc/postfix/</b><i>filename</i>
15
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 <a href="postconf.5.html">main.cf</a>, for example:
18
The Postfix mail system uses optional tables for address rewriting or
19
mail routing. These tables are usually in <b>dbm</b> or <b>db</b> format.
21
Alternatively, lookup tables can be specified as LDAP databases.
23
In order to use LDAP lookups, define an LDAP source as a lookup table
24
in <a href="postconf.5.html">main.cf</a>, for example:
28
26
<a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
30
The file /etc/postfix/ldap-aliases.cf has the same format
31
as the Postfix <a href="postconf.5.html">main.cf</a> file, and can specify the parame-
32
ters described below. An example is given at the end of
35
This configuration method is available with Postfix ver-
36
sion 2.1 and later. See the section "BACKWARDS COMPATI-
37
BILITY" below for older Postfix versions.
39
For details about LDAP SSL and STARTTLS, see the section
40
on SSL and STARTTLS below.
28
The file /etc/postfix/ldap-aliases.cf has the same format as the Post-
29
fix <a href="postconf.5.html">main.cf</a> file, and can specify the parameters described below. An
30
example is given at the end of this manual.
32
This configuration method is available with Postfix version 2.1 and
33
later. See the section "BACKWARDS COMPATIBILITY" below for older Post-
36
For details about LDAP SSL and STARTTLS, see the section on SSL and
42
39
<b>BACKWARDS COMPATIBILITY</b>
43
For backwards compatibility with Postfix version 2.0 and
44
earlier, LDAP parameters can also be defined in <a href="postconf.5.html">main.cf</a>.
45
Specify as LDAP source a name that doesn't begin with a
46
slash or a dot. The LDAP parameters will then be accessi-
47
ble as the name you've given the source in its definition,
48
an underscore, and the name of the parameter. For exam-
49
ple, if the map is specified as "<a href="ldap_table.5.html">ldap</a>:<i>ldapsource</i>", the
50
"server_host" parameter below would be defined in <a href="postconf.5.html">main.cf</a>
51
as "<i>ldapsource</i>_server_host".
53
Note: with this form, the passwords for the LDAP sources
54
are written in <a href="postconf.5.html">main.cf</a>, which is normally world-readable.
55
Support for this form will be removed in a future Postfix
58
For backwards compatibility with the pre 2.2 LDAP clients,
59
<b>result_filter</b> can for now be used instead of <b>result_for-</b>
60
<b>mat</b>, when the latter parameter is not also set. The new
61
name better reflects the function of the parameter. This
62
compatibility interface may be removed in a future
40
For backwards compatibility with Postfix version 2.0 and earlier, LDAP
41
parameters can also be defined in <a href="postconf.5.html">main.cf</a>. Specify as LDAP source a
42
name that doesn't begin with a slash or a dot. The LDAP parameters
43
will then be accessible as the name you've given the source in its def-
44
inition, an underscore, and the name of the parameter. For example, if
45
the map is specified as "<a href="ldap_table.5.html">ldap</a>:<i>ldapsource</i>", the "server_host" parameter
46
below would be defined in <a href="postconf.5.html">main.cf</a> as "<i>ldapsource</i>_server_host".
48
Note: with this form, the passwords for the LDAP sources are written in
49
<a href="postconf.5.html">main.cf</a>, which is normally world-readable. Support for this form will
50
be removed in a future Postfix version.
52
For backwards compatibility with the pre 2.2 LDAP clients, <b>result_fil-</b>
53
<b>ter</b> can for now be used instead of <b>result_format</b>, when the latter
54
parameter is not also set. The new name better reflects the function
55
of the parameter. This compatibility interface may be removed in a
65
58
<b>LIST MEMBERSHIP</b>
66
When using LDAP to store lists such as $<a href="postconf.5.html#mynetworks">mynetworks</a>,
67
$<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>,
68
etc., it is important to understand that the table must
69
store each list member as a separate key. The table lookup
70
verifies the *existence* of the key. See "Postfix lists
71
versus tables" in the <a href="DATABASE_README.html">DATABASE_README</a> document for a dis-
74
Do NOT create tables that return the full list of domains
75
in $<a href="postconf.5.html#mydestination">mydestination</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP addresses
76
in $<a href="postconf.5.html#mynetworks">mynetworks</a>.
78
DO create tables with each matching item as a key and with
79
an arbitrary value. With LDAP databases it is not uncommon
80
to return the key itself.
82
For example, NEVER do this in a map defining $<a href="postconf.5.html#mydestination">mydestina</a>-
83
<a href="postconf.5.html#mydestination">tion</a>:
59
When using LDAP to store lists such as $<a href="postconf.5.html#mynetworks">mynetworks</a>, $<a href="postconf.5.html#mydestination">mydestination</a>,
60
$<a href="postconf.5.html#relay_domains">relay_domains</a>, $<a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a>, etc., it is important to under-
61
stand that the table must store each list member as a separate key. The
62
table lookup 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 discussion.
65
Do NOT create tables that return the full list of domains in $<a href="postconf.5.html#mydestination">mydesti</a>-
66
<a href="postconf.5.html#mydestination">nation</a> or $<a href="postconf.5.html#relay_domains">relay_domains</a> etc., or IP addresses in $<a href="postconf.5.html#mynetworks">mynetworks</a>.
68
DO create tables with each matching item as a key and with an arbitrary
69
value. With LDAP databases it is not uncommon to return the key itself.
71
For example, NEVER do this in a map defining $<a href="postconf.5.html#mydestination">mydestination</a>:
85
73
query_filter = domain=*
86
74
result_attribute = domain
130
116
server_port = 778
132
118
<b>timeout (default: 10 seconds)</b>
133
The number of seconds a search can take before tim-
119
The number of seconds a search can take before timing out, e.g.
138
123
<b>search_base (No default; you must configure this)</b>
139
The <a href="http://tools.ietf.org/html/rfc2253">RFC2253</a> base DN at which to conduct the search,
124
The <a href="http://tools.ietf.org/html/rfc2253">RFC2253</a> base DN at which to conduct the search, e.g.
142
126
search_base = dc=your, dc=com
144
With Postfix 2.2 and later this parameter supports
145
the following '%' expansions:
128
With Postfix 2.2 and later this parameter supports the following
147
131
<b>%%</b> This is replaced by a literal '%' character.
149
<b>%s</b> This is replaced by the input key. <a href="http://tools.ietf.org/html/rfc2253">RFC 2253</a>
150
quoting is used to make sure that the input
151
key does not add unexpected metacharacters.
153
<b>%u</b> When the input key is an address of the form
154
user@domain, <b>%u</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2253">RFC</a>
155
<a href="http://tools.ietf.org/html/rfc2253">2253</a>) quoted local part of the address.
156
Otherwise, <b>%u</b> is replaced by the entire
157
search string. If the localpart is empty,
158
the search is suppressed and returns no
161
<b>%d</b> When the input key is an address of the form
162
user@domain, <b>%d</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2253">RFC</a>
163
<a href="http://tools.ietf.org/html/rfc2253">2253</a>) quoted domain part of the address.
164
Otherwise, the search is suppressed and
167
<b>%[SUD]</b> For the <b>search_base</b> parameter, the upper-
168
case equivalents of the above expansions
169
behave identically to their lower-case
170
counter-parts. With the <b>result_format</b> param-
171
eter (previously called <b>result_filter</b> see
172
the COMPATIBILITY section and below), they
173
expand to the corresponding components of
174
input key rather than the result value.
176
<b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by
177
the corresponding most significant component
178
of the input key's domain. If the input key
179
is <i>user@mail.example.com</i>, then %1 is <b>com</b>, %2
180
is <b>example</b> and %3 is <b>mail</b>. If the input key
181
is unqualified or does not have enough
182
domain components to satisfy all the speci-
183
fied patterns, the search is suppressed and
133
<b>%s</b> This is replaced by the input key. <a href="http://tools.ietf.org/html/rfc2253">RFC 2253</a> quoting is
134
used to make sure that the input key does not add unex-
135
pected metacharacters.
137
<b>%u</b> When the input key is an address of the form user@domain,
138
<b>%u</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2253">RFC 2253</a>) quoted local part of the
139
address. Otherwise, <b>%u</b> is replaced by the entire search
140
string. If the localpart is empty, the search is sup-
141
pressed and returns no results.
143
<b>%d</b> When the input key is an address of the form user@domain,
144
<b>%d</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2253">RFC 2253</a>) quoted domain part of
145
the address. Otherwise, the search is suppressed and
148
<b>%[SUD]</b> For the <b>search_base</b> parameter, the upper-case equivalents
149
of the above expansions behave identically to their
150
lower-case counter-parts. With the <b>result_format</b> parame-
151
ter (previously called <b>result_filter</b> see the COMPATIBIL-
152
ITY section and below), they expand to the corresponding
153
components of input key rather than the result value.
155
<b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by the corre-
156
sponding most significant component of the input key's
157
domain. If the input key is <i>user@mail.example.com</i>, then
158
%1 is <b>com</b>, %2 is <b>example</b> and %3 is <b>mail</b>. If the input key
159
is unqualified or does not have enough domain components
160
to satisfy all the specified patterns, the search is sup-
161
pressed and returns no results.
186
163
<b>query_filter (default: mailacceptinggeneralid=%s)</b>
187
The <a href="http://tools.ietf.org/html/rfc2254">RFC2254</a> filter used to search the directory,
188
where <b>%s</b> is a substitute for the address Postfix is
189
trying to resolve, e.g.
164
The <a href="http://tools.ietf.org/html/rfc2254">RFC2254</a> filter used to search the directory, where <b>%s</b> is a
165
substitute for the address Postfix is trying to resolve, e.g.
191
167
query_filter = (&(mail=%s)(paid_up=true))
193
This parameter supports the following '%' expan-
196
<b>%%</b> This is replaced by a literal '%' character.
197
(Postfix 2.2 and later).
199
<b>%s</b> This is replaced by the input key. <a href="http://tools.ietf.org/html/rfc2254">RFC 2254</a>
200
quoting is used to make sure that the input
201
key does not add unexpected metacharacters.
203
<b>%u</b> When the input key is an address of the form
204
user@domain, <b>%u</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2254">RFC</a>
205
<a href="http://tools.ietf.org/html/rfc2254">2254</a>) quoted local part of the address.
206
Otherwise, <b>%u</b> is replaced by the entire
207
search string. If the localpart is empty,
208
the search is suppressed and returns no
211
<b>%d</b> When the input key is an address of the form
212
user@domain, <b>%d</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2254">RFC</a>
213
<a href="http://tools.ietf.org/html/rfc2254">2254</a>) quoted domain part of the address.
214
Otherwise, the search is suppressed and
217
<b>%[SUD]</b> The upper-case equivalents of the above
218
expansions behave in the <b>query_filter</b> param-
219
eter identically to their lower-case
220
counter-parts. With the <b>result_format</b> param-
221
eter (previously called <b>result_filter</b> see
222
the COMPATIBILITY section and below), they
223
expand to the corresponding components of
224
input key rather than the result value.
226
The above %S, %U and %D expansions are
227
available with Postfix 2.2 and later.
229
<b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by
230
the corresponding most significant component
231
of the input key's domain. If the input key
232
is <i>user@mail.example.com</i>, then %1 is <b>com</b>, %2
233
is <b>example</b> and %3 is <b>mail</b>. If the input key
234
is unqualified or does not have enough
235
domain components to satisfy all the speci-
236
fied patterns, the search is suppressed and
239
The above %1, ..., %9 expansions are avail-
240
able with Postfix 2.2 and later.
242
The "domain" parameter described below limits the
243
input keys to addresses in matching domains. When
244
the "domain" parameter is non-empty, LDAP queries
245
for unqualified addresses or addresses in non-
246
matching domains are suppressed and return no
249
NOTE: DO NOT put quotes around the <b>query_filter</b>
169
This parameter supports the following '%' expansions:
171
<b>%%</b> This is replaced by a literal '%' character. (Postfix 2.2
174
<b>%s</b> This is replaced by the input key. <a href="http://tools.ietf.org/html/rfc2254">RFC 2254</a> quoting is
175
used to make sure that the input key does not add unex-
176
pected metacharacters.
178
<b>%u</b> When the input key is an address of the form user@domain,
179
<b>%u</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2254">RFC 2254</a>) quoted local part of the
180
address. Otherwise, <b>%u</b> is replaced by the entire search
181
string. If the localpart is empty, the search is sup-
182
pressed and returns no results.
184
<b>%d</b> When the input key is an address of the form user@domain,
185
<b>%d</b> is replaced by the (<a href="http://tools.ietf.org/html/rfc2254">RFC 2254</a>) quoted domain part of
186
the address. Otherwise, the search is suppressed and
189
<b>%[SUD]</b> The upper-case equivalents of the above expansions behave
190
in the <b>query_filter</b> parameter identically to their lower-
191
case counter-parts. With the <b>result_format</b> parameter
192
(previously called <b>result_filter</b> see the COMPATIBILITY
193
section and below), they expand to the corresponding com-
194
ponents of input key rather than the result value.
196
The above %S, %U and %D expansions are available with
197
Postfix 2.2 and later.
199
<b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by the corre-
200
sponding most significant component of the input key's
201
domain. If the input key is <i>user@mail.example.com</i>, then
202
%1 is <b>com</b>, %2 is <b>example</b> and %3 is <b>mail</b>. If the input key
203
is unqualified or does not have enough domain components
204
to satisfy all the specified patterns, the search is sup-
205
pressed and returns no results.
207
The above %1, ..., %9 expansions are available with Post-
210
The "domain" parameter described below limits the input keys to
211
addresses in matching domains. When the "domain" parameter is
212
non-empty, LDAP queries for unqualified addresses or addresses
213
in non-matching domains are suppressed and return no results.
215
NOTE: DO NOT put quotes around the <b>query_filter</b> parameter.
252
217
<b>result_format (default: %s</b>)
253
Called <b>result_filter</b> in Postfix releases prior to
254
2.2. Format template applied to result attributes.
255
Most commonly used to append (or prepend) text to
256
the result. This parameter supports the following
259
<b>%%</b> This is replaced by a literal '%' character.
260
(Postfix 2.2 and later).
262
<b>%s</b> This is replaced by the value of the result
263
attribute. When result is empty it is
266
<b>%u</b> When the result attribute value is an
267
address of the form user@domain, <b>%u</b> is
268
replaced by the local part of the address.
269
When the result has an empty localpart it is
272
<b>%d</b> When a result attribute value is an address
273
of the form user@domain, <b>%d</b> is replaced by
274
the domain part of the attribute value. When
275
the result is unqualified it is skipped.
218
Called <b>result_filter</b> in Postfix releases prior to 2.2. Format
219
template applied to result attributes. Most commonly used to
220
append (or prepend) text to the result. This parameter supports
221
the following '%' expansions:
223
<b>%%</b> This is replaced by a literal '%' character. (Postfix 2.2
226
<b>%s</b> This is replaced by the value of the result attribute.
227
When result is empty it is skipped.
229
<b>%u</b> When the result attribute value is an address of the form
230
user@domain, <b>%u</b> is replaced by the local part of the
231
address. When the result has an empty localpart it is
234
<b>%d</b> When a result attribute value is an address of the form
235
user@domain, <b>%d</b> is replaced by the domain part of the
236
attribute value. When the result is unqualified it is
278
The upper-case and decimal digit expansions
279
interpolate the parts of the input key
280
rather than the result. Their behavior is
281
identical to that described with <b>query_fil-</b>
282
<b>ter</b>, and in fact because the input key is
283
known in advance, lookups whose key does not
284
contain all the information specified in the
285
result template are suppressed and return no
288
The above %S, %U, %D and %1, ..., %9 expan-
289
sions are available with Postfix 2.2 and
292
For example, using "result_format = <a href="smtp.8.html">smtp</a>:[%s]"
293
allows one to use a mailHost attribute as the basis
294
of a <a href="transport.5.html">transport(5)</a> table. After applying the result
295
format, multiple values are concatenated as comma
296
separated strings. The expansion_limit and
297
size_limit parameters explained below allow one to
298
restrict the number of values in the result, which
299
is especially useful for maps that should return a
302
The default value <b>%s</b> specifies that each attribute
303
value should be used as is.
305
This parameter was called <b>result_filter</b> in Postfix
306
releases prior to 2.2. If no "result_format" is
307
specified, the value of "result_filter" will be
308
used instead before resorting to the default value.
309
This provides compatibility with old configuration
240
The upper-case and decimal digit expansions interpolate
241
the parts of the input key rather than the result. Their
242
behavior is identical to that described with <b>query_fil-</b>
243
<b>ter</b>, and in fact because the input key is known in
244
advance, lookups whose key does not contain all the
245
information specified in the result template are sup-
246
pressed and return no results.
248
The above %S, %U, %D and %1, ..., %9 expansions are
249
available with Postfix 2.2 and later.
251
For example, using "result_format = <a href="smtp.8.html">smtp</a>:[%s]" allows one to use
252
a mailHost attribute as the basis of a <a href="transport.5.html">transport(5)</a> table. After
253
applying the result format, multiple values are concatenated as
254
comma separated strings. The expansion_limit and size_limit
255
parameters explained below allow one to restrict the number of
256
values in the result, which is especially useful for maps that
257
should return a single value.
259
The default value <b>%s</b> specifies that each attribute value should
262
This parameter was called <b>result_filter</b> in Postfix releases
263
prior to 2.2. If no "result_format" is specified, the value of
264
"result_filter" will be used instead before resorting to the
265
default value. This provides compatibility with old configura-
312
268
NOTE: DO NOT put quotes around the result format!
314
270
<b>domain (default: no domain list)</b>
315
This is a list of domain names, paths to files, or
316
dictionaries. When specified, only fully qualified
317
search keys with a *non-empty* localpart and a
318
matching domain are eligible for lookup: 'user'
319
lookups, bare domain lookups and "@domain" lookups
320
are not performed. This can significantly reduce
321
the query load on the LDAP server.
323
domain = postfix.org, hash:/etc/postfix/searchdomains
325
It is best not to use LDAP to store the domains
326
eligible for LDAP lookups.
328
NOTE: DO NOT define this parameter for <a href="local.8.html">local(8)</a>
271
This is a list of domain names, paths to files, or dictionaries.
272
When specified, only fully qualified search keys with a *non-
273
empty* localpart and a matching domain are eligible for lookup:
274
'user' lookups, bare domain lookups and "@domain" lookups are
275
not performed. This can significantly reduce the query load on
278
domain = postfix.org, <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/searchdomains
280
It is best not to use LDAP to store the domains eligible for
283
NOTE: DO NOT define this parameter for <a href="local.8.html">local(8)</a> aliases.
331
285
This feature is available in Postfix 1.0 and later.
333
287
<b>result_attribute (default: maildrop)</b>
334
The attribute(s) Postfix will read from any direc-
335
tory entries returned by the lookup, to be resolved
288
The attribute(s) Postfix will read from any directory entries
289
returned by the lookup, to be resolved to an email address.
338
291
result_attribute = mailbox, maildrop
340
Don't rely on the default value ("maildrop"). Set
341
the result_attribute explicitly in all ldap table
342
configuration files. This is particularly relevant
343
when no result_attribute is applicable, e.g. cases
344
in which leaf_result_attribute and/or termi-
345
nal_result_attribute are used instead. The default
346
value is harmless if "maildrop" is also listed as a
347
leaf or terminal result attribute, but it is best
348
to not leave this to chance.
293
Don't rely on the default value ("maildrop"). Set the
294
result_attribute explicitly in all ldap table configuration
295
files. This is particularly relevant when no result_attribute is
296
applicable, e.g. cases in which leaf_result_attribute and/or
297
terminal_result_attribute are used instead. The default value is
298
harmless if "maildrop" is also listed as a leaf or terminal
299
result attribute, but it is best to not leave this to chance.
350
301
<b>special_result_attribute (default: empty)</b>
351
The attribute(s) of directory entries that can con-
352
tain DNs or <a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a> LDAP URLs. If found, a recur-
353
sive search is performed to retrieve the entry ref-
354
erenced by the DN, or the entries matched by the
302
The attribute(s) of directory entries that can contain DNs or
303
<a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a> LDAP URLs. If found, a recursive search is performed to
304
retrieve the entry referenced by the DN, or the entries matched
357
307
special_result_attribute = memberdn
359
DN recursion retrieves the same result_attributes
360
as the main query, including the special attributes
361
for further recursion.
309
DN recursion retrieves the same result_attributes as the main
310
query, including the special attributes for further recursion.
363
URL processing retrieves only those attributes that
364
are included in both the URL definition and as
365
result attributes (ordinary, special, leaf or ter-
366
minal) in the Postfix table definition. If the URL
367
lists any of the table's special result attributes,
368
these are retrieved and used recursively. A URL
369
that does not specify any attribute selection, is
370
equivalent (<a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a>) to a URL that selects all
371
attributes, in which case the selected attributes
372
will be the full set of result attributes in the
312
URL processing retrieves only those attributes that are included
313
in both the URL definition and as result attributes (ordinary,
314
special, leaf or terminal) in the Postfix table definition. If
315
the URL lists any of the table's special result attributes,
316
these are retrieved and used recursively. A URL that does not
317
specify any attribute selection, is equivalent (<a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a>) to a
318
URL that selects all attributes, in which case the selected
319
attributes will be the full set of result attributes in the
375
If an LDAP URL attribute-descriptor or the corre-
376
sponding Postfix LDAP table result attribute (but
377
not both) uses <a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a> sub-type options
378
("attr;option"), the attribute requested from the
379
LDAP server will include the sub-type option. In
380
all other cases, the URL attribute and the table
381
attribute must match exactly. Attributes with
382
options in both the URL and the Postfix table are
383
requested only when the options are identical. LDAP
384
attribute-descriptor options are very rarely used,
385
most LDAP users will not need to concern themselves
386
with this level of nuanced detail.
322
If an LDAP URL attribute-descriptor or the corresponding Postfix
323
LDAP table result attribute (but not both) uses <a href="http://tools.ietf.org/html/rfc2255">RFC 2255</a> sub-
324
type options ("attr;option"), the attribute requested from the
325
LDAP server will include the sub-type option. In all other
326
cases, the URL attribute and the table attribute must match
327
exactly. Attributes with options in both the URL and the Postfix
328
table are requested only when the options are identical. LDAP
329
attribute-descriptor options are very rarely used, most LDAP
330
users will not need to concern themselves with this level of
388
333
<b>terminal_result_attribute (default: empty)</b>
389
When one or more terminal result attributes are
390
found in an LDAP entry, all other result attributes
391
are ignored and only the terminal result attributes
392
are returned. This is useful for delegating expan-
393
sion of group members to a particular host, by
394
using an optional "maildrop" attribute on selected
395
groups to route the group to a specific host, where
396
the group is expanded, possibly via mailing-list
397
manager or other special processing.
334
When one or more terminal result attributes are found in an LDAP
335
entry, all other result attributes are ignored and only the ter-
336
minal result attributes are returned. This is useful for dele-
337
gating expansion of group members to a particular host, by using
338
an optional "maildrop" attribute on selected groups to route the
339
group to a specific host, where the group is expanded, possibly
340
via mailing-list manager or other special processing.
399
342
result_attribute =
400
343
terminal_result_attribute = maildrop
402
When using terminal and/or leaf result attributes,
403
the result_attribute is best set to an empty value
404
when it is not used, or else explicitly set to the
405
desired value, even if it is the default value
345
When using terminal and/or leaf result attributes, the
346
result_attribute is best set to an empty value when it is not
347
used, or else explicitly set to the desired value, even if it is
348
the default value "maildrop".
408
This feature is available with Postfix 2.4 or
350
This feature is available with Postfix 2.4 or later.
411
352
<b>leaf_result_attribute (default: empty)</b>
412
When one or more special result attributes are
413
found in a non-terminal (see above) LDAP entry,
414
leaf result attributes are excluded from the expan-
415
sion of that entry. This is useful when expanding
416
groups and the desired mail address attribute(s) of
417
the member objects obtained via DN or URI recursion
418
are also present in the group object. To only
419
return the attribute values from the leaf objects
420
and not the containing group, add the attribute to
421
the leaf_result_attribute list, and not the
422
result_attribute list, which is always expanded.
423
Note, the default value of "result_attribute" is
424
not empty, you may want to set it explicitly empty
425
when using "leaf_result_attribute" to expand the
426
group to a list of member DN addresses. If groups
427
have both member DN references AND attributes that
428
hold multiple string valued rfc822 addresses, then
429
the string attributes go in "result_attribute".
430
The attributes that represent the email addresses
431
of objects referenced via a DN (or LDAP URI) go in
353
When one or more special result attributes are found in a non-
354
terminal (see above) LDAP entry, leaf result attributes are
355
excluded from the expansion of that entry. This is useful when
356
expanding groups and the desired mail address attribute(s) of
357
the member objects obtained via DN or URI recursion are also
358
present in the group object. To only return the attribute values
359
from the leaf objects and not the containing group, add the
360
attribute to the leaf_result_attribute list, and not the
361
result_attribute list, which is always expanded. Note, the
362
default value of "result_attribute" is not empty, you may want
363
to set it explicitly empty when using "leaf_result_attribute" to
364
expand the group to a list of member DN addresses. If groups
365
have both member DN references AND attributes that hold multiple
366
string valued rfc822 addresses, then the string attributes go in
367
"result_attribute". The attributes that represent the email
368
addresses of objects referenced via a DN (or LDAP URI) go in
432
369
"leaf_result_attribute".
434
371
result_attribute = memberaddr
465
Postfix versions prior to 2.8 only support "bind =
466
no" which means don't bind, and "bind = yes" which
467
means do a SIMPLE bind. Postfix 2.8 and later also
468
supports "bind = SASL" when compiled with LDAP SASL
469
support as described in <a href="LDAP_README.html">LDAP_README</a>, it also adds
470
the synonyms "bind = none" and "bind = simple" for
471
"bind = no" and "bind = yes" respectively. See the
472
SASL section below for additional parameters avail-
473
able with "bind = sasl".
399
Postfix versions prior to 2.8 only support "bind = no" which
400
means don't bind, and "bind = yes" which means do a SIMPLE bind.
401
Postfix 2.8 and later also supports "bind = SASL" when compiled
402
with LDAP SASL support as described in <a href="LDAP_README.html">LDAP_README</a>, it also adds
403
the synonyms "bind = none" and "bind = simple" for "bind = no"
404
and "bind = yes" respectively. See the SASL section below for
405
additional parameters available with "bind = sasl".
475
If you do need to bind, you might consider config-
476
uring Postfix to connect to the local machine on a
477
port that's an SSL tunnel to your LDAP server. If
478
your LDAP server doesn't natively support SSL, put
479
a tunnel (wrapper, proxy, whatever you want to call
480
it) on that system too. This should prevent the
481
password from traversing the network in the clear.
407
If you do need to bind, you might consider configuring Postfix
408
to connect to the local machine on a port that's an SSL tunnel
409
to your LDAP server. If your LDAP server doesn't natively sup-
410
port SSL, put a tunnel (wrapper, proxy, whatever you want to
411
call it) on that system too. This should prevent the password
412
from traversing the network in the clear.
483
414
<b>bind_dn (default: empty)</b>
484
If you do have to bind, do it with this distin-
485
guished name. Example:
415
If you do have to bind, do it with this distinguished name.
487
418
bind_dn = uid=postfix, dc=your, dc=com
488
With "bind = sasl" (see above) the DN may be
489
optional for some SASL mechanisms, don't specify a
419
With "bind = sasl" (see above) the DN may be optional for some
420
SASL mechanisms, don't specify a DN if not needed.
492
422
<b>bind_pw (default: empty)</b>
493
The password for the distinguished name above. If
494
you have to use this, you probably want to make the
495
map configuration file readable only by the Postfix
496
user. When using the obsolete <a href="ldap_table.5.html">ldap</a>:ldapsource syn-
497
tax, with map parameters in <a href="postconf.5.html">main.cf</a>, it is not pos-
498
sible to securely store the bind password. This is
499
because <a href="postconf.5.html">main.cf</a> needs to be world readable to allow
500
local accounts to submit mail via the sendmail com-
423
The password for the distinguished name above. If you have to
424
use this, you probably want to make the map configuration file
425
readable only by the Postfix user. When using the obsolete
426
<a href="ldap_table.5.html">ldap</a>:ldapsource syntax, with map parameters in <a href="postconf.5.html">main.cf</a>, it is
427
not possible to securely store the bind password. This is
428
because <a href="postconf.5.html">main.cf</a> needs to be world readable to allow local
429
accounts to submit mail via the sendmail command. Example:
503
431
bind_pw = postfixpw
504
With "bind = sasl" (see above) the password may be
505
optional for some SASL mechanisms, don't specify a
506
password if not needed.
432
With "bind = sasl" (see above) the password may be optional for
433
some SASL mechanisms, don't specify a password if not needed.
508
435
<b>cache (IGNORED with a warning)</b>
510
437
<b>cache_expiry (IGNORED with a warning)</b>
512
439
<b>cache_size (IGNORED with a warning)</b>
513
The above parameters are NO LONGER SUPPORTED by
514
Postfix. Cache support has been dropped from
515
OpenLDAP as of release 2.1.13.
440
The above parameters are NO LONGER SUPPORTED by Postfix. Cache
441
support has been dropped from OpenLDAP as of release 2.1.13.
517
443
<b>recursion_limit (default: 1000)</b>
518
A limit on the nesting depth of DN and URL special
519
result attribute evaluation. The limit must be a
520
non-zero positive number.
444
A limit on the nesting depth of DN and URL special result
445
attribute evaluation. The limit must be a non-zero positive num-
522
448
<b>expansion_limit (default: 0)</b>
523
A limit on the total number of result elements
524
returned (as a comma separated list) by a lookup
525
against the map. A setting of zero disables the
526
limit. Lookups fail with a temporary error if the
527
limit is exceeded. Setting the limit to 1 ensures
528
that lookups do not return multiple values.
449
A limit on the total number of result elements returned (as a
450
comma separated list) by a lookup against the map. A setting of
451
zero disables the limit. Lookups fail with a temporary error if
452
the limit is exceeded. Setting the limit to 1 ensures that
453
lookups do not return multiple values.
530
455
<b>size_limit (default: $expansion_limit)</b>
531
A limit on the number of LDAP entries returned by
532
any single LDAP search performed as part of the
533
lookup. A setting of 0 disables the limit. Expan-
534
sion of DN and URL references involves nested LDAP
535
queries, each of which is separately subjected to
456
A limit on the number of LDAP entries returned by any single
457
LDAP search performed as part of the lookup. A setting of 0 dis-
458
ables the limit. Expansion of DN and URL references involves
459
nested LDAP queries, each of which is separately subjected to
538
Note: even a single LDAP entry can generate multi-
539
ple lookup results, via multiple result attributes
540
and/or multi-valued result attributes. This limit
541
caps the per search resource utilization on the
542
LDAP server, not the final multiplicity of the
543
lookup result. It is analogous to the "-z" option
462
Note: even a single LDAP entry can generate multiple lookup
463
results, via multiple result attributes and/or multi-valued
464
result attributes. This limit caps the per search resource uti-
465
lization on the LDAP server, not the final multiplicity of the
466
lookup result. It is analogous to the "-z" option of
546
469
<b>dereference (default: 0)</b>
547
When to dereference LDAP aliases. (Note that this
548
has nothing do with Postfix aliases.) The permitted
549
values are those legal for the OpenLDAP/UM LDAP
470
When to dereference LDAP aliases. (Note that this has nothing do
471
with Postfix aliases.) The permitted values are those legal for
472
the OpenLDAP/UM LDAP implementations:
638
Both forms require LDAP protocol version 3, which has to
639
be set explicitly with:
550
Both forms require LDAP protocol version 3, which has to be set explic-
643
If any of the Postfix programs querying the map is config-
644
ured in <a href="master.5.html">master.cf</a> to run chrooted, all the certificates
645
and keys involved have to be copied to the chroot jail. Of
646
course, the private keys should only be readable by the
555
If any of the Postfix programs querying the map is configured in <a href="master.5.html">mas-
556
ter.cf</a> to run chrooted, all the certificates and keys involved have to
557
be copied to the chroot jail. Of course, the private keys should only
558
be readable by the user "postfix".
649
The following parameters are relevant to LDAP SSL and
560
The following parameters are relevant to LDAP SSL and STARTTLS:
652
562
<b>start_tls (default: no)</b>
653
Whether or not to issue STARTTLS upon connection to
654
the server. Don't set this with LDAP SSL (the SSL
655
session is setup automatically when the TCP connec-
658
<b>tls_ca_cert_dir (No default; set either this or</b>
659
<b>tls_ca_cert_file)</b>
660
Directory containing X509 Certificate Authority
661
certificates in PEM format which are to be recog-
662
nized by the client in SSL/TLS connections. The
663
files each contain one CA certificate. The files
664
are looked up by the CA subject name hash value,
665
which must hence be available. If more than one CA
666
certificate with the same name hash value exist,
667
the extension must be different (e.g. 9d66eef0.0,
668
9d66eef0.1 etc). The search is performed in the
669
ordering of the extension number, regardless of
670
other properties of the certificates. Use the
671
c_rehash utility (from the OpenSSL distribution) to
672
create the necessary links.
674
<b>tls_ca_cert_file (No default; set either this or</b>
675
<b>tls_ca_cert_dir)</b>
676
File containing the X509 Certificate Authority cer-
677
tificates in PEM format which are to be recognized
678
by the client in SSL/TLS connections. This setting
679
takes precedence over tls_ca_cert_dir.
563
Whether or not to issue STARTTLS upon connection to the server.
564
Don't set this with LDAP SSL (the SSL session is setup automati-
565
cally when the TCP connection is opened).
567
<b>tls_ca_cert_dir (No default; set either this or tls_ca_cert_file)</b>
568
Directory containing X509 Certificate Authority certificates in
569
PEM format which are to be recognized by the client in SSL/TLS
570
connections. The files each contain one CA certificate. The
571
files are looked up by the CA subject name hash value, which
572
must hence be available. If more than one CA certificate with
573
the same name hash value exist, the extension must be different
574
(e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in
575
the ordering of the extension number, regardless of other prop-
576
erties of the certificates. Use the c_rehash utility (from the
577
OpenSSL distribution) to create the necessary links.
579
<b>tls_ca_cert_file (No default; set either this or tls_ca_cert_dir)</b>
580
File containing the X509 Certificate Authority certificates in
581
PEM format which are to be recognized by the client in SSL/TLS
582
connections. This setting takes precedence over tls_ca_cert_dir.
681
584
<b>tls_cert (No default; you must set this)</b>
682
File containing client's X509 certificate to be
683
used by the client in SSL/ TLS connections.
585
File containing client's X509 certificate to be used by the
586
client in SSL/ TLS connections.
685
588
<b>tls_key (No default; you must set this)</b>
686
File containing the private key corresponding to
589
File containing the private key corresponding to the above
689
592
<b>tls_require_cert (default: no)</b>
690
Whether or not to request server's X509 certificate
691
and check its validity when establishing SSL/TLS
692
connections. The supported values are <b>no</b> and <b>yes</b>.
694
With <b>no</b>, the server certificate trust chain is not
695
checked, but with OpenLDAP prior to 2.1.13, the
696
name in the server certificate must still match the
697
LDAP server name. With OpenLDAP 2.0.0 to 2.0.11 the
698
server name is not necessarily what you specified,
699
rather it is determined (by reverse lookup) from
700
the IP address of the LDAP server connection. With
701
OpenLDAP prior to 2.0.13, subjectAlternativeName
702
extensions in the LDAP server certificate are
703
ignored: the server name must match the subject
704
CommonName. The <b>no</b> setting corresponds to the <b>never</b>
705
value of <b>TLS_REQCERT</b> in LDAP client configuration
708
Don't use TLS with OpenLDAP 2.0.x (and especially
709
with x <= 11) if you can avoid it.
711
With <b>yes</b>, the server certificate must be issued by
712
a trusted CA, and not be expired. The LDAP server
713
name must match one of the name(s) found in the
714
certificate (see above for OpenLDAP library version
715
dependent behavior). The <b>yes</b> setting corresponds to
716
the <b>demand</b> value of <b>TLS_REQCERT</b> in LDAP client con-
719
The "try" and "never" values of <b>TLS_REQCERT</b> have no
720
equivalents here. They are not available with
721
OpenLDAP 2.0, and in any case have questionable
722
security properties. Either you want TLS verified
723
LDAP connections, or you don't.
725
The <b>yes</b> value only works correctly with Postfix 2.5
726
and later, or with OpenLDAP 2.0. Earlier Postfix
727
releases or later OpenLDAP releases don't work
728
together with this setting. Support for LDAP over
729
TLS was added to Postfix based on the OpenLDAP 2.0
593
Whether or not to request server's X509 certificate and check
594
its validity when establishing SSL/TLS connections. The sup-
595
ported values are <b>no</b> and <b>yes</b>.
597
With <b>no</b>, the server certificate trust chain is not checked, but
598
with OpenLDAP prior to 2.1.13, the name in the server certifi-
599
cate must still match the LDAP server name. With OpenLDAP 2.0.0
600
to 2.0.11 the server name is not necessarily what you specified,
601
rather it is determined (by reverse lookup) from the IP address
602
of the LDAP server connection. With OpenLDAP prior to 2.0.13,
603
subjectAlternativeName extensions in the LDAP server certificate
604
are ignored: the server name must match the subject CommonName.
605
The <b>no</b> setting corresponds to the <b>never</b> value of <b>TLS_REQCERT</b> in
606
LDAP client configuration files.
608
Don't use TLS with OpenLDAP 2.0.x (and especially with x <= 11)
611
With <b>yes</b>, the server certificate must be issued by a trusted CA,
612
and not be expired. The LDAP server name must match one of the
613
name(s) found in the certificate (see above for OpenLDAP library
614
version dependent behavior). The <b>yes</b> setting corresponds to the
615
<b>demand</b> value of <b>TLS_REQCERT</b> in LDAP client configuration files.
617
The "try" and "allow" values of <b>TLS_REQCERT</b> have no equivalents
618
here. They are not available with OpenLDAP 2.0, and in any case
619
have questionable security properties. Either you want TLS veri-
620
fied LDAP connections, or you don't.
622
The <b>yes</b> value only works correctly with Postfix 2.5 and later,
623
or with OpenLDAP 2.0. Earlier Postfix releases or later OpenLDAP
624
releases don't work together with this setting. Support for LDAP
625
over TLS was added to Postfix based on the OpenLDAP 2.0 API.
732
627
<b>tls_random_file (No default)</b>
733
Path of a file to obtain random bits from when
734
/dev/[u]random is not available, to be used by the
735
client in SSL/TLS connections.
628
Path of a file to obtain random bits from when /dev/[u]random is
629
not available, to be used by the client in SSL/TLS connections.
737
631
<b>tls_cipher_suite (No default)</b>
738
632
Cipher suite to use in SSL/TLS negotiations.
741
Here's a basic example for using LDAP to look up <a href="local.8.html">local(8)</a>
742
aliases. Assume that in <a href="postconf.5.html">main.cf</a>, you have:
635
Here's a basic example for using LDAP to look up <a href="local.8.html">local(8)</a> aliases.
636
Assume that in <a href="postconf.5.html">main.cf</a>, you have:
744
<a href="postconf.5.html#alias_maps">alias_maps</a> = hash:/etc/aliases,
638
<a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/aliases,
745
639
<a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
747
641
and in <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf you have:
added
removed
html/ldap_table.5.html
