NetBSD/gnu/dist/postfix/proto/ldap_table
2006-07-19 01:16:27 +00:00

530 lines
21 KiB
Plaintext

#++
# 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.
#
# Postfix 2.2 has enhanced query interfaces for MySQL and PostgreSQL.
# These include features that were previously available only in the
# Postfix LDAP client. This work also created an opportunity for
# improvements in the LDAP interface. The primary compatibility
# issue is that \fBresult_filter\fR (a name that has caused some
# confusion as to its meaning in the past) has been renamed to
# \fBresult_format\fR. For backwards compatibility with the pre
# 2.2 LDAP client, \fBresult_filter\fR can for now be used instead
# of \fBresult_format\fR, when the latter parameter is not also set.
# The new name better reflects the function of the parameter. This
# compatibility interface may be removed in a future release.
# 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.example.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.example.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.example.com:1444
# .ti +8
# ldap://ldap2.example.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 +8
# ldaps://ldap.example.com:636
# .IP "\fBserver_port (default: 389)\fR"
# The port the LDAP server listens on, e.g.
# .ti +4
# server_port = 778
# .IP "\fBtimeout (default: 10 seconds)\fR"
# The number of seconds a search can take before timing out, e.g.
# .ti +4
# timeout = 5
# .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
# With Postfix 2.2 and later this parameter supports the
# following '%' expansions:
# .RS
# .IP "\fB\fB%%\fR\fR"
# This is replaced by a literal '%' character.
# .IP "\fB\fB%s\fR\fR"
# This is replaced by the input key.
# RFC 2253 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 2253) quoted local part of the address.
# Otherwise, \fB%u\fR is replaced by the entire search string.
# If the localpart is empty, the search is suppressed and returns
# no results.
# .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 2253) quoted domain part of the address.
# Otherwise, the search is suppressed and returns no results.
# .IP "\fB\fB%[SUD]\fR\fR"
# For the \fBsearch_base\fR parameter, the upper-case equivalents
# of the above expansions behave identically to their lower-case
# counter-parts. With the \fBresult_format\fR parameter (previously
# called \fBresult_filter\fR see the COMPATIBILITY section and below),
# they expand to the corresponding components of input key rather
# than the result value.
# .IP "\fB\fB%[1-9]\fR\fR"
# The patterns %1, %2, ... %9 are replaced by the corresponding
# most significant component of the input key's domain. If the
# input key is \fIuser@mail.example.com\fR, then %1 is \fBcom\fR,
# %2 is \fBexample\fR and %3 is \fBmail\fR. If the input key is
# unqualified or does not have enough domain components to satisfy
# all the specified patterns, the search is suppressed and returns
# no results.
# .RE
# .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%%\fR\fR"
# This is replaced by a literal '%' character. (Postfix 2.2 and later).
# .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.
# Otherwise, \fB%u\fR is replaced by the entire search string.
# If the localpart is empty, the search is suppressed and returns
# no results.
# .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.
# Otherwise, the search is suppressed and returns no results.
# .IP "\fB\fB%[SUD]\fR\fR"
# The upper-case equivalents of the above expansions behave in the
# \fBquery_filter\fR parameter identically to their lower-case
# counter-parts. With the \fBresult_format\fR parameter (previously
# called \fBresult_filter\fR see the COMPATIBILITY section and below),
# they expand to the corresponding components of input key rather
# than the result value.
# .IP
# The above %S, %U and %D expansions are available with Postfix 2.2
# and later.
# .IP "\fB\fB%[1-9]\fR\fR"
# The patterns %1, %2, ... %9 are replaced by the corresponding
# most significant component of the input key's domain. If the
# input key is \fIuser@mail.example.com\fR, then %1 is \fBcom\fR,
# %2 is \fBexample\fR and %3 is \fBmail\fR. If the input key is
# unqualified or does not have enough domain components to satisfy
# all the specified patterns, the saerch is suppressed and returns
# no results.
# .IP
# The above %1, ..., %9 expansions are available with Postfix 2.2
# and later.
# .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 \fBquery_filter\fR parameter.
# .IP "\fBresult_format (default: \fB%s\fR)\fR"
# Called \fBresult_filter\fR in Postfix releases prior to 2.2.
# Format template applied to result attributes. Most commonly used
# to append (or prepend) text to the result. This parameter supports
# the following '%' expansions:
# .RS
# .IP "\fB\fB%%\fR\fR"
# This is replaced by a literal '%' character. (Postfix 2.2 and later).
# .IP "\fB\fB%s\fR\fR"
# This is replaced by the value of the result attribute. When
# result is empty it is skipped.
# .IP "\fB%u\fR
# When the result attribute value is an address of the form
# user@domain, \fB%u\fR is replaced by the local part of the
# address. When the result has an empty localpart it is skipped.
# .IP "\fB\fB%d\fR\fR"
# When a result attribute value is an address of the form
# user@domain, \fB%d\fR is replaced by the domain part of
# the attribute value. When the result is unqualified it
# is skipped.
# .IP "\fB\fB%[SUD1-9]\fR\fB"
# The upper-case and decimal digit expansions interpolate
# the parts of the input key rather than the result. Their
# behavior is identical to that described with \fBquery_filter\fR,
# and in fact because the input key is known in advance, lookups
# whose key does not contain all the information specified in
# the result template are suppressed and return no results.
# .IP
# The above %S, %U, %D and %1, ..., %9 expansions are available with
# Postfix 2.2 and later.
# .RE
# .IP
# For example, using "result_format = smtp:[%s]" allows one
# to use a mailHost attribute as the basis of a transport(5)
# table. After applying the result format, 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.
#
# This parameter was called \fBresult_filter\fR in Postfix
# releases prior to 2.2. If no "result_format" is specified,
# the value of "result_filter" will be used instead before
# resorting to the default value. This provides compatibility
# with old configuration files.
#
# NOTE: DO NOT put quotes around the result format!
# .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.
#
# This feature is available in Postfix 1.0 and later.
# .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 search 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 search 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.example.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.
#--