#++
# 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.
#--