Postfix Lookup Table Overview
OverviewThis document covers the following topics:
Postfix uses lookup tables to store and look up information for access control, address rewriting and even for content filtering. All Postfix lookup tables are specified as "type:table", where "type" is one of the database types described under "Postfix lookup table types" at the end of this document, and where "table" is the lookup table name. The Postfix documentation uses the terms "database" and "lookup table" for the same thing.
Examples of lookup tables that appear often in the Postfix documentation:
/usr/local/etc/postfix/main.cf: alias_maps = hash:/usr/local/etc/postfix/aliases (local aliasing) header_checks = regexp:/usr/local/etc/postfix/header_checks (content filtering) transport_maps = hash:/usr/local/etc/postfix/transport (routing table) virtual_alias_maps = hash:/usr/local/etc/postfix/virtual (address rewriting)
All Postfix lookup tables store information as (key, value) pairs. This interface may seem simplistic at first, but it turns out to be very powerful. The (key, value) query interface completely hides the complexities of LDAP or SQL from Postfix. This is a good example of connecting complex systems with simple interfaces.
Benefits of the Postfix (key, value) query interface:
Most Postfix lookup tables are used to look up information. Examples are address rewriting (the lookup string is the old address, and the result is the new address) or access control (the lookup string is the client, sender or recipient, and the result is an action such as "reject").
With some tables, however, Postfix needs to know only if the lookup key exists. The lookup result itself is not used. Examples are the local_recipient_maps that determine what local recipients Postfix accepts in mail from the network, the mydestination parameter that specifies what domains Postfix delivers locally, or the mynetworks parameter that specifies the IP addresses of trusted clients or client networks. Technically, these are lists, not tables. Despite the difference, Postfix lists are described here because they use the same underlying infrastructure as Postfix lookup tables.
LDAP and SQL are complex systems. Trying to set up both Postfix and LDAP or SQL at the same time is definitely not a good idea. You can save yourself a lot of time by implementing Postfix first with local files such as Berkeley DB. Local files have few surprises, and are easy to debug with the postmap(1) command:
% postmap -q email@example.com hash:/usr/local/etc/postfix/virtual
Once you have local files working properly you can follow the instructions in ldap_table(5), mysql_table(5) or pgsql_table(5) and replace local file lookups with LDAP or SQL lookups. When you do this, you should use the postmap(1) command again, to verify that database lookups still produce the exact same results as local file lookup:
% postmap -q firstname.lastname@example.org ldap:/usr/local/etc/postfix/virtual.cf
Be sure to exercise all the partial address or parent domain queries that are documented under "table search order" in the relevant manual page: access(5), canonical(5), virtual(5), transport(5), or under the relevant configuration parameter: mynetworks, relay_domains, parent_domain_matches_subdomains.
When you make changes to a database while the mail system is running, it would be desirable if Postfix avoids reading information while that information is being changed. It would also be nice if you can change a database without having to execute "postfix reload", in order to force Postfix to use the new information. Each time you do "postfix reload" Postfix loses a lot of performance.
Although Postfix uses file locking to avoid access conflicts while updating Berkeley DB or other local database files, you still have a problem when the update fails because the disk is full or because something else happens. This is because commands such as postmap(1) or postalias(1) overwrite existing files. If the update fails in the middle then you have no usable database, and Postfix will stop working.
With multi-file databases such as DBM, there is no simple solution. With Berkeley DB and other "one file" databases, it is possible to add some extra robustness by using "mv" to REPLACE an existing database file instead of overwriting it:
# postmap access.in && mv access.in.db access.db
This converts the input file "access.in" into the output file "access.in.db", and replaces the file "access.db" only when the postmap(1) command was successful. Of course typing such commands becomes boring quickly, and this is why people use "make" instead, as shown below. User input is shown in bold font.
# cat Makefile all: aliases.db access.db virtual.db ...etcetera... # Note 1: commands are specified after a TAB character. # Note 2: use postalias(1) for local aliases, postmap(1) for the rest. aliases.db: aliases.in postalias aliases.in mv aliases.in.db aliases.db access.db: access.in postmap access.in mv access.in.db access.db virtual.db: virtual.in postmap virtual.in mv virtual.in.db virtual.db ...etcetera... # vi access.in ...editing session not shown... # make postmap access.in mv access.in.db access.db #
The "make" command updates only the files that have changed. In case of error, the "make" command will stop and will not invoke the "mv" command, so that Postfix will keep using the existing database file as if nothing happened.
To find out what database types your Postfix system supports, use the "postconf -m" command. Here is a list of database types that are often supported:
Other lookup table types may be available depending on how Postfix was built. With some Postfix distributions the list is dynamically extensible as support for lookup tables is dynamically linked into Postfix.