title: ldap_table(5)

text:
# ldap_table(5)

## NAME
ldap_table - Postfix LDAP client configuration

## SYNOPSIS

```
postmap -q "string" ldap:/etc/postfix/filename
postmap -q - ldap:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting or mail routing. These tables are usually in dbm or db 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:

```
    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 "OBSOLETE MAIN.CF PARAMETERS" below for older Postfix versions.

For details about LDAP SSL and STARTTLS, see the section on SSL and STARTTLS below.

## LIST MEMBERSHIP

```

```

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:

```
    query_filter = domain=*

    result_attribute = domain
```

Do this instead:

```
    query_filter = domain=%s

    result_attribute = domain
```

## GENERAL LDAP PARAMETERS

```

```

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.

server_host (default: localhost)

The name of the host running the LDAP server, e.g.

```
    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 server_port below), by naming them like

```
    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):

```
    server_host = ldap://ldap.example.com:1444

                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):

```
    server_host = ldapi://%2Fsome%2Fpath

                ldaps://ldap.example.com:636
```

server_port (default: 389)

The port the LDAP server listens on, e.g.

```
    server_port = 778
```

timeout (default: 10 seconds)

The number of seconds a search can take before timing out, e.g.

timeout = 5

search_base (No default; you must configure this)

The RFC2253 base DN at which to conduct the search, e.g.

```
    search_base = dc=your, dc=com
```

With Postfix 2.2 and later this parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character.

%s

This is replaced by the input key. RFC 2253 quoting is used to make sure that the input key does not add unexpected metacharacters.

%u

When the input key is an address of the form user@domain, %u is replaced by the (RFC 2253) quoted local part of the address. Otherwise, %u is replaced by the entire search string. If the localpart is empty, the search is suppressed and returns no results.

%d

When the input key is an address of the form user@domain, %d is replaced by the (RFC 2253) quoted domain part of the address. Otherwise, the search is suppressed and returns no results.

%[SUD]

For the search_base parameter, the upper-case equivalents of the above expansions behave identically to their lower-case counter-parts. With the result_format parameter (previously called result_filter see the OTHER OBSOLETE FEATURES section and below), they expand to the corresponding components of input key rather than the result value.

%[1-9]

The patterns %1, %2, ... %9 are replaced by the corresponding most significant component of the input key's domain. If the input key is user@mail.example.com, then %1 is com, %2 is example and %3 is mail. 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.

query_filter (default: mailacceptinggeneralid=%s)

The RFC2254 filter used to search the directory, where %s 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 '%' expansions:

%%

This is replaced by a literal '%' character. (Postfix 2.2 and later).

%s

This is replaced by the input key. RFC 2254 quoting is used to make sure that the input key does not add unexpected metacharacters.

%u

When the input key is an address of the form user@domain, %u is replaced by the (RFC 2254) quoted local part of the address. Otherwise, %u is replaced by the entire search string. If the localpart is empty, the search is suppressed and returns no results.

%d

When the input key is an address of the form user@domain, %d is replaced by the (RFC 2254) quoted domain part of the address. Otherwise, the search is suppressed and returns no results.

%[SUD]

The upper-case equivalents of the above expansions behave in the query_filter parameter identically to their lower-case counter-parts. With the result_format parameter (previously called result_filter see the OTHER OBSOLETE FEATURES section and below), they expand to the corresponding components of input key rather than the result value.

The above %S, %U and %D expansions are available with Postfix 2.2 and later.

%[1-9]

The patterns %1, %2, ... %9 are replaced by the corresponding most significant component of the input key's domain. If the input key is user@mail.example.com, then %1 is com, %2 is example and %3 is mail. 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.

The above %1, ..., %9 expansions are available with Postfix 2.2 and later.

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 parameter.

result_format (default: %s)

Called result_filter 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:

%%

This is replaced by a literal '%' character. (Postfix 2.2 and later).

%s

This is replaced by the value of the result attribute. When result is empty it is skipped.

%u

When the result attribute value is an address of the form user@domain, %u is replaced by the local part of the address. When the result has an empty localpart it is skipped.

%d

When a result attribute value is an address of the form user@domain, %d is replaced by the domain part of the attribute value. When the result is unqualified it is skipped.

%[SUD1-9]

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 query_filter, 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.

The above %S, %U, %D and %1, ..., %9 expansions are available with Postfix 2.2 and later.

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 %s specifies that each attribute value should be used as is.

This parameter was called result_filter 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!

domain (default: no domain list)

This is a list of domain names, paths to files, or "type:table" databases. 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/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.

result_attribute (default: maildrop)

The attribute(s) Postfix will read from any directory entries returned by the lookup, to be resolved to an email address.

```
    result_attribute = mailbox, maildrop
```

Don't rely on the default value ("maildrop"). Set the result_attribute explicitly in all ldap table configuration files. This is particularly relevant when no result_attribute is applicable, e.g. cases in which leaf_result_attribute and/or terminal_result_attribute are used instead. The default value is harmless if "maildrop" is also listed as a leaf or terminal result attribute, but it is best to not leave this to chance.

special_result_attribute (default: empty)

The attribute(s) of directory entries that can contain DNs or RFC 2255 LDAP URLs. If found, a recursive search is performed to retrieve the entry referenced by the DN, or the entries matched by the URL query.

```
    special_result_attribute = memberdn
```

DN recursion retrieves the same result_attributes as the main query, including the special attributes for further recursion.

URL processing retrieves only those attributes that are included in both the URL definition and as result attributes (ordinary, special, leaf or terminal) in the Postfix table definition. If the URL lists any of the table's special result attributes, these are retrieved and used recursively. A URL that does not specify any attribute selection, is equivalent (RFC 2255) to a URL that selects all attributes, in which case the selected attributes will be the full set of result attributes in the Postfix table.

If an LDAP URL attribute-descriptor or the corresponding Postfix LDAP table result attribute (but not both) uses RFC 2255 sub-type options ("attr;option"), the attribute requested from the LDAP server will include the sub-type option. In all other cases, the URL attribute and the table attribute must match exactly. Attributes with options in both the URL and the Postfix table are requested only when the options are identical. LDAP attribute-descriptor options are very rarely used, most LDAP users will not need to concern themselves with this level of nuanced detail.

terminal_result_attribute (default: empty)

When one or more terminal result attributes are found in an LDAP entry, all other result attributes are ignored and only the terminal result attributes are returned. This is useful for delegating expansion of group members to a particular host, by using an optional "maildrop" attribute on selected groups to route the group to a specific host, where the group is expanded, possibly via mailing-list manager or other special processing.

```
    result_attribute =

    terminal_result_attribute = maildrop
```

When using terminal and/or leaf result attributes, the result_attribute is best set to an empty value when it is not used, or else explicitly set to the desired value, even if it is the default value "maildrop".

This feature is available with Postfix 2.4 or later.

leaf_result_attribute (default: empty)

When one or more special result attributes are found in a non-terminal (see above) LDAP entry, leaf result attributes are excluded from the expansion of that entry. This is useful when expanding groups and the desired mail address attribute(s) of the member objects obtained via DN or URI recursion are also present in the group object. To only return the attribute values from the leaf objects and not the containing group, add the attribute to the leaf_result_attribute list, and not the result_attribute list, which is always expanded. Note, the default value of "result_attribute" is not empty, you may want to set it explicitly empty when using "leaf_result_attribute" to expand the group to a list of member DN addresses. If groups have both member DN references AND attributes that hold multiple string valued rfc822 addresses, then the string attributes go in "result_attribute". The attributes that represent the email addresses of objects referenced via a DN (or LDAP URI) go in "leaf_result_attribute".

```
    result_attribute = memberaddr

    special_result_attribute = memberdn

    terminal_result_attribute = maildrop

    leaf_result_attribute = mail
```

When using terminal and/or leaf result attributes, the result_attribute is best set to an empty value when it is not used, or else explicitly set to the desired value, even if it is the default value "maildrop".

This feature is available with Postfix 2.4 or later.

scope (default: sub)

The LDAP search scope: sub, base, or one. These translate into LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE, and LDAP_SCOPE_ONELEVEL.

bind (default: yes)

Whether or how to bind to the LDAP server. Newer LDAP implementations don't require clients to bind, which saves time. Example:

```
    # Don't bind

    bind = no

    # Use SIMPLE bind

    bind = yes

    # Use SASL bind

    bind = sasl
```

Postfix versions prior to 2.8 only support "bind = no" which means don't bind, and "bind = yes" which means do a SIMPLE bind. Postfix 2.8 and later also supports "bind = SASL" when compiled with LDAP SASL support as described in LDAP_README, it also adds the synonyms "bind = none" and "bind = simple" for "bind = no" and "bind = yes" respectively. See the SASL section below for additional parameters available with "bind = sasl".

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.

bind_dn (default: empty)

If you do have to bind, do it with this distinguished name. Example:

```
    bind_dn = uid=postfix, dc=your, dc=com
```

With "bind = sasl" (see above) the DN may be optional for some SASL mechanisms, don't specify a DN if not needed.

bind_pw (default: empty)

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:

```
    bind_pw = postfixpw
```

With "bind = sasl" (see above) the password may be optional for some SASL mechanisms, don't specify a password if not needed.

cache (IGNORED with a warning)

cache_expiry (IGNORED with a warning)

cache_size (IGNORED with a warning)

The above parameters are NO LONGER SUPPORTED by Postfix. Cache support has been dropped from OpenLDAP as of release 2.1.13.

recursion_limit (default: 1000)

A limit on the nesting depth of DN and URL special result attribute evaluation. The limit must be a non-zero positive number.

expansion_limit (default: 0)

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.

size_limit (default: $expansion_limit)

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".

dereference (default: 0)

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.

chase_referrals (default: 0)

Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP version 3 support).

version (default: 2)

Specifies the LDAP protocol version to use.

debuglevel (default: 0)

What level to set for debugging in the OpenLDAP libraries.

## LDAP SASL PARAMETERS

```

```

If you're using the OpenLDAP libraries compiled with SASL support, Postfix 2.8 and later built with LDAP SASL support as described in LDAP_README can authenticate to LDAP servers via SASL.

This enables authentication to the LDAP server via mechanisms other than a simple password. The added flexibility has a cost: it is no longer practical to set an explicit timeout on the duration of an LDAP bind operation. Under adverse conditions, whether a SASL bind times out, or if it does, the duration of the timeout is determined by the LDAP and SASL libraries.

It is best to use tables that use SASL binds via proxymap(8), this way the requesting process can time-out the proxymap request. This also lets you tailer the process environment by overriding the proxymap(8) import_environment setting in master.cf(5). Special environment settings may be needed to configure GSSAPI credential caches or other SASL mechanism specific options. The GSSAPI credentials used for LDAP lookups may need to be different than say those used for the Postfix SMTP client to authenticate to remote servers.

Using SASL mechanisms requires LDAP protocol version 3, the default protocol version is 2 for backwards compatibility. You must set "version = 3" in addition to "bind = sasl".

The following parameters are relevant to using LDAP with SASL

sasl_mechs (default: empty)

Space separated list of SASL mechanism(s) to try.

sasl_realm (default: empty)

SASL Realm to use, if applicable.

sasl_authz_id (default: empty)

The SASL authorization identity to assert, if applicable.

sasl_minssf (default: 0)

The minimum required sasl security factor required to establish a connection.

## LDAP SSL AND STARTTLS PARAMETERS

```

```

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.example.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 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:

start_tls (default: no)

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).

tls_ca_cert_dir (No default; set either this or tls_ca_cert_file)

Directory containing X509 Certification 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.

tls_ca_cert_file (No default; set either this or tls_ca_cert_dir)

File containing the X509 Certification 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.

tls_cert (No default; you must set this)

File containing client's X509 certificate to be used by the client in SSL/ TLS connections.

tls_key (No default; you must set this)

File containing the private key corresponding to the above tls_cert.

tls_require_cert (default: no)

Whether or not to request server's X509 certificate and check its validity when establishing SSL/TLS connections. The supported values are no and yes. With no, the server certificate trust chain is not checked, but with OpenLDAP prior to 2.1.13, the name in the server certificate must still match the LDAP server name. With OpenLDAP 2.0.0 to 2.0.11 the server name is not necessarily what you specified, rather it is determined (by reverse lookup) from the IP address of the LDAP server connection. With OpenLDAP prior to 2.0.13, subjectAlternativeName extensions in the LDAP server certificate are ignored: the server name must match the subject CommonName. The no setting corresponds to the never value of TLS_REQCERT in LDAP client configuration files.

Don't use TLS with OpenLDAP 2.0.x (and especially with x <= 11) if you can avoid it.

With yes, the server certificate must be issued by a trusted CA, and not be expired. The LDAP server name must match one of the name(s) found in the certificate (see above for OpenLDAP library version dependent behavior). The yes setting corresponds to the demand value of TLS_REQCERT in LDAP client configuration files.

The "try" and "allow" values of TLS_REQCERT have no equivalents here. They are not available with OpenLDAP 2.0, and in any case have questionable security properties. Either you want TLS verified LDAP connections, or you don't.

The yes value only works correctly with Postfix 2.5 and later, or with OpenLDAP 2.0. Earlier Postfix releases or later OpenLDAP releases don't work together with this setting. Support for LDAP over TLS was added to Postfix based on the OpenLDAP 2.0 API.

tls_random_file (No default)

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.

tls_cipher_suite (No default)

Cipher suite to use in SSL/TLS negotiations.

## EXAMPLE

```

```

Here's a basic example for using LDAP to look up local(8) aliases. Assume that in main.cf, you have:

```
    alias_maps = hash:/etc/aliases,

            ldap:/etc/postfix/ldap-aliases.cf
```

and in ldap:/etc/postfix/ldap-aliases.cf you have:

```
    server_host = ldap.example.com

    search_base = dc=example, 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.example.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.

## OBSOLETE MAIN.CF PARAMETERS

```

```

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:ldapsource", the "server_host" parameter below would be defined in main.cf as "ldapsource_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.

## OTHER OBSOLETE FEATURES

```

```

result_filter (No default)

For backwards compatibility with the pre 2.2 LDAP clients, result_filter can for now be used instead of result_format, 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.

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

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
LDAP_README, Postfix LDAP client guide
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```

```

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.


package: postfix

title: lmdb_table(5)

text:
# lmdb_table(5)

## NAME
lmdb_table - Postfix LMDB adapter

## SYNOPSIS

```
postmap lmdb:/etc/postfix/filename

postmap -i lmdb:/etc/postfix/filename <inputfile
postmap -d "key" lmdb:/etc/postfix/filename

postmap -d - lmdb:/etc/postfix/filename <inputfile
postmap -q "key" lmdb:/etc/postfix/filename

postmap -q - lmdb:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix LMDB adapter provides access to a persistent, memory-mapped, key-value store. The database size is limited only by the size of the memory address space (typically 31 or 47 bits on 32-bit or 64-bit CPUs, respectively) and by the available file system space.

## REQUESTS

```

```

The LMDB adapter supports all Postfix lookup table operations. This makes LMDB suitable for Postfix address rewriting, routing, access policies, caches, or any information that can be stored under a fixed lookup key.

When a transaction fails due to a full database, Postfix resizes the database and retries the transaction.

Postfix table lookups may generate partial search keys such as domain names without one or more subdomains, network addresses without one or more least-significant octets, or email addresses without the localpart, address extension or domain portion. This behavior is also found with, for example, btree:, hash:, or ldap: tables.

Changes to an LMDB database do not trigger an automatic daemon restart, and do not require a daemon restart with "postfix reload".

## RELIABILITY

```

```

LMDB's copy-on-write architecture provides safe updates, at the cost of using more space than some other flat-file databases. Read operations are memory-mapped for speed. Write operations are not memory-mapped to avoid silent corruption due to stray pointer bugs.

Multiple processes can safely update an LMDB database without serializing requests through the proxymap(8) service. This makes LMDB suitable as a shared cache for verify(8) or postscreen(8) services.

## SYNCHRONIZATION

```

```

The Postfix LMDB adapter does not use LMDB's built-in locking scheme, because that would require world-writable lockfiles and would violate the Postfix security model. Instead, Postfix uses fcntl(2) locks with whole-file granularity. Programs that use LMDB's built-in locking protocol will corrupt a Postfix LMDB database or will read garbage.

Every Postfix LMDB database read or write transaction must be protected from start to end with a shared or exclusive fcntl(2) lock. A writer may atomically downgrade an exclusive lock to a shared lock, but it must hold an exclusive lock while opening another write transaction.

Note that fcntl(2) locks do not protect transactions within the same process against each other. If a program cannot avoid making simultaneous database requests, then it must protect its transactions with in-process locks, in addition to the per-process fcntl(2) locks.

## CONFIGURATION PARAMETERS

```

```

Short-lived programs automatically pick up changes to main.cf. With long-running daemon programs, Use the command "postfix reload" after a configuration change.

lmdb_map_size (16777216)

The initial OpenLDAP LMDB database size limit in bytes.

## SEE ALSO

```
postconf(1), Postfix supported lookup tables
postmap(1), Postfix lookup table maintenance
postconf(5), configuration parameters
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
LMDB_README, Postfix OpenLDAP LMDB howto
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## HISTORY

LMDB support was introduced with Postfix version 2.11.

## AUTHOR(S)

```
Howard Chu
Symas Corporation
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```

branch: sisyphus


master

title: master(5)

text:
# master(5)

## NAME
master - Postfix master process configuration file format

## DESCRIPTION

The Postfix mail system is implemented by small number of (mostly) client commands that are invoked by users, and by a larger number of services that run in the background.

Postfix services are implemented by daemon processes. These run in the background, started on-demand by the master(8) process. The master.cf configuration file defines how a client program connects to a service, and what daemon program runs when a service is requested. Most daemon processes are short-lived and terminate voluntarily after serving max_use clients, or after inactivity for max_idle or more units of time.

All daemons specified here must speak a Postfix-internal protocol. In order to execute non-Postfix software use the local(8), pipe(8) or spawn(8) services, or execute the software with inetd(8) or equivalent.

After changing master.cf you must execute "postfix reload" to reload the configuration.

## SYNTAX

```

```

The general format of the master.cf file is as follows:

- Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a `#'.

- A logical line starts with non-whitespace text. A line that starts with whitespace continues a logical line.

- Each logical line defines a single Postfix service. Each service is identified by its name and type as described below. When multiple lines specify the same service name and type, only the last one is remembered. Otherwise, the order of master.cf service definitions does not matter.

Each logical line consists of eight fields separated by whitespace. These are described below in the order as they appear in the master.cf file.

Where applicable a field of "-" requests that the built-in default value be used. For boolean fields specify "y" or "n" to override the default value.

Service name

The service name syntax depends on the service type as described next.

Service type

Specify one of the following service types:

inet

The service listens on a TCP/IP socket and is accessible via the network. The service name is specified as host:port, denoting the host and port on which new connections should be accepted. The host part (and colon) may be omitted. Either host or port may be given in symbolic form (see hosts(5) or services(5)) or in numeric form (IP address or port number). Host information may be enclosed inside "[]"; this form is necessary only with IPv6 addresses.

Examples: a service named 127.0.0.1:smtp or ::1:smtp receives mail via the loopback interface only; and a service named 10025 accepts connections on TCP port 10025 via all interfaces configured with the inet_interfaces parameter.

Note: with Postfix version 2.2 and later specify "inet_interfaces = loopback-only" in main.cf, instead of hard-coding loopback IP address information in master.cf or in main.cf.

unix

The service listens on a UNIX-domain stream socket and is accessible for local clients only. The service name is a pathname relative to the Postfix queue directory (pathname controlled with the queue_directory configuration parameter in main.cf).

On Solaris 8 and earlier systems the unix type is implemented with streams sockets.

unix-dgram

The service listens on a UNIX-domain datagram socket and is accessible for local clients only. The service name is a pathname relative to the Postfix queue directory (pathname controlled with the queue_directory configuration parameter in main.cf).

fifo (obsolete)

The service listens on a FIFO (named pipe) and is accessible for local clients only. The service name is a pathname relative to the Postfix queue directory (pathname controlled with the queue_directory configuration parameter in main.cf).

pass

The service listens on a UNIX-domain stream socket, and is accessible to local clients only. It receives one open connection (file descriptor passing) per connection request. The service name is a pathname relative to the Postfix queue directory (pathname controlled with the queue_directory configuration parameter in main.cf).

On Solaris 8 and earlier systems the pass type is implemented with streams sockets.

This feature is available as of Postfix version 2.5.

Private (default: y)

Whether a service is internal to Postfix (pathname starts with private/), or exposed through Postfix command-line tools (pathname starts with public/). Internet (type inet) services can't be private.

Unprivileged (default: y)

Whether the service runs with root privileges or as the owner of the Postfix system (the owner name is controlled by the mail_owner configuration variable in the main.cf file). The local(8), pipe(8), spawn(8), and virtual(8) daemons require privileges.

Chroot (default: Postfix >= 3.0: n, Postfix < 3.0: y)

Whether or not the service runs chrooted to the mail queue directory (pathname is controlled by the queue_directory configuration variable in the main.cf file). Chroot should not be used with the local(8), pipe(8), spawn(8), and virtual(8) daemons. Although the proxymap(8) server can run chrooted, doing so defeats most of the purpose of having that service in the first place.

The files in the examples/chroot-setup subdirectory of the Postfix source show how to set up a Postfix chroot environment on a variety of systems. See also BASIC_CONFIGURATION_README for issues related to running daemons chrooted.

Wake up time (default: 0)

Automatically wake up the named service after the specified number of seconds. The wake up is implemented by connecting to the service and sending a wake up request. A ? at the end of the wake-up time field requests that no wake up events be sent before the first time a service is used. Specify 0 for no automatic wake up. The pickup(8), qmgr(8) and flush(8) daemons require a wake up timer.

Process limit (default: $default_process_limit)

The maximum number of processes that may execute this service simultaneously. Specify 0 for no process count limit. NOTE: Some Postfix services must be configured as a single-process service (for example, qmgr(8)) and some services must be configured with no process limit (for example, cleanup(8)). These limits must not be changed.

Command name + arguments

The command to be executed. Characters that are special to the shell such as ">" or "|" have no special meaning here, and quotes cannot be used to protect arguments containing whitespace. To protect whitespace, use "{" and "}" as described below. The command name is relative to the Postfix daemon directory (pathname is controlled by the daemon_directory configuration variable).

The command argument syntax for specific commands is specified in the respective daemon manual page.

The following command-line options have the same effect for all daemon programs:

-D

Run the daemon under control by the command specified with the debugger_command variable in the main.cf configuration file. See DEBUG_README for hints and tips.

-o { name = value } (long form, Postfix >= 3.0)

-o name=value (short form)

Override the named main.cf configuration parameter. The parameter value can refer to other parameters as $name etc., just like in main.cf. See postconf(5) for syntax. NOTE 1: With the "long form" shown above, whitespace after "{", around "=", and before "}" is ignored, and whitespace within the parameter value is preserved.

NOTE 2: with the "short form" shown above, do not specify whitespace around the "=" or in parameter values. To specify a parameter value that contains whitespace, use the long form described above, or use commas instead of spaces, or specify the value in main.cf. Example:

```
/etc/postfix/master.cf:

    submission inet .... smtpd

        -o smtpd_xxx_yyy=$submission_xxx_yyy

/etc/postfix/main.cf

    submission_xxx_yyy = text with whitespace...
```

NOTE 3: Over-zealous use of parameter overrides makes the Postfix configuration hard to understand and maintain. At a certain point, it might be easier to configure multiple instances of Postfix, instead of configuring multiple personalities via master.cf.

-v

Increase the verbose logging level. Specify multiple -v options to make a Postfix daemon process increasingly verbose.

Other command-line arguments

Specify "{" and "}" around command arguments that contain whitespace (Postfix 3.0 and later). Whitespace after "{" and before "}" is ignored.

## SEE ALSO

```
master(8), process manager
postconf(5), configuration parameters
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
BASIC_CONFIGURATION_README, basic configuration
DEBUG_README, Postfix debugging
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```
Initial version by
Magnus Baeck
Lund Institute of Technology
Sweden
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


title: memcache_table(5)

text:
# memcache_table(5)

## NAME
memcache_table - Postfix memcache client configuration

## SYNOPSIS

```
postmap -q "string" memcache:/etc/postfix/filename
postmap -q - memcache:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting or mail routing. These tables are usually in dbm or db format.

Alternatively, lookup tables can be specified as memcache instances. To use memcache lookups, define a memcache source as a lookup table in main.cf, for example:

```
    virtual_alias_maps = memcache:/etc/postfix/memcache-aliases.cf
```

The file /etc/postfix/memcache-aliases.cf has the same format as the Postfix main.cf file, and specifies the parameters described below.

The Postfix memcache client supports the lookup, update, delete and sequence (first/next) operations. The sequence operation requires a backup database that supports the operation.

## MEMCACHE MAIN PARAMETERS

```

```

memcache (default: inet:localhost:11211)

The memcache server (note: singular) that Postfix will try to connect to. For a TCP server specify "inet:" followed by a hostname or address, ":", and a port name or number. Specify an IPv6 address inside "[]". For a UNIX-domain server specify "unix:" followed by the socket pathname. Examples:

```
    memcache = inet:memcache.example.com:11211

    memcache = inet:127.0.0.1:11211

    memcache = inet:[fc00:8d00:189::3]:11211

    memcache = unix:/path/to/socket
```

NOTE: to access a UNIX-domain socket with the proxymap(8) server, the socket must be accessible by the unprivileged postfix user.

backup (default: undefined)

An optional Postfix database that provides persistent backup for the memcache database. The Postfix memcache client will update the memcache database whenever it looks up or changes information in the persistent database. Specify a Postfix "type:table" database. Examples:

```
    # Non-shared postscreen cache.

    backup = btree:/var/lib/postfix/postscreen_cache_map

    # Shared postscreen cache for processes on the same host.

    backup = proxy:btree:/var/lib/postfix/postscreen_cache_map
```

Access to remote proxymap servers is under development.

NOTE 1: When sharing a persistent postscreen(8) or verify(8) cache, disable automatic cache cleanup (set *_cache_cleanup_interval = 0) except with one Postfix instance that will be responsible for cache cleanup.

NOTE 2: When multiple tables share the same memcache database, each table should use the key_format feature (see below) to prepend its own unique string to the lookup key. Otherwise, automatic postscreen(8) or verify(8) cache cleanup may not work.

NOTE 3: When the backup database is accessed with "proxy:" lookups, the full backup database name (including the "proxy:" prefix) must be specified in the proxymap server's proxy_read_maps or proxy_write_maps setting (depending on whether the access is read-only or read-write).

flags (default: 0)

Optional flags that should be stored along with a memcache update. The flags are ignored when looking up information.

ttl (default: 3600)

The expiration time in seconds of memcache updates. NOTE 1: When using a memcache table as postscreen(8) or verify(8) cache without persistent backup, specify a zero *_cache_cleanup_interval value with all Postfix instances that use the memcache, and specify the largest postscreen(8) *_ttl value or verify(8) *_expire_time value as the memcache table's ttl value.

NOTE 2: According to memcache protocol documentation, a value greater than 30 days (2592000 seconds) specifies absolute UNIX time. Smaller values are relative to the time of the update.

## MEMCACHE KEY PARAMETERS

```

```

key_format (default: %s)

Format of the lookup and update keys that the Postfix memcache client sends to the memcache server. By default, these are the same as the lookup and update keys that the memcache client receives from Postfix applications. NOTE 1: The key_format feature is not used for backup database requests.

NOTE 2: When multiple tables share the same memcache database, each table should prepend its own unique string to the lookup key. Otherwise, automatic postscreen(8) or verify(8) cache cleanup may not work.

Examples:

```
    key_format = aliases:%s

    key_format = verify:%s

    key_format = postscreen:%s
```

The key_format parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character.

%s

This is replaced by the memcache client input key.

%u

When the input key is an address of the form user@domain, %u is replaced by the SQL quoted local part of the address. Otherwise, %u is replaced by the entire search string. If the localpart is empty, a lookup is silently suppressed and returns no results (an update is skipped with a warning).

%d

When the input key is an address of the form user@domain, %d is replaced by the domain part of the address. Otherwise, a lookup is silently suppressed and returns no results (an update is skipped with a warning).

%[SUD]

The upper-case equivalents of the above expansions behave in the key_format parameter identically to their lower-case counter-parts.

%[1-9]

The patterns %1, %2, ... %9 are replaced by the corresponding most significant component of the input key's domain. If the input key is user@mail.example.com, then %1 is com, %2 is example and %3 is mail. If the input key is unqualified or does not have enough domain components to satisfy all the specified patterns, a lookup is silently suppressed and returns no results (an update is skipped with a warning).

domain (default: no domain list)

This feature can significantly reduce database server load. Specify a list of domain names, paths to files, or "type:table" databases. When specified, only fully qualified search keys with a *non-empty* localpart and a matching domain are eligible for lookup or update: bare 'user' lookups, bare domain lookups and "@domain" lookups are silently skipped (updates are skipped with a warning). Example:

```
    domain = example.com, hash:/etc/postfix/searchdomains
```

## MEMCACHE ERROR CONTROLS

```

```

data_size_limit (default: 10240)

The maximal memcache reply data length in bytes.

line_size_limit (default: 1024)

The maximal memcache reply line length in bytes.

max_try (default: 2)

The number of times to try a memcache command before giving up. The memcache client does not retry a command when the memcache server accepts no connection.

retry_pause (default: 1)

The time in seconds before retrying a failed memcache command.

timeout (default: 2)

The time limit for sending a memcache command and for receiving a memcache reply.

## BUGS

The Postfix memcache client cannot be used for security-sensitive tables such as alias_maps (these may contain "|command and "/file/name" destinations), or virtual_uid_maps, virtual_gid_maps and virtual_mailbox_maps (these specify UNIX process privileges or "/file/name" destinations). In a typical deployment a memcache database is writable by any process that can talk to the memcache server; in contrast, security-sensitive tables must never be writable by the unprivileged Postfix user.

The Postfix memcache client requires additional configuration when used as postscreen(8) or verify(8) cache. For details see the backup and ttl parameter discussions in the MEMCACHE MAIN PARAMETERS section above.

## SEE ALSO

```
postmap(1), Postfix lookup table manager
postconf(5), configuration parameters
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
MEMCACHE_README, Postfix memcache client guide
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## HISTORY

Memcache support was introduced with Postfix version 2.9.

## AUTHOR(S)

```
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


title: mysql_table(5)

text:
# mysql_table(5)

## NAME
mysql_table - Postfix MySQL client configuration

## SYNOPSIS

```
postmap -q "string" mysql:/etc/postfix/filename
postmap -q - mysql:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting or mail routing. These tables are usually in dbm or db format.

Alternatively, lookup tables can be specified as MySQL databases. In order to use MySQL lookups, define a MySQL source as a lookup table in main.cf, for example:

```
    alias_maps = mysql:/etc/postfix/mysql-aliases.cf
```

The file /etc/postfix/mysql-aliases.cf has the same format as the Postfix main.cf file, and can specify the parameters described below.

## LIST MEMBERSHIP

```

```

When using SQL 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 SQL databases it is not uncommon to return the key itself or a constant value.

## MYSQL PARAMETERS

```

```

hosts

The hosts that Postfix will try to connect to and query from. Specify unix: for UNIX domain sockets, inet: for TCP connections (default). Examples:

```
    hosts = inet:host1.some.domain inet:host2.some.domain:port

    hosts = host1.some.domain host2.some.domain:port

    hosts = unix:/file/name
```

The hosts are tried in random order, with all connections over UNIX domain sockets being tried before those over TCP. The connections are automatically closed after being idle for about 1 minute, and are re-opened as necessary. Postfix versions 2.0 and earlier do not randomize the host order.

NOTE: if you specify localhost as a hostname (even if you prefix it with inet:), MySQL will connect to the default UNIX domain socket. In order to instruct MySQL to connect to localhost over TCP you have to specify

```
    hosts = 127.0.0.1
```

user

password

The user name and password to log into the mysql server. Example:

```
    user = someone

    password = some_password
```

dbname

The database name on the servers. Example:

```
    dbname = customer_database
```

query

The SQL query template used to search the database, where %s is a substitute for the address Postfix is trying to resolve, e.g.

```
    query = SELECT replacement FROM aliases WHERE mailbox = '%s'
```

By default, every query must return a result set (instead of storing its results in a table); with "require_result_set = no" (Postfix 3.2 and later), the absence of a result set is treated as "not found".

This parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character.

%s

This is replaced by the input key. SQL quoting is used to make sure that the input key does not add unexpected metacharacters.

%u

When the input key is an address of the form user@domain, %u is replaced by the SQL quoted local part of the address. Otherwise, %u is replaced by the entire search string. If the localpart is empty, the query is suppressed and returns no results.

%d

When the input key is an address of the form user@domain, %d is replaced by the SQL quoted domain part of the address. Otherwise, the query is suppressed and returns no results.

%[SUD]

The upper-case equivalents of the above expansions behave in the query parameter identically to their lower-case counter-parts. With the result_format parameter (see below), they expand the input key rather than the result value.

%[1-9]

The patterns %1, %2, ... %9 are replaced by the corresponding most significant component of the input key's domain. If the input key is user@mail.example.com, then %1 is com, %2 is example and %3 is mail. If the input key is unqualified or does not have enough domain components to satisfy all the specified patterns, the query is suppressed and returns no results.

The domain parameter described below limits the input keys to addresses in matching domains. When the domain parameter is non-empty, SQL queries for unqualified addresses or addresses in non-matching domains are suppressed and return no results. This parameter is available with Postfix 2.2. In prior releases the SQL query was built from the separate parameters: select_field, table, where_field and additional_conditions. The mapping from the old parameters to the equivalent query is:

```
    SELECT [select_field]

    FROM [table]

    WHERE [where_field] = '%s'

          [additional_conditions]
```

The '%s' in the WHERE clause expands to the escaped search string. With Postfix 2.2 these legacy parameters are used if the query parameter is not specified.

NOTE: DO NOT put quotes around the query parameter.

result_format (default: %s)

Format template applied to result attributes. Most commonly used to append (or prepend) text to the result. This parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character.

%s

This is replaced by the value of the result attribute. When result is empty it is skipped.

%u

When the result attribute value is an address of the form user@domain, %u is replaced by the local part of the address. When the result has an empty localpart it is skipped.

%d

When a result attribute value is an address of the form user@domain, %d is replaced by the domain part of the attribute value. When the result is unqualified it is skipped.

%[SUD1-9]

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 query, and in fact because the input key is known in advance, queries whose key does not contain all the information specified in the result template are suppressed and return no results.

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 parameter explained below allows one to restrict the number of values in the result, which is especially useful for maps that must return at most one value. The default value %s specifies that each result value should be used as is.

This parameter is available with Postfix 2.2 and later.

NOTE: DO NOT put quotes around the result format!

domain (default: no domain list)

This is a list of domain names, paths to files, or "type:table" databases. 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 MySQL server.

```
    domain = postfix.org, hash:/etc/postfix/searchdomains
```

It is best not to use SQL to store the domains eligible for SQL lookups.

This parameter is available with Postfix 2.2 and later.

NOTE: DO NOT define this parameter for local(8) aliases, because the input keys are always unqualified.

expansion_limit (default: 0)

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.

option_file

Read options from the given file instead of the default my.cnf location. This reads options from the [client] option group, optionally followed by options from the group given with option_group. This parameter is available with Postfix 2.11 and later.

option_group (default: Postfix >=3.2: client, <= 3.1: empty)

Read options from the given group of the mysql options file, after reading options from the [client] group. Postfix 3.2 and later read [client] option group settings by default. To disable this specify no option_file and specify "option_group =" (i.e. an empty value).

Postfix 3.1 and earlier don't read [client] option group settings unless a non-empty option_file or option_group value are specified. To enable this, specify, for example, "option_group = client".

This parameter is available with Postfix 2.11 and later.

require_result_set (default: yes)

If "yes", require that every query returns a result set. If "no", treat the absence of a result set as "not found". This parameter is available with Postfix 3.2 and later.

tls_cert_file

File containing client's X509 certificate. This parameter is available with Postfix 2.11 and later.

tls_key_file

File containing the private key corresponding to tls_cert_file. This parameter is available with Postfix 2.11 and later.

tls_CAfile

File containing certificates for all of the X509 Certification Authorities the client will recognize. Takes precedence over tls_CApath. This parameter is available with Postfix 2.11 and later.

tls_CApath

Directory containing X509 Certification Authority certificates in separate individual files. This parameter is available with Postfix 2.11 and later.

tls_ciphers

The list of permissible ciphers for SSL encryption. This parameter is available with Postfix 2.11 and later.

tls_verify_cert (default: no)

Verify that the server's name matches the common name in the certificate. This parameter is available with Postfix 2.11 and later.

## USING MYSQL STORED PROCEDURES

```

```

Postfix 3.2 and later support calling a stored procedure instead of using a SELECT statement in the query, e.g.

```
    query = CALL lookup('%s')
```

The previously described '%' expansions can be used in the parameter(s) to the stored procedure.

By default, every stored procedure call must return a result set, i.e. every code path must execute a SELECT statement that returns a result set (instead of storing its results in a table). With "require_result_set = no", the absence of a result set is treated as "not found".

A stored procedure must not return multiple result sets. That is, there must be no code path that executes multiple SELECT statements that return a result (instead of storing their results in a table).

The following is an example of a stored procedure returning a single result set:

```
CREATE [DEFINER=`user`@`host`] PROCEDURE
`lookup`(IN `param` VARCHAR(255))

    READS SQL DATA

    SQL SECURITY INVOKER

    BEGIN

        select goto from alias where address=param;

    END
```

## OBSOLETE MAIN.CF PARAMETERS

```

```

For compatibility with other Postfix lookup tables, MySQL parameters can also be defined in main.cf. In order to do that, specify as MySQL source a name that doesn't begin with a slash or a dot. The MySQL 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 "mysql:mysqlname", the parameter "hosts" would be defined in main.cf as "mysqlname_hosts".

Note: with this form, the passwords for the MySQL sources are written in main.cf, which is normally world-readable. Support for this form will be removed in a future Postfix version.

## OBSOLETE QUERY INTERFACE

```

```

This section describes an interface that is deprecated as of Postfix 2.2. It is replaced by the more general query interface described above. If the query parameter is defined, the legacy parameters described here ignored. Please migrate to the new interface as the legacy interface may be removed in a future release.

The following parameters can be used to fill in a SELECT template statement of the form:

```
    SELECT [select_field]

    FROM [table]

    WHERE [where_field] = '%s'

          [additional_conditions]
```

The specifier %s is replaced by the search string, and is escaped so if it contains single quotes or other odd characters, it will not cause a parse error, or worse, a security problem.

select_field

The SQL "select" parameter. Example:

```
    select_field = forw_addr
```

table

The SQL "select .. from" table name. Example:

```
    table = mxaliases
```

where_field

The SQL "select .. where" parameter. Example:

```
    where_field = alias
```

additional_conditions

Additional conditions to the SQL query. Example:

```
    additional_conditions = AND status = 'paid'
```

## SEE ALSO

```
postmap(1), Postfix lookup table maintenance
postconf(5), configuration parameters
ldap_table(5), LDAP lookup tables
pgsql_table(5), PostgreSQL lookup tables
sqlite_table(5), SQLite lookup tables
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
MYSQL_README, Postfix MYSQL client guide
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## HISTORY

MySQL support was introduced with Postfix version 1.0.

## AUTHOR(S)

```
Original implementation by:
Scott Cotton, Joshua Marcus
IC Group, Inc.
Further enhancements by:
Liviu Daia
Institute of Mathematics of the Romanian Academy
P.O. BOX 1-764
RO-014700 Bucharest, ROMANIA
Stored-procedure support by John Fawcett.
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


title: nisplus_table(5)

text:
# nisplus_table(5)

## NAME
nisplus_table - Postfix NIS+ client

## SYNOPSIS

```
postmap -q "string" "nisplus:[name=%s];name.name."
postmap -q - "nisplus:[name=%s];name.name." <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional lookup tables. These tables are usually in dbm or db format. Alternatively, lookup tables can be specified as NIS+ databases.

To find out what types of lookup tables your Postfix system supports use the "postconf -m" command.

To test Postfix NIS+ lookup tables, use the "postmap -q" command as described in the SYNOPSIS above.

## QUERY SYNTAX

```

```

Most of the NIS+ query is specified via the NIS+ map name. The general format of a Postfix NIS+ map name is as follows:

nisplus:[name=%s];name.name.name.:column

Postfix NIS+ map names differ from what one normally would use with commands such as niscat:

- With each NIS+ table lookup, "%s" is replaced by a version of the lookup string. There can be only one "%s" instance in a Postfix NIS+ map name.

- Postfix NIS+ map names use ";" instead of ",", because the latter character is special in the Postfix main.cf file. Postfix replaces ";" characters in the map name by "," before making NIS+ queries.

- The ":column" part in the NIS+ map name is not part of the actual NIS+ query. Instead, it specifies the number of the table column that provides the lookup result. When no ":column" is specified the first column (1) is used.

## EXAMPLE

```

```

A NIS+ aliases map might be queried as follows:

```
    alias_maps = dbm:/etc/mail/aliases,

        nisplus:[alias=%s];mail_aliases.org_dir.$mydomain.:1
```

This queries the local aliases file before the NIS+ file.

## SEE ALSO

```
postmap(1), Postfix lookup table manager
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## AUTHOR(S)

```
Geoff Gibbs
UK-HGMP-RC
Hinxton
Cambridge
CB10 1SB, UK
Adopted and adapted by:
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


title: pcre_table(5)

text:
# pcre_table(5)

## NAME
pcre_table - format of Postfix PCRE tables

## SYNOPSIS

```
postmap -q "string" pcre:/etc/postfix/filename
postmap -q - pcre:/etc/postfix/filename <inputfile
postmap -hmq - pcre:/etc/postfix/filename <inputfile
postmap -bmq - pcre:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting, mail routing, or access control. These tables are usually in dbm or db format.

Alternatively, lookup tables can be specified in Perl Compatible Regular Expression form. In this case, each input is compared against a list of patterns. When a match is found, the corresponding result is returned and the search is terminated.

To find out what types of lookup tables your Postfix system supports use the "postconf -m" command.

To test lookup tables, use the "postmap -q" command as described in the SYNOPSIS above. Use "postmap -hmq - <file" for header_checks(5) patterns, and "postmap -bmq - <file" for body_checks(5) (Postfix 2.6 and later).

This driver can be built with the pcre2 library (Postfix 3.7 and later), or with the legacy pcre library (all Postfix versions).

## COMPATIBILITY

```

```

With Postfix version 2.2 and earlier specify "postmap -fq" to query a table that contains case sensitive patterns. Patterns are case insensitive by default.

## TABLE FORMAT

```

```

The general form of a PCRE table is:

/pattern/flags result

When pattern matches the input string, use the corresponding result value.

!/pattern/flags result

When pattern does not match the input string, use the corresponding result value.

if /pattern/flags

endif

If the input string matches /pattern/, then match that input string against the patterns between if and endif. The if..endif can nest. Note: do not prepend whitespace to patterns inside if..endif.

This feature is available in Postfix 2.1 and later.

if !/pattern/flags

endif

If the input string does not match /pattern/, then match that input string against the patterns between if and endif. The if..endif can nest. Note: do not prepend whitespace to patterns inside if..endif.

This feature is available in Postfix 2.1 and later.

blank lines and comments

Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a `#'.

multi-line text

A logical line starts with non-whitespace text. A line that starts with whitespace continues a logical line.

Each pattern is a perl-like regular expression. The expression delimiter can be any non-alphanumeric character, except whitespace or characters that have special meaning (traditionally the forward slash is used). The regular expression can contain whitespace.

By default, matching is case-insensitive, and newlines are not treated as special characters. The behavior is controlled by flags, which are toggled by appending one or more of the following characters after the pattern:

i (default: on)

Toggles the case sensitivity flag. By default, matching is case insensitive.

m (default: off)

Toggles the pcre MULTILINE flag. When this flag is on, the ^ and $ metacharacters match immediately after and immediately before a newline character, respectively, in addition to matching at the start and end of the subject string.

s (default: on)

Toggles the pcre DOTALL flag. When this flag is on, the . metacharacter matches the newline character. With Postfix versions prior to 2.0, the flag is off by default, which is inconvenient for multi-line message header matching.

x (default: off)

Toggles the pcre extended flag. When this flag is on, whitespace characters in the pattern (other than in a character class) are ignored. To include a whitespace character as part of the pattern, escape it with backslash. Note: do not use #comment after patterns.

A (default: off)

Toggles the pcre ANCHORED flag. When this flag is on, the pattern is forced to be "anchored", that is, it is constrained to match only at the start of the string which is being searched (the "subject string"). This effect can also be achieved by appropriate constructs in the pattern itself.

E (default: off)

Toggles the pcre DOLLAR_ENDONLY flag. When this flag is on, a $ metacharacter in the pattern matches only at the end of the subject string. Without this flag, a dollar also matches immediately before the final character if it is a newline character (but not before any other newline characters). This flag is ignored if the pcre MULTILINE flag is set.

U (default: off)

Toggles the pcre UNGREEDY flag. When this flag is on, the pattern matching engine inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". This flag can also set by a (?U) modifier within the pattern.

X (default: off)

Toggles the pcre EXTRA flag. When this flag is on, any backslash in a pattern that is followed by a letter that has no special meaning causes an error, thus reserving these combinations for future expansion. This feature is not supported with PCRE2.

## SEARCH ORDER

```

```

Patterns are applied in the order as specified in the table, until a pattern is found that matches the input string.

Each pattern is applied to the entire input string. Depending on the application, that string is an entire client hostname, an entire client IP address, or an entire mail address. Thus, no parent domain or parent network search is done, and user@domain mail addresses are not broken up into their user and domain constituent parts, nor is user+foo broken up into user and foo.

## TEXT SUBSTITUTION

```

```

Substitution of substrings (text that matches patterns inside "()") from the matched expression into the result string is requested with $1, $2, etc.; specify $$ to produce a $ character as output. The macros in the result string may need to be written as ${n} or $(n) if they aren't followed by whitespace. This feature does not support pcre2 substring names.

Note: since negated patterns (those preceded by !) return a result when the expression does not match, substitutions are not available for negated patterns.

## INLINE SPECIFICATION

```

```

The contents of a table may be specified in the table name (Postfix 3.7 and later). The basic syntax is:

```
main.cf:

    parameter = .. pcre:{ { rule-1 }, { rule-2 } .. } ..
master.cf:

    .. -o { parameter = .. pcre:{ { rule-1 }, { rule-2 } .. } .. } ..
```

Postfix ignores whitespace after '{' and before '}', and writes each rule as one text line to an in-memory file:

```
in-memory file:

    rule-1

    rule-2

    ..
```

Postfix parses the result as if it is a file in /etc/postfix.

Note: if a rule contains $, specify $$ to keep Postfix from trying to do $name expansion as it evaluates a parameter value.

## EXAMPLE SMTPD ACCESS MAP

```
# Protect your outgoing majordomo exploders
/^(?!owner-)(.*)-outgoing@(.*)/ 550 Use ${1}@${2} instead
# Bounce friend@whatever, except when whatever is our domain (you would
# be better just bouncing all friend@ mail - this is just an example).
/^(friend@(?!my\.domain$).*)$/  550 Stick this in your pipe $1
# A multi-line entry. The text is sent as one line.
#
/^noddy@my\.domain$/
 550 This user is a funny one. You really don't want to send mail to
 them as it only makes their head spin.
```

## EXAMPLE HEADER FILTER MAP

```
/^Subject: make money fast/     REJECT
/^To: friend@public\.com/       REJECT
```

## EXAMPLE BODY FILTER MAP

```
# First skip over base 64 encoded text to save CPU cycles.
# Requires PCRE version 3.
~^[[:alnum:]+/]{60,}$~          OK
# Put your own body patterns here.
```

## SEE ALSO

```
postmap(1), Postfix lookup table manager
postconf(5), configuration parameters
regexp_table(5), format of POSIX regular expression tables
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
```

## AUTHOR(S)

```
The PCRE table lookup code was originally written by:
Andrew McNamara
andrewm@connect.com.au
connect.com.au Pty. Ltd.
Level 3, 213 Miller St
North Sydney, NSW, Australia
Adopted and adapted by:
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
```


title: pgsql_table(5)

text:
# pgsql_table(5)

## NAME
pgsql_table - Postfix PostgreSQL client configuration

## SYNOPSIS

```
postmap -q "string" pgsql:/etc/postfix/filename
postmap -q - pgsql:/etc/postfix/filename <inputfile
```

## DESCRIPTION

The Postfix mail system uses optional tables for address rewriting or mail routing. These tables are usually in dbm or db format.

Alternatively, lookup tables can be specified as PostgreSQL databases. In order to use PostgreSQL lookups, define a PostgreSQL source as a lookup table in main.cf, for example:

```
    alias_maps = pgsql:/etc/postfix/pgsql-aliases.cf
```

The file /etc/postfix/pgsql-aliases.cf has the same format as the Postfix main.cf file, and can specify the parameters described below.

## LIST MEMBERSHIP

```

```

When using SQL 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 SQL databases it is not uncommon to return the key itself or a constant value.

## PGSQL PARAMETERS

```

```

hosts

The hosts that Postfix will try to connect to and query from. Besides a postgresql:// connection URI, this setting supports the historical forms unix:/pathname for UNIX-domain sockets and inet:host:port for TCP connections, where the unix: and inet: prefixes are accepted and ignored for backwards compatibility. Examples:

```
    hosts = postgresql://username@example.com/tablename?sslmode=require

    hosts = inet:host1.some.domain inet:host2.some.domain:port

    hosts = host1.some.domain host2.some.domain:port

    hosts = unix:/file/name
```

The hosts are tried in random order. The connections are automatically closed after being idle for about 1 minute, and are re-opened as necessary.

user

password

The user name and password to log into the pgsql server. Example:

```
    user = someone

    password = some_password
```

dbname

The database name on the servers. Example:

```
    dbname = customer_database
```

encoding

The encoding used by the database client. The default setting is:

```
    encoding = UTF8
```

Historically, the database client was hard coded to use LATIN1 in an attempt to disable multibyte character support. This feature is available in Postfix 3.8 and later.

query

The SQL query template used to search the database, where %s is a substitute for the address Postfix is trying to resolve, e.g.

```
    query = SELECT replacement FROM aliases WHERE mailbox = '%s'
```

This parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character. (Postfix 2.2 and later)

%s

This is replaced by the input key. SQL quoting is used to make sure that the input key does not add unexpected metacharacters.

%u

When the input key is an address of the form user@domain, %u is replaced by the SQL quoted local part of the address. Otherwise, %u is replaced by the entire search string. If the localpart is empty, the query is suppressed and returns no results.

%d

When the input key is an address of the form user@domain, %d is replaced by the SQL quoted domain part of the address. Otherwise, the query is suppressed and returns no results.

%[SUD]

The upper-case equivalents of the above expansions behave in the query parameter identically to their lower-case counter-parts. With the result_format parameter (see below), they expand the input key rather than the result value.

The above %S, %U and %D expansions are available with Postfix 2.2 and later

%[1-9]

The patterns %1, %2, ... %9 are replaced by the corresponding most significant component of the input key's domain. If the input key is user@mail.example.com, then %1 is com, %2 is example and %3 is mail. If the input key is unqualified or does not have enough domain components to satisfy all the specified patterns, the query is suppressed and returns no results.

The above %1, ... %9 expansions are available with Postfix 2.2 and later

The domain parameter described below limits the input keys to addresses in matching domains. When the domain parameter is non-empty, SQL queries for unqualified addresses or addresses in non-matching domains are suppressed and return no results. The precedence of this parameter has changed with Postfix 2.2, in prior releases the precedence was, from highest to lowest, select_function, query, select_field, ...

With Postfix 2.2 the query parameter has highest precedence, see OBSOLETE QUERY INTERFACES below.

NOTE: DO NOT put quotes around the query parameter.

result_format (default: %s)

Format template applied to result attributes. Most commonly used to append (or prepend) text to the result. This parameter supports the following '%' expansions:

%%

This is replaced by a literal '%' character.

%s

This is replaced by the value of the result attribute. When result is empty it is skipped.

%u

When the result attribute value is an address of the form user@domain, %u is replaced by the local part of the address. When the result has an empty localpart it is skipped.

%d

When a result attribute value is an address of the form user@domain, %d is replaced by the domain part of the attribute value. When the result is unqualified it is skipped.

%[SUD1-9]

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 query, and in fact because the input key is known in advance, queries whose key does not contain all the information specified in the result template are suppressed and return no results.

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 parameter explained below allows one to restrict the number of values in the result, which is especially useful for maps that must return at most one value. The default value %s specifies that each result value should be used as is.

This parameter is available with Postfix 2.2 and later.

NOTE: DO NOT put quotes around the result format!

domain (default: no domain list)

This is a list of domain names, paths to files, or "type:table" databases. 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 PostgreSQL server.

```
    domain = postfix.org, hash:/etc/postfix/searchdomains
```

It is best not to use SQL to store the domains eligible for SQL lookups.

This parameter is available with Postfix 2.2 and later.

NOTE: DO NOT define this parameter for local(8) aliases, because the input keys are always unqualified.

expansion_limit (default: 0)

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.

## OBSOLETE MAIN.CF PARAMETERS

```

```

For compatibility with other Postfix lookup tables, PostgreSQL parameters can also be defined in main.cf. In order to do that, specify as PostgreSQL source a name that doesn't begin with a slash or a dot. The PostgreSQL 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 "pgsql:pgsqlname", the parameter "hosts" would be defined in main.cf as "pgsqlname_hosts".

Note: with this form, the passwords for the PostgreSQL sources are written in main.cf, which is normally world-readable. Support for this form will be removed in a future Postfix version.

## OBSOLETE QUERY INTERFACES

```

```

This section describes query interfaces that are deprecated as of Postfix 2.2. Please migrate to the new query interface as the old interfaces are slated to be phased out.

select_function

This parameter specifies a database function name. Example:

```
    select_function = my_lookup_user_alias
```

This is equivalent to:

```
    query = SELECT my_lookup_user_alias('%s')
```

This parameter overrides the legacy table-related fields (described below). With Postfix versions prior to 2.2, it also overrides the query parameter. Starting with Postfix 2.2, the query parameter has highest precedence, and the select_function parameter is deprecated.

The following parameters (with lower precedence than the select_function interface described above) can be used to build the SQL select statement as follows:

```
    SELECT [select_field]

    FROM [table]

    WHERE [where_field] = '%s'

          [additional_conditions]
```

The specifier %s is replaced with each lookup by the lookup key and is escaped so if it contains single quotes or other odd characters, it will not cause a parse error, or worse, a security problem.

Starting with Postfix 2.2, this interface is obsoleted by the more general query interface described above. If higher precedence the query or select_function parameters described above are defined, the parameters described here are ignored.

select_field

The SQL "select" parameter. Example:

```
    select_field = forw_addr
```

table

The SQL "select .. from" table name. Example:

```
    table = mxaliases
```

where_field

The SQL "select .. where" parameter. Example:

```
    where_field = alias
```

additional_conditions

Additional conditions to the SQL query. Example:

```
    additional_conditions = AND status = 'paid'
```

## SEE ALSO

```
postmap(1), Postfix lookup table manager
postconf(5), configuration parameters
ldap_table(5), LDAP lookup tables
mysql_table(5), MySQL lookup tables
sqlite_table(5), SQLite lookup tables
```

## README FILES

```

```

Use "postconf readme_directory" or "postconf html_directory" to locate this information.

```
DATABASE_README, Postfix lookup table overview
PGSQL_README, Postfix PostgreSQL client guide
```

## LICENSE

```

```

The Secure Mailer license must be distributed with this software.

## HISTORY

PgSQL support was introduced with Postfix version 2.1.

## AUTHOR(S)

```
Based on the MySQL client by:
Scott Cotton, Joshua Marcus
IC Group, Inc.
Ported to PostgreSQL by:
Aaron Sethman
Further enhanced by:
Liviu Daia
Institute of Mathematics of the Romanian Academy
P.O. BOX 1-764
RO-014700 Bucharest, ROMANIA
```