1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "https://www.w3.org/TR/html4/loose.dtd"> 3 <html> <head> 4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5 <link rel='stylesheet' type='text/css' href='postfix-doc.css'> 6 <title> Postfix manual - ldap_table(5) </title> 7 </head> <body> <pre> 8 LDAP_TABLE(5) LDAP_TABLE(5) 9 10 <b><a name="name">NAME</a></b> 11 ldap_table - Postfix LDAP client configuration 12 13 <b><a name="synopsis">SYNOPSIS</a></b> 14 <b>postmap -q "</b><i>string</i><b>" <a href="ldap_table.5.html">ldap</a>:/etc/postfix/</b><i>filename</i> 15 16 <b>postmap -q - <a href="ldap_table.5.html">ldap</a>:/etc/postfix/</b><i>filename</i> <<i>inputfile</i> 17 18 <b><a name="description">DESCRIPTION</a></b> 19 The Postfix mail system uses optional tables for address rewriting or 20 mail routing. These tables are usually in <b><a href="lmdb_table.5.html">lmdb</a>:</b>, <b><a href="CDB_README.html">cdb</a>:</b>, <b><a href="DATABASE_README.html#types">hash</a>:</b>, or <b><a href="DATABASE_README.html#types">dbm</a>:</b> 21 format. 22 23 Alternatively, lookup tables can be specified as LDAP databases. To 24 find out what types of lookup tables your Postfix system supports use 25 the "<b>postconf -m</b>" command. 26 27 In order to use LDAP lookups, define an LDAP source as a lookup table 28 in <a href="postconf.5.html">main.cf</a>, for example: 29 30 <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf 31 32 The file /etc/postfix/ldap-aliases.cf has the same format as the Post- 33 fix <a href="postconf.5.html">main.cf</a> file, and can specify the parameters described below. An 34 example is given at the end of this manual. 35 36 This configuration method is available with Postfix version 2.1 and 37 later. See the section "OBSOLETE MAIN.CF PARAMETERS" below for older 38 Postfix versions. 39 40 For details about LDAP SSL and STARTTLS, see the section on SSL and 41 STARTTLS below. 42 43 <b><a name="list_membership">LIST MEMBERSHIP</a></b> 44 When using LDAP to store lists such as $<a href="postconf.5.html#mynetworks">mynetworks</a>, $<a href="postconf.5.html#mydestination">mydestination</a>, 45 $<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- 46 stand that the table must store each list member as a separate key. The 47 table lookup verifies the *existence* of the key. See "Postfix lists 48 versus tables" in the <a href="DATABASE_README.html">DATABASE_README</a> document for a discussion. 49 50 Do NOT create tables that return the full list of domains in $<a href="postconf.5.html#mydestination">mydesti</a>- 51 <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>. 52 53 DO create tables with each matching item as a key and with an arbitrary 54 value. With LDAP databases it is not uncommon to return the key itself. 55 56 For example, NEVER do this in a map defining $<a href="postconf.5.html#mydestination">mydestination</a>: 57 58 query_filter = domain=* 59 result_attribute = domain 60 61 Do this instead: 62 63 query_filter = domain=%s 64 result_attribute = domain 65 66 <b><a name="general_ldap_parameters">GENERAL LDAP PARAMETERS</a></b> 67 In the text below, default values are given in parentheses. Note: 68 don't use quotes in these variables; at least, not until the Postfix 69 configuration routines understand how to deal with quoted strings. 70 71 <b>server_host (default: localhost)</b> 72 The name of the host running the LDAP server, e.g. 73 74 server_host = ldap.example.com 75 76 Depending on the LDAP client library you're using, it should be 77 possible to specify multiple servers here, with the library try- 78 ing them in order should the first one fail. It should also be 79 possible to give each server in the list a different port (over- 80 riding <b>server_port</b> below), by naming them like 81 82 server_host = ldap.example.com:1444 83 84 NOTE: this client will reconnect immediately after a single 85 failure, and will fail a lookup request after a second attempt 86 also fails. 87 88 With OpenLDAP, a (list of) LDAP URLs can be used to specify both 89 the hostname(s) and the port(s): 90 91 server_host = <a href="ldap_table.5.html">ldap</a>://ldap.example.com:1444 92 <a href="ldap_table.5.html">ldap</a>://ldap2.example.com:1444 93 94 All LDAP URLs accepted by the OpenLDAP library are supported, 95 including connections over UNIX domain sockets, and LDAP SSL 96 (the last one provided that OpenLDAP was compiled with support 97 for SSL): 98 99 server_host = <a href="ldap_table.5.html">ldapi</a>://%2Fsome%2Fpath 100 <a href="ldap_table.5.html">ldaps</a>://ldap.example.com:636 101 102 <b>server_port (default: 389)</b> 103 The port the LDAP server listens on, e.g. 104 105 server_port = 778 106 107 <b>timeout (default: 10 seconds)</b> 108 The number of seconds a search can take before timing out, e.g. 109 110 timeout = 5 111 112 <b>search_base (No default; you must configure this)</b> 113 The <a href="https://tools.ietf.org/html/rfc2253">RFC2253</a> base DN at which to conduct the search, e.g. 114 115 search_base = dc=your, dc=com 116 117 With Postfix 2.2 and later this parameter supports the following 118 '%' expansions: 119 120 <b>%%</b> This is replaced by a literal '%' character. 121 122 <b>%s</b> This is replaced by the input key. <a href="https://tools.ietf.org/html/rfc2253">RFC 2253</a> quoting is 123 used to make sure that the input key does not add unex- 124 pected metacharacters. 125 126 <b>%u</b> When the input key is an address of the form user@domain, 127 <b>%u</b> is replaced by the (<a href="https://tools.ietf.org/html/rfc2253">RFC 2253</a>) quoted local part of the 128 address. Otherwise, <b>%u</b> is replaced by the entire search 129 string. If the localpart is empty, the search is sup- 130 pressed and returns no results. 131 132 <b>%d</b> When the input key is an address of the form user@domain, 133 <b>%d</b> is replaced by the (<a href="https://tools.ietf.org/html/rfc2253">RFC 2253</a>) quoted domain part of 134 the address. Otherwise, the search is suppressed and 135 returns no results. 136 137 <b>%[SUD]</b> For the <b>search_base</b> parameter, the upper-case equivalents 138 of the above expansions behave identically to their 139 lower-case counter-parts. With the <b>result_format</b> parame- 140 ter (previously called <b>result_filter</b> see the OTHER OBSO- 141 LETE FEATURES section and below), they expand to the cor- 142 responding components of input key rather than the result 143 value. 144 145 <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by the corre- 146 sponding most significant component of the input key's 147 domain. If the input key is <i>user (a] mail.example.com</i>, then 148 %1 is <b>com</b>, %2 is <b>example</b> and %3 is <b>mail</b>. If the input key 149 is unqualified or does not have enough domain components 150 to satisfy all the specified patterns, the search is sup- 151 pressed and returns no results. 152 153 <b>query_filter (default: mailacceptinggeneralid=%s)</b> 154 The <a href="https://tools.ietf.org/html/rfc2254">RFC2254</a> filter used to search the directory, where <b>%s</b> is a 155 substitute for the address Postfix is trying to resolve, e.g. 156 157 query_filter = (&(mail=%s)(paid_up=true)) 158 159 This parameter supports the following '%' expansions: 160 161 <b>%%</b> This is replaced by a literal '%' character. (Postfix 2.2 162 and later). 163 164 <b>%s</b> This is replaced by the input key. <a href="https://tools.ietf.org/html/rfc2254">RFC 2254</a> quoting is 165 used to make sure that the input key does not add unex- 166 pected metacharacters. 167 168 <b>%u</b> When the input key is an address of the form user@domain, 169 <b>%u</b> is replaced by the (<a href="https://tools.ietf.org/html/rfc2254">RFC 2254</a>) quoted local part of the 170 address. Otherwise, <b>%u</b> is replaced by the entire search 171 string. If the localpart is empty, the search is sup- 172 pressed and returns no results. 173 174 <b>%d</b> When the input key is an address of the form user@domain, 175 <b>%d</b> is replaced by the (<a href="https://tools.ietf.org/html/rfc2254">RFC 2254</a>) quoted domain part of 176 the address. Otherwise, the search is suppressed and 177 returns no results. 178 179 <b>%[SUD]</b> The upper-case equivalents of the above expansions behave 180 in the <b>query_filter</b> parameter identically to their 181 lower-case counter-parts. With the <b>result_format</b> parame- 182 ter (previously called <b>result_filter</b> see the OTHER OBSO- 183 LETE FEATURES section and below), they expand to the cor- 184 responding components of input key rather than the result 185 value. 186 187 The above %S, %U and %D expansions are available with 188 Postfix 2.2 and later. 189 190 <b>%[1-9]</b> The patterns %1, %2, ... %9 are replaced by the corre- 191 sponding most significant component of the input key's 192 domain. If the input key is <i>user (a] mail.example.com</i>, then 193 %1 is <b>com</b>, %2 is <b>example</b> and %3 is <b>mail</b>. If the input key 194 is unqualified or does not have enough domain components 195 to satisfy all the specified patterns, the search is sup- 196 pressed and returns no results. 197 198 The above %1, ..., %9 expansions are available with Post- 199 fix 2.2 and later. 200 201 The "domain" parameter described below limits the input keys to 202 addresses in matching domains. When the "domain" parameter is 203 non-empty, LDAP queries for unqualified addresses or addresses 204 in non-matching domains are suppressed and return no results. 205 206 NOTE: DO NOT put quotes around the <b>query_filter</b> parameter. 207 208 <b>result_format (default: %s</b>) 209 Called <b>result_filter</b> in Postfix releases prior to 2.2. Format 210 template applied to result attributes. Most commonly used to 211 append (or prepend) text to the result. This parameter supports 212 the following '%' expansions: 213 214 <b>%%</b> This is replaced by a literal '%' character. (Postfix 2.2 215 and later). 216 217 <b>%s</b> This is replaced by the value of the result attribute. 218 When result is empty it is skipped. 219 220 <b>%u</b> When the result attribute value is an address of the form 221 user@domain, <b>%u</b> is replaced by the local part of the 222 address. When the result has an empty localpart it is 223 skipped. 224 225 <b>%d</b> When a result attribute value is an address of the form 226 user@domain, <b>%d</b> is replaced by the domain part of the 227 attribute value. When the result is unqualified it is 228 skipped. 229 230 <b>%[SUD1-9]</b> 231 The upper-case and decimal digit expansions interpolate 232 the parts of the input key rather than the result. Their 233 behavior is identical to that described with <b>query_fil-</b> 234 <b>ter</b>, and in fact because the input key is known in 235 advance, lookups whose key does not contain all the 236 information specified in the result template are sup- 237 pressed and return no results. 238 239 The above %S, %U, %D and %1, ..., %9 expansions are 240 available with Postfix 2.2 and later. 241 242 For example, using "result_format = <a href="smtp.8.html">smtp</a>:[%s]" allows one to use 243 a mailHost attribute as the basis of a <a href="transport.5.html">transport(5)</a> table. After 244 applying the result format, multiple values are concatenated as 245 comma separated strings. The expansion_limit and size_limit 246 parameters explained below allow one to restrict the number of 247 values in the result, which is especially useful for maps that 248 should return a single value. 249 250 The default value <b>%s</b> specifies that each attribute value should 251 be used as is. 252 253 This parameter was called <b>result_filter</b> in Postfix releases 254 prior to 2.2. If no "result_format" is specified, the value of 255 "result_filter" will be used instead before resorting to the 256 default value. This provides compatibility with old configura- 257 tion files. 258 259 NOTE: DO NOT put quotes around the result format! 260 261 <b>domain (default: no domain list)</b> 262 This is a list of domain names, paths to files, or "<a href="DATABASE_README.html">type:table</a>" 263 databases. When specified, only fully qualified search keys with 264 a *non-empty* localpart and a matching domain are eligible for 265 lookup: 'user' lookups, bare domain lookups and "@domain" 266 lookups are not performed. This can significantly reduce the 267 query load on the LDAP server. 268 269 domain = postfix.org, <a href="DATABASE_README.html#types">hash</a>:/etc/postfix/searchdomains 270 271 It is best not to use LDAP to store the domains eligible for 272 LDAP lookups. 273 274 NOTE: DO NOT define this parameter for <a href="local.8.html">local(8)</a> aliases. 275 276 This feature is available in Postfix 1.0 and later. 277 278 <b>result_attribute (default: maildrop)</b> 279 The attribute(s) Postfix will read from any directory entries 280 returned by the lookup, to be resolved to an email address. 281 282 result_attribute = mailbox, maildrop 283 284 Don't rely on the default value ("maildrop"). Set the 285 result_attribute explicitly in all ldap table configuration 286 files. This is particularly relevant when no result_attribute is 287 applicable, e.g. cases in which leaf_result_attribute and/or 288 terminal_result_attribute are used instead. The default value is 289 harmless if "maildrop" is also listed as a leaf or terminal 290 result attribute, but it is best to not leave this to chance. 291 292 <b>special_result_attribute (default: empty)</b> 293 The attribute(s) of directory entries that can contain DNs or 294 <a href="https://tools.ietf.org/html/rfc2255">RFC 2255</a> LDAP URLs. If found, a recursive search is performed to 295 retrieve the entry referenced by the DN, or the entries matched 296 by the URL query. 297 298 special_result_attribute = memberdn 299 300 DN recursion retrieves the same result_attributes as the main 301 query, including the special attributes for further recursion. 302 303 URL processing retrieves only those attributes that are included 304 in both the URL definition and as result attributes (ordinary, 305 special, leaf or terminal) in the Postfix table definition. If 306 the URL lists any of the table's special result attributes, 307 these are retrieved and used recursively. A URL that does not 308 specify any attribute selection, is equivalent (<a href="https://tools.ietf.org/html/rfc2255">RFC 2255</a>) to a 309 URL that selects all attributes, in which case the selected 310 attributes will be the full set of result attributes in the 311 Postfix table. 312 313 If an LDAP URL attribute-descriptor or the corresponding Postfix 314 LDAP table result attribute (but not both) uses <a href="https://tools.ietf.org/html/rfc2255">RFC 2255</a> 315 sub-type options ("attr;option"), the attribute requested from 316 the LDAP server will include the sub-type option. In all other 317 cases, the URL attribute and the table attribute must match 318 exactly. Attributes with options in both the URL and the Postfix 319 table are requested only when the options are identical. LDAP 320 attribute-descriptor options are very rarely used, most LDAP 321 users will not need to concern themselves with this level of 322 nuanced detail. 323 324 <b>terminal_result_attribute (default: empty)</b> 325 When one or more terminal result attributes are found in an LDAP 326 entry, all other result attributes are ignored and only the ter- 327 minal result attributes are returned. This is useful for dele- 328 gating expansion of group members to a particular host, by using 329 an optional "maildrop" attribute on selected groups to route the 330 group to a specific host, where the group is expanded, possibly 331 via mailing-list manager or other special processing. 332 333 result_attribute = 334 terminal_result_attribute = maildrop 335 336 When using terminal and/or leaf result attributes, the 337 result_attribute is best set to an empty value when it is not 338 used, or else explicitly set to the desired value, even if it is 339 the default value "maildrop". 340 341 This feature is available with Postfix 2.4 or later. 342 343 <b>leaf_result_attribute (default: empty)</b> 344 When one or more special result attributes are found in a 345 non-terminal (see above) LDAP entry, leaf result attributes are 346 excluded from the expansion of that entry. This is useful when 347 expanding groups and the desired mail address attribute(s) of 348 the member objects obtained via DN or URI recursion are also 349 present in the group object. To only return the attribute values 350 from the leaf objects and not the containing group, add the 351 attribute to the leaf_result_attribute list, and not the 352 result_attribute list, which is always expanded. Note, the 353 default value of "result_attribute" is not empty, you may want 354 to set it explicitly empty when using "leaf_result_attribute" to 355 expand the group to a list of member DN addresses. If groups 356 have both member DN references AND attributes that hold multiple 357 string valued rfc822 addresses, then the string attributes go in 358 "result_attribute". The attributes that represent the email 359 addresses of objects referenced via a DN (or LDAP URI) go in 360 "leaf_result_attribute". 361 362 result_attribute = memberaddr 363 special_result_attribute = memberdn 364 terminal_result_attribute = maildrop 365 leaf_result_attribute = mail 366 367 When using terminal and/or leaf result attributes, the 368 result_attribute is best set to an empty value when it is not 369 used, or else explicitly set to the desired value, even if it is 370 the default value "maildrop". 371 372 This feature is available with Postfix 2.4 or later. 373 374 <b>scope (default: sub)</b> 375 The LDAP search scope: <b>sub</b>, <b>base</b>, or <b>one</b>. These translate into 376 LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE, and LDAP_SCOPE_ONELEVEL. 377 378 <b>bind (default: yes)</b> 379 Whether or how to bind to the LDAP server. Newer LDAP implemen- 380 tations don't require clients to bind, which saves time. Exam- 381 ple: 382 383 # Don't bind 384 bind = no 385 # Use SIMPLE bind 386 bind = yes 387 # Use SASL bind 388 bind = sasl 389 390 Postfix versions prior to 2.8 only support "bind = no" which 391 means don't bind, and "bind = yes" which means do a SIMPLE bind. 392 Postfix 2.8 and later also supports "bind = SASL" when compiled 393 with LDAP SASL support as described in <a href="LDAP_README.html">LDAP_README</a>, it also adds 394 the synonyms "bind = none" and "bind = simple" for "bind = no" 395 and "bind = yes" respectively. See the SASL section below for 396 additional parameters available with "bind = sasl". 397 398 If you do need to bind, you might consider configuring Postfix 399 to connect to the local machine on a port that's an SSL tunnel 400 to your LDAP server. If your LDAP server doesn't natively sup- 401 port SSL, put a tunnel (wrapper, proxy, whatever you want to 402 call it) on that system too. This should prevent the password 403 from traversing the network in the clear. 404 405 <b>bind_dn (default: empty)</b> 406 If you do have to bind, do it with this distinguished name. 407 Example: 408 409 bind_dn = uid=postfix, dc=your, dc=com 410 With "bind = sasl" (see above) the DN may be optional for some 411 SASL mechanisms, don't specify a DN if not needed. 412 413 <b>bind_pw (default: empty)</b> 414 The password for the distinguished name above. If you have to 415 use this, you probably want to make the map configuration file 416 readable only by the Postfix user. When using the obsolete 417 <a href="ldap_table.5.html">ldap</a>:ldapsource syntax, with map parameters in <a href="postconf.5.html">main.cf</a>, it is 418 not possible to securely store the bind password. This is 419 because <a href="postconf.5.html">main.cf</a> needs to be world readable to allow local 420 accounts to submit mail via the sendmail command. Example: 421 422 bind_pw = postfixpw 423 With "bind = sasl" (see above) the password may be optional for 424 some SASL mechanisms, don't specify a password if not needed. 425 426 <b>cache (IGNORED with a warning)</b> 427 428 <b>cache_expiry (IGNORED with a warning)</b> 429 430 <b>cache_size (IGNORED with a warning)</b> 431 The above parameters are NO LONGER SUPPORTED by Postfix. Cache 432 support has been dropped from OpenLDAP as of release 2.1.13. 433 434 <b>recursion_limit (default: 1000)</b> 435 A limit on the nesting depth of DN and URL special result 436 attribute evaluation. The limit must be a non-zero positive num- 437 ber. 438 439 <b>expansion_limit (default: 0)</b> 440 A limit on the total number of result elements returned (as a 441 comma separated list) by a lookup against the map. A setting of 442 zero disables the limit. Lookups fail with a temporary error if 443 the limit is exceeded. Setting the limit to 1 ensures that 444 lookups do not return multiple values. 445 446 <b>size_limit (default: $expansion_limit)</b> 447 A limit on the number of LDAP entries returned by any single 448 LDAP search performed as part of the lookup. A setting of 0 dis- 449 ables the limit. Expansion of DN and URL references involves 450 nested LDAP queries, each of which is separately subjected to 451 this limit. 452 453 Note: even a single LDAP entry can generate multiple lookup 454 results, via multiple result attributes and/or multi-valued 455 result attributes. This limit caps the per search resource uti- 456 lization on the LDAP server, not the final multiplicity of the 457 lookup result. It is analogous to the "-z" option of 458 "ldapsearch". 459 460 <b>dereference (default: 0)</b> 461 When to dereference LDAP aliases. (Note that this has nothing do 462 with Postfix aliases.) The permitted values are those legal for 463 the OpenLDAP/UM LDAP implementations: 464 465 0 never 466 467 1 when searching 468 469 2 when locating the base object for the search 470 471 3 always 472 473 See ldap.h or the ldap_open(3) or ldapsearch(1) man pages for 474 more information. And if you're using an LDAP package that has 475 other possible values, please bring it to the attention of the 476 postfix-users (a] postfix.org mailing list. 477 478 <b>chase_referrals (default: 0)</b> 479 Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP version 3 480 support). 481 482 <b>version (default: 2)</b> 483 Specifies the LDAP protocol version to use. 484 485 <b>debuglevel (default: 0)</b> 486 What level to set for debugging in the OpenLDAP libraries. 487 488 <b><a name="ldap_sasl_parameters">LDAP SASL PARAMETERS</a></b> 489 If you're using the OpenLDAP libraries compiled with SASL support, 490 Postfix 2.8 and later built with LDAP SASL support as described in 491 <a href="LDAP_README.html">LDAP_README</a> can authenticate to LDAP servers via SASL. 492 493 This enables authentication to the LDAP server via mechanisms other 494 than a simple password. The added flexibility has a cost: it is no 495 longer practical to set an explicit timeout on the duration of an LDAP 496 bind operation. Under adverse conditions, whether a SASL bind times 497 out, or if it does, the duration of the timeout is determined by the 498 LDAP and SASL libraries. 499 500 It is best to use tables that use SASL binds via <a href="proxymap.8.html">proxymap(8)</a>, this way 501 the requesting process can time-out the proxymap request. This also 502 lets you tailer the process environment by overriding the <a href="proxymap.8.html">proxymap(8)</a> 503 <a href="postconf.5.html#import_environment">import_environment</a> setting in <a href="master.5.html">master.cf</a>(5). Special environment set- 504 tings may be needed to configure GSSAPI credential caches or other SASL 505 mechanism specific options. The GSSAPI credentials used for LDAP 506 lookups may need to be different than say those used for the Postfix 507 SMTP client to authenticate to remote servers. 508 509 Using SASL mechanisms requires LDAP protocol version 3, the default 510 protocol version is 2 for backwards compatibility. You must set "ver- 511 sion = 3" in addition to "bind = sasl". 512 513 The following parameters are relevant to using LDAP with SASL 514 515 <b>sasl_mechs (default: empty)</b> 516 Space separated list of SASL mechanism(s) to try. 517 518 <b>sasl_realm (default: empty)</b> 519 SASL Realm to use, if applicable. 520 521 <b>sasl_authz_id (default: empty)</b> 522 The SASL authorization identity to assert, if applicable. 523 524 <b>sasl_minssf (default: 0)</b> 525 The minimum required sasl security factor required to establish 526 a connection. 527 528 <b><a name="ldap_ssl_and_starttls_parameters">LDAP SSL AND STARTTLS PARAMETERS</a></b> 529 If you're using the OpenLDAP libraries compiled with SSL support, Post- 530 fix can connect to LDAP SSL servers and can issue the STARTTLS command. 531 532 LDAP SSL service can be requested by using a LDAP SSL URL in the 533 server_host parameter: 534 535 server_host = <a href="ldap_table.5.html">ldaps</a>://ldap.example.com:636 536 537 STARTTLS can be turned on with the start_tls parameter: 538 539 start_tls = yes 540 541 Both forms require LDAP protocol version 3, which has to be set explic- 542 itly with: 543 544 version = 3 545 546 If any of the Postfix programs querying the map is configured in <a href="master.5.html">mas- 547 ter.cf</a> to run chrooted, all the certificates and keys involved have to 548 be copied to the chroot jail. Of course, the private keys should only 549 be readable by the user "postfix". 550 551 The following parameters are relevant to LDAP SSL and STARTTLS: 552 553 <b>start_tls (default: no)</b> 554 Whether or not to issue STARTTLS upon connection to the server. 555 Don't set this with LDAP SSL (the SSL session is setup automati- 556 cally when the TCP connection is opened). 557 558 <b>tls_ca_cert_dir (No default; set either this or tls_ca_cert_file)</b> 559 Directory containing X509 Certification Authority certificates 560 in PEM format which are to be recognized by the client in 561 SSL/TLS connections. The files each contain one CA certificate. 562 The files are looked up by the CA subject name hash value, which 563 must hence be available. If more than one CA certificate with 564 the same name hash value exist, the extension must be different 565 (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is performed in 566 the ordering of the extension number, regardless of other prop- 567 erties of the certificates. Use the c_rehash utility (from the 568 OpenSSL distribution) to create the necessary links. 569 570 <b>tls_ca_cert_file (No default; set either this or tls_ca_cert_dir)</b> 571 File containing the X509 Certification Authority certificates in 572 PEM format which are to be recognized by the client in SSL/TLS 573 connections. This setting takes precedence over tls_ca_cert_dir. 574 575 <b>tls_cert (No default; you must set this)</b> 576 File containing client's X509 certificate to be used by the 577 client in SSL/ TLS connections. 578 579 <b>tls_key (No default; you must set this)</b> 580 File containing the private key corresponding to the above 581 tls_cert. 582 583 <b>tls_require_cert (default: no)</b> 584 Whether or not to request server's X509 certificate and check 585 its validity when establishing SSL/TLS connections. The sup- 586 ported values are <b>no</b> and <b>yes</b>. 587 588 With <b>no</b>, the server certificate trust chain is not checked, but 589 with OpenLDAP prior to 2.1.13, the name in the server certifi- 590 cate must still match the LDAP server name. With OpenLDAP 2.0.0 591 to 2.0.11 the server name is not necessarily what you specified, 592 rather it is determined (by reverse lookup) from the IP address 593 of the LDAP server connection. With OpenLDAP prior to 2.0.13, 594 subjectAlternativeName extensions in the LDAP server certificate 595 are ignored: the server name must match the subject CommonName. 596 The <b>no</b> setting corresponds to the <b>never</b> value of <b>TLS_REQCERT</b> in 597 LDAP client configuration files. 598 599 Don't use TLS with OpenLDAP 2.0.x (and especially with x <= 11) 600 if you can avoid it. 601 602 With <b>yes</b>, the server certificate must be issued by a trusted CA, 603 and not be expired. The LDAP server name must match one of the 604 name(s) found in the certificate (see above for OpenLDAP library 605 version dependent behavior). The <b>yes</b> setting corresponds to the 606 <b>demand</b> value of <b>TLS_REQCERT</b> in LDAP client configuration files. 607 608 The "try" and "allow" values of <b>TLS_REQCERT</b> have no equivalents 609 here. They are not available with OpenLDAP 2.0, and in any case 610 have questionable security properties. Either you want TLS veri- 611 fied LDAP connections, or you don't. 612 613 The <b>yes</b> value only works correctly with Postfix 2.5 and later, 614 or with OpenLDAP 2.0. Earlier Postfix releases or later OpenLDAP 615 releases don't work together with this setting. Support for LDAP 616 over TLS was added to Postfix based on the OpenLDAP 2.0 API. 617 618 <b>tls_random_file (No default)</b> 619 Path of a file to obtain random bits from when /dev/[u]random is 620 not available, to be used by the client in SSL/TLS connections. 621 622 <b>tls_cipher_suite (No default)</b> 623 Cipher suite to use in SSL/TLS negotiations. 624 625 <b><a name="example">EXAMPLE</a></b> 626 Here's a basic example for using LDAP to look up <a href="local.8.html">local(8)</a> aliases. 627 Assume that in <a href="postconf.5.html">main.cf</a>, you have: 628 629 <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="DATABASE_README.html#types">hash</a>:/etc/aliases, 630 <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf 631 632 and in <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf you have: 633 634 server_host = ldap.example.com 635 search_base = dc=example, dc=com 636 637 Upon receiving mail for a local address "ldapuser" that isn't found in 638 the /etc/aliases database, Postfix will search the LDAP server listen- 639 ing at port 389 on ldap.example.com. It will bind anonymously, search 640 for any directory entries whose mailacceptinggeneralid attribute is 641 "ldapuser", read the "maildrop" attributes of those found, and build a 642 list of their maildrops, which will be treated as <a href="https://tools.ietf.org/html/rfc822">RFC822</a> addresses to 643 which the message will be delivered. 644 645 <b>OBSOLETE MAIN.CF PARAMETERS</b> 646 For backwards compatibility with Postfix version 2.0 and earlier, LDAP 647 parameters can also be defined in <a href="postconf.5.html">main.cf</a>. Specify as LDAP source a 648 name that doesn't begin with a slash or a dot. The LDAP parameters 649 will then be accessible as the name you've given the source in its def- 650 inition, an underscore, and the name of the parameter. For example, if 651 the map is specified as "<a href="ldap_table.5.html">ldap</a>:<i>ldapsource</i>", the "server_host" parameter 652 below would be defined in <a href="postconf.5.html">main.cf</a> as "<i>ldapsource</i>_server_host". 653 654 Note: with this form, the passwords for the LDAP sources are written in 655 <a href="postconf.5.html">main.cf</a>, which is normally world-readable. Support for this form will 656 be removed in a future Postfix version. 657 658 <b><a name="other_obsolete_features">OTHER OBSOLETE FEATURES</a></b> 659 <b>result_filter (No default)</b> 660 For backwards compatibility with the pre 2.2 LDAP clients, 661 <b>result_filter</b> can for now be used instead of <b>result_format</b>, when 662 the latter parameter is not also set. The new name better 663 reflects the function of the parameter. This compatibility 664 interface may be removed in a future release. 665 666 <b><a name="see_also">SEE ALSO</a></b> 667 <a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager 668 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 669 <a href="mysql_table.5.html">mysql_table(5)</a>, MySQL lookup tables 670 <a href="pgsql_table.5.html">pgsql_table(5)</a>, PostgreSQL lookup tables 671 672 <b><a name="readme_files">README FILES</a></b> 673 <a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview 674 <a href="LDAP_README.html">LDAP_README</a>, Postfix LDAP client guide 675 676 <b><a name="license">LICENSE</a></b> 677 The Secure Mailer license must be distributed with this software. 678 679 <b>AUTHOR(S)</b> 680 Carsten Hoeger, Hery Rakotoarisoa, John Hensley, Keith Stevenson, LaM- 681 ont Jones, Liviu Daia, Manuel Guesdon, Mike Mattice, Prabhat K Singh, 682 Sami Haahtinen, Samuel Tardieu, Victor Duchovni, and many others. 683 684 LDAP_TABLE(5) 685 </pre> </body> </html> 686
Indexes created Wed Sep 23 00:26:21 UTC 2026