457 lines
21 KiB
HTML
457 lines
21 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"http://www.w3.org/TR/html4/loose.dtd">
|
|
<html> <head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
|
<title> Postfix manual - ldap_table(5) </title>
|
|
</head> <body> <pre>
|
|
LDAP_TABLE(5) LDAP_TABLE(5)
|
|
|
|
<b>NAME</b>
|
|
ldap_table - Postfix LDAP client configuration
|
|
|
|
<b>SYNOPSIS</b>
|
|
<b>postmap -q "</b><i>string</i><b>" <a href="ldap_table.5.html">ldap</a>:/etc/postfix/filename</b>
|
|
|
|
<b>postmap -q - <a href="ldap_table.5.html">ldap</a>:/etc/postfix/</b><i>filename</i> <<i>inputfile</i>
|
|
|
|
<b>DESCRIPTION</b>
|
|
The Postfix mail system uses optional tables for address
|
|
rewriting or mail routing. These tables are usually in <b>dbm</b>
|
|
or <b>db</b> 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:
|
|
<a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="ldap_table.5.html">ldap</a>:/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 parame-
|
|
ters described below. An example is given at the end of
|
|
this manual.
|
|
|
|
This configuration method is available with Postfix ver-
|
|
sion 2.1 and later. See the section "BACKWARDS COMPATI-
|
|
BILITY" below for older Postfix versions.
|
|
|
|
For details about LDAP SSL and STARTTLS, see the section
|
|
on SSL and STARTTLS below.
|
|
|
|
<b>BACKWARDS COMPATIBILITY</b>
|
|
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 accessi-
|
|
ble as the name you've given the source in its definition,
|
|
an underscore, and the name of the parameter. For exam-
|
|
ple, if the map is specified as "<a href="ldap_table.5.html">ldap</a>:<i>ldapsource</i>", the
|
|
"server_host" parameter below would be defined in main.cf
|
|
as "<i>ldapsource</i>_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.
|
|
|
|
<b>LIST MEMBERSHIP</b>
|
|
When using LDAP to store lists such as $<a href="postconf.5.html#mynetworks">mynetworks</a>,
|
|
$<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>,
|
|
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 <a href="DATABASE_README.html">DATABASE_README</a> document for a dis-
|
|
cussion.
|
|
|
|
Do NOT create tables that return the full list of domains
|
|
in $<a href="postconf.5.html#mydestination">mydestination</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>.
|
|
|
|
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 $<a href="postconf.5.html#mydestination">mydestina</a>-
|
|
<a href="postconf.5.html#mydestination">tion</a>:
|
|
query_filter = domain=*
|
|
result_attribute = domain
|
|
|
|
Do this instead:
|
|
query_filter = domain=%s
|
|
result_attribute = domain
|
|
|
|
<b>GENERAL LDAP PARAMETERS</b>
|
|
In the text below, default values are given in parenthe-
|
|
ses. Note: don't use quotes in these variables; at least,
|
|
not until the Postfix configuration routines understand
|
|
how to deal with quoted strings.
|
|
|
|
<b>server_host (default: localhost)</b>
|
|
The name of the host running the LDAP server, e.g.
|
|
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 <b>server_port</b> below), by naming them like
|
|
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):
|
|
server_host = <a href="ldap_table.5.html">ldap</a>://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):
|
|
server_host = ldapi://%2Fsome%2Fpath
|
|
server_host = ldaps://ldap.your.com:636
|
|
|
|
<b>server_port (default: 389)</b>
|
|
The port the LDAP server listens on, e.g.
|
|
server_port = 778
|
|
|
|
<b>search_base (No default; you must configure this)</b>
|
|
The <a href="http://www.faqs.org/rfcs/rfc2253.html">RFC2253</a> base DN at which to conduct the search,
|
|
e.g.
|
|
search_base = dc=your, dc=com
|
|
|
|
<b>timeout (default: 10 seconds)</b>
|
|
The number of seconds a search can take before tim-
|
|
ing out, e.g.
|
|
timeout = 5
|
|
|
|
<b>query_filter (default: mailacceptinggeneralid=%s)</b>
|
|
The <a href="http://www.faqs.org/rfcs/rfc2254.html">RFC2254</a> filter used to search the directory,
|
|
where <b>%s</b> is a substitute for the address Postfix is
|
|
trying to resolve, e.g.
|
|
query_filter = (&(mail=%s)(paid_up=true))
|
|
|
|
This parameter supports the following '%' expan-
|
|
sions:
|
|
|
|
<b>%s</b> This is replaced by the input key. <a href="http://www.faqs.org/rfcs/rfc2254.html">RFC 2254</a>
|
|
quoting is used to make sure that the input
|
|
key does not add unexpected metacharacters.
|
|
|
|
<b>%u</b> When the input key is an address of the form
|
|
user@domain, <b>%u</b> is replaced by the (RFC
|
|
2254) quoted local part of the address. If
|
|
no domain is specified, <b>%u</b> is replaced by
|
|
the entire search string.
|
|
|
|
<b>%d</b> When the input key is an address of the form
|
|
user@domain, <b>%d</b> is replaced by the (RFC
|
|
2254) quoted domain part of the address.
|
|
When the input key has no domain qualifier,
|
|
<b>%d</b> is replaced by the entire search string.
|
|
|
|
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.
|
|
|
|
<b>result_filter (default: %s</b>)
|
|
Format template applied to result attributes. Sup-
|
|
ports the same expansions as the query_filter, and
|
|
can be easily used to append (or prepend) text.
|
|
This parameter supports the following '%' expan-
|
|
sions:
|
|
|
|
<b>%s</b> This is replaced by the value of the result
|
|
attribute.
|
|
|
|
<b>%u</b> When the result attribute is an address of
|
|
the form user@domain, <b>%u</b> is replaced local
|
|
part of the address, if the result attribute
|
|
is unqualified, <b>%u</b> is replaced by the entire
|
|
attribute value.
|
|
|
|
<b>%d</b> When a result attribute is an address of the
|
|
form user@domain, <b>%d</b> is replaced by the
|
|
domain part of the attribute value. If an
|
|
attribute value is unqualified <b>%d</b> is
|
|
replaced by the entire attribute value.
|
|
|
|
For example, using "result_filter = <a href="smtp.8.html">smtp</a>:[%s]"
|
|
allows one to use a mailHost attribute as the basis
|
|
of a <a href="transport.5.html">transport(5)</a> 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 <b>%s</b> specifies that each attribute
|
|
value should be used as is.
|
|
|
|
NOTE: DO NOT put quotes around the result filter!
|
|
|
|
<b>domain (default: no domain list)</b>
|
|
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.
|
|
domain = postfix.org, hash:/etc/postfix/search-
|
|
domains
|
|
|
|
It is best not to use LDAP to store the domains
|
|
eligible for LDAP lookups.
|
|
|
|
NOTE: DO NOT define this parameter for <a href="local.8.html">local(8)</a>
|
|
aliases.
|
|
|
|
<b>result_attribute (default: maildrop)</b>
|
|
The attribute(s) Postfix will read from any direc-
|
|
tory entries returned by the lookup, to be resolved
|
|
to an email address.
|
|
result_attribute = mailbox,maildrop
|
|
|
|
<b>special_result_attribute (No default)</b>
|
|
The attribute(s) of directory entries that can con-
|
|
tain DNs or URLs. If found, a recursive subsequent
|
|
search is done using their values.
|
|
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.
|
|
|
|
<b>scope (default: sub)</b>
|
|
The LDAP search scope: <b>sub</b>, <b>base</b>, or <b>one</b>. These
|
|
translate into LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE,
|
|
and LDAP_SCOPE_ONELEVEL.
|
|
|
|
<b>bind (default: yes)</b>
|
|
Whether or not to bind to the LDAP server. Newer
|
|
LDAP implementations don't require clients to bind,
|
|
which saves time. Example:
|
|
bind = no
|
|
|
|
If you do need to bind, you might consider config-
|
|
uring 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.
|
|
|
|
<b>bind_dn (default: empty)</b>
|
|
If you do have to bind, do it with this distin-
|
|
guished name. Example:
|
|
bind_dn = uid=postfix, dc=your, dc=com
|
|
|
|
<b>bind_pw (default: empty)</b>
|
|
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 <a href="ldap_table.5.html">ldap</a>:ldapsource syn-
|
|
tax, with map parameters in main.cf, it is not pos-
|
|
sible 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 com-
|
|
mand. Example:
|
|
bind_pw = postfixpw
|
|
|
|
<b>cache (IGNORED with a warning)</b>
|
|
|
|
<b>cache_expiry (IGNORED with a warning)</b>
|
|
|
|
<b>cache_size (IGNORED with a warning)</b>
|
|
The above parameters are NO LONGER SUPPORTED by
|
|
Postfix. Cache support has been dropped from
|
|
OpenLDAP as of release 2.1.13.
|
|
|
|
<b>recursion_limit (default: 1000)</b>
|
|
A limit on the nesting depth of DN and URL special
|
|
result attribute evaluation. The limit must be a
|
|
non-zero positive number.
|
|
|
|
<b>expansion_limit (default: 0)</b>
|
|
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.
|
|
|
|
<b>size_limit (default: $expansion_limit)</b>
|
|
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. Expan-
|
|
sion 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 multi-
|
|
ple 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".
|
|
|
|
<b>dereference (default: 0)</b>
|
|
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:
|
|
|
|
0 never
|
|
|
|
1 when searching
|
|
|
|
2 when locating the base object for the search
|
|
|
|
3 always
|
|
|
|
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.
|
|
|
|
<b>chase_referrals (default: 0)</b>
|
|
Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP
|
|
version 3 support).
|
|
|
|
<b>version (default: 2)</b>
|
|
Specifies the LDAP protocol version to use.
|
|
|
|
<b>debuglevel (default: 0)</b>
|
|
What level to set for debugging in the OpenLDAP
|
|
libraries.
|
|
|
|
<b>LDAP SSL AND STARTTLS PARAMETERS</b>
|
|
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:
|
|
server_host = ldaps://ldap.your.com:636
|
|
|
|
STARTTLS can be turned on with the start_tls parameter:
|
|
start_tls = yes
|
|
|
|
Both forms require LDAP protocol version 3, which has to
|
|
be set explicitly with:
|
|
version = 3
|
|
|
|
If any of the Postfix programs querying the map is config-
|
|
ured 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:
|
|
|
|
<b>start_tls (default: no)</b>
|
|
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 connec-
|
|
tion is opened).
|
|
|
|
<b>tls_ca_cert_dir (No default; set either this or</b>
|
|
<b>tls_ca_cert_file)</b>
|
|
Directory containing X509 Certificate Authority
|
|
certificates in PEM format which are to be recog-
|
|
nized 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.
|
|
|
|
<b>tls_ca_cert_file (No default; set either this or</b>
|
|
<b>tls_ca_cert_dir)</b>
|
|
File containing the X509 Certificate Authority cer-
|
|
tificates in PEM format which are to be recognized
|
|
by the client in SSL/TLS connections. This setting
|
|
takes precedence over tls_ca_cert_dir.
|
|
|
|
<b>tls_cert (No default; you must set this)</b>
|
|
File containing client's X509 certificate to be
|
|
used by the client in SSL/ TLS connections.
|
|
|
|
<b>tls_key (No default; you must set this)</b>
|
|
File containing the private key corresponding to
|
|
the above tls_cert.
|
|
|
|
<b>tls_require_cert (default: no)</b>
|
|
Whether or not to request server's X509 certificate
|
|
and check its validity when establishing SSL/TLS
|
|
connections.
|
|
|
|
<b>tls_random_file (No default)</b>
|
|
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.
|
|
|
|
<b>tls_cipher_suite (No default)</b>
|
|
Cipher suite to use in SSL/TLS negotiations.
|
|
|
|
<b>EXAMPLE</b>
|
|
Here's a basic example for using LDAP to look up <a href="local.8.html">local(8)</a>
|
|
aliases. Assume that in main.cf, you have:
|
|
<a href="postconf.5.html#alias_maps">alias_maps</a> = hash:/etc/aliases,
|
|
<a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf
|
|
|
|
and in <a href="ldap_table.5.html">ldap</a>:/etc/postfix/ldap-aliases.cf you have:
|
|
server_host = ldap.my.com
|
|
search_base = dc=my, dc=com
|
|
|
|
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 <a href="http://www.faqs.org/rfcs/rfc822.html">RFC822</a> addresses to which the message will be
|
|
delivered.
|
|
|
|
<b>SEE ALSO</b>
|
|
<a href="postmap.1.html">postmap(1)</a>, Postfix lookup table manager
|
|
<a href="postconf.5.html">postconf(5)</a>, configuration parameters
|
|
<a href="mysql_table.5.html">mysql_table(5)</a>, MySQL lookup tables
|
|
<a href="pgsql_table.5.html">pgsql_table(5)</a>, PostgreSQL lookup tables
|
|
|
|
<b>README FILES</b>
|
|
<a href="DATABASE_README.html">DATABASE_README</a>, Postfix lookup table overview
|
|
<a href="LDAP_README.html">LDAP_README</a>, Postfix LDAP client guide
|
|
|
|
<b>LICENSE</b>
|
|
The Secure Mailer license must be distributed with this
|
|
software.
|
|
|
|
<b>AUTHOR(S)</b>
|
|
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.
|
|
|
|
LDAP_TABLE(5)
|
|
</pre> </body> </html>
|