#++ # NAME # ldap_table 5 # SUMMARY # Postfix LDAP client configuration # SYNOPSIS # \fBpostmap -q "\fIstring\fB" ldap:/etc/postfix/filename\fR # # \fBpostmap -q - ldap:/etc/postfix/\fIfilename\fR <\fIinputfile\fR # DESCRIPTION # The Postfix mail system uses optional tables for address # rewriting or mail routing. These tables are usually in # \fBdbm\fR or \fBdb\fR format. # # Alternatively, lookup tables can be specified as LDAP databases. # # In order to use LDAP lookups, define an LDAP source as a lookup # table in main.cf, for example: # .ti +4 # alias_maps = ldap:/etc/postfix/ldap-aliases.cf # # The file /etc/postfix/ldap-aliases.cf has the same format as # the Postfix main.cf file, and can specify the parameters # described below. An example is given at the end of this manual. # # This configuration method is available with Postfix version # 2.1 and later. See the section "BACKWARDS COMPATIBILITY" # below for older Postfix versions. # # For details about LDAP SSL and STARTTLS, see the section # on SSL and STARTTLS below. # BACKWARDS COMPATIBILITY # .ad # .fi # For backwards compatibility with Postfix version 2.0 and earlier, # LDAP parameters can also be defined in main.cf. Specify # as LDAP source a name that doesn't begin with a slash or # a dot. The LDAP parameters will then be accessible as the # name you've given the source in its definition, an underscore, # and the name of the parameter. For example, if the map is # specified as "ldap:\fIldapsource\fR", the "server_host" # parameter below would be defined in main.cf as # "\fIldapsource\fR_server_host". # # Note: with this form, the passwords for the LDAP sources are # written in main.cf, which is normally world-readable. Support # for this form will be removed in a future Postfix version. # LIST MEMBERSHIP # .ad # .fi # When using LDAP to store lists such as $mynetworks, # $mydestination, $relay_domains, $local_recipient_maps, # etc., it is important to understand that the table must # store each list member as a separate key. The table lookup # verifies the *existence* of the key. See "Postfix lists # versus tables" in the DATABASE_README document for a # discussion. # # Do NOT create tables that return the full list of domains # in $mydestination or $relay_domains etc., or IP addresses # in $mynetworks. # # DO create tables with each matching item as a key and with # an arbitrary value. With LDAP databases it is not uncommon to # return the key itself. # # For example, NEVER do this in a map defining $mydestination: # .in +4 # query_filter = domain=* # .br # result_attribute = domain # .in -4 # # Do this instead: # .in +4 # query_filter = domain=%s # .br # result_attribute = domain # .in -4 # GENERAL LDAP PARAMETERS # .ad # .fi # In the text below, default values are given in parentheses. # Note: don't use quotes in these variables; at least, not until the # Postfix configuration routines understand how to deal with quoted # strings. # .IP "\fBserver_host (default: localhost)\fR" # The name of the host running the LDAP server, e.g. # .ti +4 # server_host = ldap.your.com # # Depending on the LDAP client library you're using, it should # be possible to specify multiple servers here, with the library # trying them in order should the first one fail. It should also # be possible to give each server in the list a different port # (overriding \fBserver_port\fR below), by naming them like # .ti +4 # server_host = ldap.your.com:1444 # # With OpenLDAP, a (list of) LDAP URLs can be used to specify both # the hostname(s) and the port(s): # .ti +4 # server_host = ldap://ldap.your.com:1444 # # All LDAP URLs accepted by the OpenLDAP library are supported, # including connections over UNIX domain sockets, and LDAP SSL # (the last one provided that OpenLDAP was compiled with support # for SSL): # .ti +4 # server_host = ldapi://%2Fsome%2Fpath # .ti +4 # server_host = ldaps://ldap.your.com:636 # .IP "\fBserver_port (default: 389)\fR" # The port the LDAP server listens on, e.g. # .ti +4 # server_port = 778 # .IP "\fBsearch_base (No default; you must configure this)\fR" # The RFC2253 base DN at which to conduct the search, e.g. # .ti +4 # search_base = dc=your, dc=com # .IP "\fBtimeout (default: 10 seconds)\fR" # The number of seconds a search can take before timing out, e.g. # .ti +4 # timeout = 5 # .IP "\fBquery_filter (default: mailacceptinggeneralid=%s)\fR" # The RFC2254 filter used to search the directory, where \fB%s\fR # is a substitute for the address Postfix is trying to resolve, # e.g. # .ti +4 # query_filter = (&(mail=%s)(paid_up=true)) # # This parameter supports the following '%' expansions: # .RS # .IP "\fB\fB%s\fR\fR" # This is replaced by the input key. RFC 2254 quoting is used # to make sure that the input key does not add unexpected # metacharacters. # .IP "\fB\fB%u\fR\fR" # When the input key is an address of the form user@domain, # \fB%u\fR is replaced by the (RFC 2254) quoted local part of the # address. If no domain is specified, \fB%u\fR is replaced by the # entire search string. # .IP "\fB\fB%d\fR\fR" # When the input key is an address of the form user@domain, # \fB%d\fR is replaced by the (RFC 2254) quoted domain part of the # address. When the input key has no domain qualifier, \fB%d\fR is # replaced by the entire search string. # .RE # .IP # The "domain" parameter described below limits the input # keys to addresses in matching domains. When the "domain" # parameter is non-empty, LDAP queries for unqualified # addresses or addresses in non-matching domains are suppressed # and return no results. # # NOTE: DO NOT put quotes around the query filter. # .IP "\fBresult_filter (default: \fB%s\fR)\fR" # Format template applied to result attributes. Supports the # same expansions as the query_filter, and can be easily used # to append (or prepend) text. This parameter supports the # following '%' expansions: # .RS # .IP "\fB\fB%s\fR\fR" # This is replaced by the value of the result attribute. # .IP "\fB%u\fR # When the result attribute is an address of the form # user@domain, \fB%u\fR is replaced local part of the address, if # the result attribute is unqualified, \fB%u\fR is replaced by the # entire attribute value. # .IP "\fB\fB%d\fR\fR" # When a result attribute is an address of the form user@domain, # \fB%d\fR is replaced by the domain part of the attribute value. # If an attribute value is unqualified \fB%d\fR is replaced by the # entire attribute value. # .RE # .IP # For example, using "result_filter = smtp:[%s]" allows one # to use a mailHost attribute as the basis of a transport(5) # table. After applying the result filter, multiple values # are concatenated as comma separated strings. The expansion_limit # and size_limit parameters explained below allow one to # restrict the number of values in the result, which is # especially useful for maps that should return a single # value. # # The default value \fB%s\fR specifies that each # attribute value should be used as is. # # NOTE: DO NOT put quotes around the result filter! # .IP "\fBdomain (default: no domain list)\fR" # This is a list of domain names, paths to files, or # dictionaries. When specified, only fully qualified search # keys with a *non-empty* localpart and a matching domain # are eligible for lookup: 'user' lookups, bare domain lookups # and "@domain" lookups are not performed. This can significantly # reduce the query load on the LDAP server. # .ti +4 # domain = postfix.org, hash:/etc/postfix/searchdomains # # It is best not to use LDAP to store the domains eligible # for LDAP lookups. # # NOTE: DO NOT define this parameter for local(8) aliases. # .IP "\fBresult_attribute (default: maildrop)\fR" # The attribute(s) Postfix will read from any directory # entries returned by the lookup, to be resolved to an email # address. # .ti +4 # result_attribute = mailbox,maildrop # .IP "\fBspecial_result_attribute (No default)\fR" # The attribute(s) of directory entries that can contain DNs # or URLs. If found, a recursive subsequent search is done # using their values. # .ti +4 # special_result_attribute = member # # DN recursion retrieves the same result_attributes as the # main query, including the special attributes for further # recursion. URI processing retrieves only those attributes # that are included in the URI definition and are *also* # listed in "result_attribute". If the URI lists any of the # map's special result attributes, these are also retrieved # and used recursively. # .IP "\fBscope (default: sub)\fR" # The LDAP search scope: \fBsub\fR, \fBbase\fR, or \fBone\fR. # These translate into LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE, # and LDAP_SCOPE_ONELEVEL. # .IP "\fBbind (default: yes)\fR" # Whether or not to bind to the LDAP server. Newer LDAP # implementations don't require clients to bind, which saves # time. Example: # .ti +4 # bind = no # # If you do need to bind, you might consider configuring # Postfix to connect to the local machine on a port that's # an SSL tunnel to your LDAP server. If your LDAP server # doesn't natively support SSL, put a tunnel (wrapper, proxy, # whatever you want to call it) on that system too. This # should prevent the password from traversing the network in # the clear. # .IP "\fBbind_dn (default: empty)\fR" # If you do have to bind, do it with this distinguished name. Example: # .ti +4 # bind_dn = uid=postfix, dc=your, dc=com # .IP "\fBbind_pw (default: empty)\fR" # The password for the distinguished name above. If you have # to use this, you probably want to make the map configuration # file readable only by the Postfix user. When using the # obsolete ldap:ldapsource syntax, with map parameters in # main.cf, it is not possible to securely store the bind # password. This is because main.cf needs to be world readable # to allow local accounts to submit mail via the sendmail # command. Example: # .ti +4 # bind_pw = postfixpw # .IP "\fBcache (IGNORED with a warning)\fR" # .IP "\fBcache_expiry (IGNORED with a warning)\fR" # .IP "\fBcache_size (IGNORED with a warning)\fR" # The above parameters are NO LONGER SUPPORTED by Postfix. # Cache support has been dropped from OpenLDAP as of release # 2.1.13. # .IP "\fBrecursion_limit (default: 1000)\fR" # A limit on the nesting depth of DN and URL special result # attribute evaluation. The limit must be a non-zero positive # number. # .IP "\fBexpansion_limit (default: 0)\fR" # A limit on the total number of result elements returned # (as a comma separated list) by a lookup against the map. # A setting of zero disables the limit. Lookups fail with a # temporary error if the limit is exceeded. Setting the # limit to 1 ensures that lookups do not return multiple # values. # .IP "\fBsize_limit (default: $expansion_limit)\fR" # A limit on the number of LDAP entries returned by any single # LDAP query performed as part of the lookup. A setting of # 0 disables the limit. Expansion of DN and URL references # involves nested LDAP queries, each of which is separately # subjected to this limit. # # Note: even a single LDAP entry can generate multiple lookup # results, via multiple result attributes and/or multi-valued # result attributes. This limit caps the per query resource # utilization on the LDAP server, not the final multiplicity # of the lookup result. It is analogous to the "-z" option # of "ldapsearch". # .IP "\fBdereference (default: 0)\fR" # When to dereference LDAP aliases. (Note that this has # nothing do with Postfix aliases.) The permitted values are # those legal for the OpenLDAP/UM LDAP implementations: # .RS # .IP 0 # never # .IP 1 # when searching # .IP 2 # when locating the base object for the search # .IP 3 # always # .RE # .IP # See ldap.h or the ldap_open(3) or ldapsearch(1) man pages # for more information. And if you're using an LDAP package # that has other possible values, please bring it to the # attention of the postfix-users@postfix.org mailing list. # .IP "\fBchase_referrals (default: 0)\fR" # Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP version # 3 support). # .IP "\fBversion (default: 2)\fR" # Specifies the LDAP protocol version to use. # .IP "\fBdebuglevel (default: 0)\fR" # What level to set for debugging in the OpenLDAP libraries. # LDAP SSL AND STARTTLS PARAMETERS # .ad # .fi # If you're using the OpenLDAP libraries compiled with SSL # support, Postfix can connect to LDAP SSL servers and can # issue the STARTTLS command. # # LDAP SSL service can be requested by using a LDAP SSL URL # in the server_host parameter: # .ti +4 # server_host = ldaps://ldap.your.com:636 # # STARTTLS can be turned on with the start_tls parameter: # .ti +4 # start_tls = yes # # Both forms require LDAP protocol version 3, which has to be set # explicitly with: # .ti +4 # version = 3 # # If any of the Postfix programs querying the map is configured in # master.cf to run chrooted, all the certificates and keys involved # have to be copied to the chroot jail. Of course, the private keys # should only be readable by the user "postfix". # # The following parameters are relevant to LDAP SSL and STARTTLS: # .IP "\fBstart_tls (default: no)\fR" # Whether or not to issue STARTTLS upon connection to the # server. Don't set this with LDAP SSL (the SSL session is setup # automatically when the TCP connection is opened). # .IP "\fBtls_ca_cert_dir (No default; set either this or tls_ca_cert_file)\fR" # Directory containing X509 Certificate Authority certificates # in PEM format which are to be recognized by the client in # SSL/TLS connections. The files each contain one CA certificate. # The files are looked up by the CA subject name hash value, # which must hence be available. If more than one CA certificate # with the same name hash value exist, the extension must be # different (e.g. 9d66eef0.0, 9d66eef0.1 etc). The search is # performed in the ordering of the extension number, regardless # of other properties of the certificates. Use the c_rehash # utility (from the OpenSSL distribution) to create the # necessary links. # .IP "\fBtls_ca_cert_file (No default; set either this or tls_ca_cert_dir)\fR" # File containing the X509 Certificate Authority certificates # in PEM format which are to be recognized by the client in # SSL/TLS connections. This setting takes precedence over # tls_ca_cert_dir. # .IP "\fBtls_cert (No default; you must set this)\fR" # File containing client's X509 certificate to be used by # the client in SSL/ TLS connections. # .IP "\fBtls_key (No default; you must set this)\fR" # File containing the private key corresponding to the above # tls_cert. # .IP "\fBtls_require_cert (default: no)\fR" # Whether or not to request server's X509 certificate and # check its validity when establishing SSL/TLS connections. # .IP "\fBtls_random_file (No default)\fR" # Path of a file to obtain random bits from when /dev/[u]random # is not available, to be used by the client in SSL/TLS # connections. # .IP "\fBtls_cipher_suite (No default)\fR" # Cipher suite to use in SSL/TLS negotiations. # EXAMPLE # .ad # .fi # Here's a basic example for using LDAP to look up local(8) # aliases. # Assume that in main.cf, you have: # .ti +4 # alias_maps = hash:/etc/aliases, # .ti +8 # ldap:/etc/postfix/ldap-aliases.cf # # and in ldap:/etc/postfix/ldap-aliases.cf you have: # .in +4 # server_host = ldap.my.com # .br # search_base = dc=my, dc=com # .in -4 # # Upon receiving mail for a local address "ldapuser" that # isn't found in the /etc/aliases database, Postfix will # search the LDAP server listening at port 389 on ldap.my.com. # It will bind anonymously, search for any directory entries # whose mailacceptinggeneralid attribute is "ldapuser", read # the "maildrop" attributes of those found, and build a list # of their maildrops, which will be treated as RFC822 addresses # to which the message will be delivered. # SEE ALSO # postmap(1), Postfix lookup table manager # postconf(5), configuration parameters # mysql_table(5), MySQL lookup tables # pgsql_table(5), PostgreSQL lookup tables # README FILES # .ad # .fi # Use "\fBpostconf readme_directory\fR" or # "\fBpostconf html_directory\fR" to locate this information. # .na # .nf # DATABASE_README, Postfix lookup table overview # LDAP_README, Postfix LDAP client guide # LICENSE # .ad # .fi # The Secure Mailer license must be distributed with this software. # AUTHOR(S) # .ad # .fi # Carsten Hoeger, # Hery Rakotoarisoa, # John Hensley, # Keith Stevenson, # LaMont Jones, # Liviu Daia, # Manuel Guesdon, # Mike Mattice, # Prabhat K Singh, # Sami Haahtinen, # Samuel Tardieu, # Victor Duchovni, # and many others. #--