Postfix Basic ConfigurationIntroductionPostfix has several hundred configuration parameters that are controlled via the main.cf file. Fortunately, all parameters have sensible default values. In many cases, you need to configure only two or three parameters before you can start to play with the mail system. Here's a quick introduction to the syntax: Postfix configuration files The text below assumes that you already have Postfix installed on the system, either by compiling the source code yourself (as described in the INSTALL file) or by installing an already compiled version. This document covers basic Postfix configuration. Information about how to configure Postfix for specific applications such as mailhub, firewall or dial-up client can be found in the STANDARD_CONFIGURATION_README file. But don't go there until you already have covered the material presented below. The first parameters of interest specify the machine's identity and role in the network. What domain name to use in outbound mail What domains to receive mail for What clients to relay mail from What destinations to relay mail to What delivery method: direct or indirect The default values for many other configuration parameters are derived from just these. The next parameter of interest controls the amount of mail sent to the local postmaster: What trouble to report to the postmaster Be sure to set the following correctly if you're behind a proxy or network address translator, and you are running a backup MX host for some other domain: Proxy/NAT external network addresses Postfix daemon processes run in the background, and log problems and normal activity to the syslog daemon. Here are a few things that you need to be aware of: What you need to know about Postfix logging If your machine has unusual security requirements you may want to run Postfix daemon processes inside a chroot environment. Running Postfix daemon processes chrooted If you run Postfix on a virtual network interface, or if your machine runs other mailers on virtual interfaces, you'll have to look at the other parameters listed here as well:

My own hostname My own domain name My own network addresses

Postfix configuration filesBy default, Postfix configuration files are in /etc/postfix. The two most important files are main.cf and master.cf; these files must be owned by root. Giving someone else write permission to main.cf or master.cf (or to their parent directories) means giving root privileges to that person. In /etc/postfix/main.cf you will have to set up a minimal number of configuration parameters. Postfix configuration parameters resemble shell variables, with two important differences: the first one is that Postfix does not know about quotes like the UNIX shell does. You specify a configuration parameter as:/etc/postfix/main.cf: parameter = value

and you use it by putting a "$" character in front of its name:/etc/postfix/main.cf: other_parameter = $parameter

You can use $parameter before it is given a value (that is the second main difference with UNIX shell variables). The Postfix configuration language uses lazy evaluation, and does not look at a parameter value until it is needed at runtime. Postfix uses database files for access control, address rewriting and other purposes. The DATABASE_README file gives an introduction to how Postfix works with Berkeley DB, LDAP or SQL and other types. Here is a common example of how Postfix invokes a database:/etc/postfix/main.cf: virtual_alias_maps = hash:/etc/postfix/virtual

Whenever you make a change to the main.cf or master.cf file, execute the following command as root in order to refresh a running mail system:# postfix reload

What domain name to use in outbound mailThe myorigin parameter specifies the domain that appears in mail that is posted on this machine. The default is to use the local machine name, $myhostname, which defaults to the name of the machine. Unless you are running a really small site, you probably want to change that into $mydomain, which defaults to the parent domain of the machine name. For the sake of consistency between sender and recipient addresses, myorigin also specifies the domain name that is appended to an unqualified recipient address. Examples (specify only one of the following):/etc/postfix/main.cf: myorigin = $myhostname (default: send mail as "user@$myhostname") myorigin = $mydomain (probably desirable: "user@$mydomain")

What domains to receive mail forThe mydestination parameter specifies what domains this machine will deliver locally, instead of forwarding to another machine. The default is to receive mail for the machine itself. See the VIRTUAL_README file for how to configure Postfix for hosted domains. You can specify zero or more domain names, "/file/name" patterns and/or "type:table" lookup tables (such as hash:, btree:, nis:, ldap:, or mysql:), separated by whitespace and/or commas. A "/file/name" pattern is replaced by its contents; "type:table" requests that a table lookup is done and merely tests for existence: the lookup result is ignored. IMPORTANT: If your machine is a mail server for its entire domain, you must list $mydomain as well. Example 1: default setting./etc/postfix/main.cf: mydestination = $myhostname localhost.$mydomain localhost

Example 2: domain-wide mail server./etc/postfix/main.cf: mydestination = $myhostname localhost.$mydomain localhost $mydomain

Example 3: host with multiple DNS A records./etc/postfix/main.cf: mydestination = $myhostname localhost.$mydomain localhost www.$mydomain ftp.$mydomain

Caution: in order to avoid mail delivery loops, you must list all hostnames of the machine, including $myhostname, and localhost.$mydomain.

What clients to relay mail fromBy default, Postfix will forward mail from clients in authorized network blocks to any destination. Authorized networks are defined with the mynetworks configuration parameter. The default is to authorize all clients in the IP subnetworks that the local machine is attached to. IMPORTANT: If your machine is connected to a wide area network then your default mynetworks setting may be too friendly. Examples (specify only one of the following):/etc/postfix/main.cf: mynetworks_style = subnet (default: authorize subnetworks) mynetworks_style = host (safe: authorize local machine only) mynetworks = 127.0.0.0/8 (safe: authorize local machine only) mynetworks = 127.0.0.0/8 168.100.189.2/32 (authorize local machine)

You can specify the trusted networks in the main.cf file, or you can let Postfix do the work for you. The default is to let Postfix do the work. The result depends on the mynetworks_style parameter value. Specify "mynetworks_style = host" when Postfix should forward mail from only the local machine. Specify "mynetworks_style = subnet" (the default) when Postfix should forward mail from

SMTP clients in the same IP subnetworks as the local machine. On Linux, this works correctly only with interfaces specified with the "ifconfig" command. Specify "mynetworks_style = class" when Postfix should forward mail from SMTP clients in the same IP class A/B/C networks as the local machine. Don't do this with a dialup site - it would cause Postfix to "trust" your entire provider's network. Instead, specify an explicit mynetworks list by hand, as described below. Alternatively, you can specify the mynetworks list by hand, in which case Postfix ignores the mynetworks_style setting. To specify the list of trusted networks by hand, specify network blocks in CIDR (network/mask) notation, for example:/etc/postfix/main.cf: mynetworks = 168.100.189.0/28, 127.0.0.0/8

You can also specify the absolute pathname of a pattern file instead of listing the patterns in the main.cf file.

What destinations to relay mail toBy default, Postfix will forward mail from strangers (clients outside authorized networks) to authorized remote destinations only. Authorized remote destinations are defined with the relay_domains configuration parameter. The default is to authorize all domains (and subdomains) of the domains listed with the mydestination parameter. Examples (specify only one of the following):/etc/postfix/main.cf: relay_domains = $mydestination (default) relay_domains = (safe: never forward mail from strangers) relay_domains = $mydomain (forward mail to my domain and subdomains)

What delivery method: direct or indirectBy default, Postfix tries to deliver mail directly to the Internet. Depending on your local conditions this may not be possible or desirable. For example, your system may be turned off outside office hours, it may be behind a firewall, or it may be connected via a provider who does not allow direct mail to the Internet. In those cases you need to configure Postfix to deliver mail indirectly via a relay host. Examples (specify only one of the following):/etc/postfix/main.cf: relayhost = Internet) relayhost = $mydomain relayhost = [mail.$mydomain] relayhost = [mail.isp.tld] (default: direct delivery to (deliver via local mailhub) (deliver via local mailhub) (deliver via provider mailhub)

The form enclosed with [] eliminates DNS MX lookups. Don't worry if you don't know what that means. Just be sure to specify the [] around the mailhub hostname that your ISP gave to you, otherwise mail may be mis-delivered. The STANDARD_CONFIGURATION_README file has more hints and tips for firewalled and/or dial-up networks.

What trouble to report to the postmasterYou should set up a postmaster alias in the aliases(5) table that directs mail to a human person. The postmaster address is required to exist, so that people can report mail delivery problems. While you're updating the aliases(5) table, be sure to direct mail for the super-user to a human person too./etc/aliases: postmaster: you root: you

Execute the command "newaliases" after changing the aliases file. Instead of /etc/aliases, your alias file may be located elsewhere. Use the command "postconf alias_maps" to find out. The Postfix system reports problems to the postmaster alias. You may not be interested in all types of trouble reports, so this reporting mechanism is configurable. The default is to report only serious problems (resource, software) to postmaster: Default setting:/etc/postfix/main.cf: notify_classes = resource, software

The meaning of the classes is as follows: bounce Inform the postmaster of undeliverable mail. Either send the postmaster a copy of undeliverable mail that is returned to the sender, or send a transcript of the SMTP session when Postfix rejected mail. For privacy reasons, the postmaster copy of undeliverable mail is truncated after the original message headers. This implies "2bounce" (see below). See also the luser_relay feature. The notification is sent to the address specified with the bounce_notice_recipient configuration parameter (default: postmaster). 2bounce When Postfix is unable to return undeliverable mail to the sender, send it to the postmaster instead (without truncating the message after the primary headers). The notification is sent to the address specified with the 2bounce_notice_recipient configuration parameter (default: postmaster). delay Inform the postmaster of delayed mail. In this case, the postmaster receives message headers only. The notification is sent to the address specified with the delay_notice_recipient configuration parameter (default: postmaster). policy Inform the postmaster of client requests that were rejected because of (UCE) policy restrictions. The postmaster receives a transcript of the SMTP session. The notification is sent to the address specified with the error_notice_recipient configuration parameter (default: postmaster). protocol

Inform the postmaster of protocol errors (client or server side) or attempts by a client to execute unimplemented commands. The postmaster receives a transcript of the SMTP session. The notification is sent to the address specified with the error_notice_recipient configuration parameter (default: postmaster). resource Inform the postmaster of mail not delivered due to resource problems (for example, queue file write errors). The notification is sent to the address specified with the error_notice_recipient configuration parameter (default: postmaster). software Inform the postmaster of mail not delivered due to software problems. The notification is sent to the address specified with the error_notice_recipient configuration parameter (default: postmaster).

Proxy/NAT external network addressesSome mail servers are connected to the Internet via a network address translator (NAT) or proxy. This means that systems on the Internet connect to the address of the NAT or proxy, instead of connecting to the network address of the mail server. The NAT or proxy forwards the connection to the network address of the mail server, but Postfix does not know this. If you run a Postfix server behind a proxy or NAT, you need to configure the proxy_interfaces parameter and specify all the external proxy or NAT addresses that Postfix receives mail on. You may specify symbolic hostnames instead of network addresses. IMPORTANT: You must specify your proxy/NAT external addresses when your system is a backup MX host for other domains, otherwise mail delivery loops will happen when the primary MX host is down. Example: host behind NAT box running a backup MX host./etc/postfix/main.cf: proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address)

What you need to know about Postfix loggingPostfix daemon processes run in the background, and log problems and normal activity to the syslog daemon. The syslogd process sorts events by class and severity, and appends them to logfiles. The logging classes, levels and logfile names are usually specified in /etc/syslog.conf. At the very least you need something like:/etc/syslog.conf: mail.err mail.debug /dev/console /var/log/maillog

After changing the syslog.conf file, send a "HUP" signal to the syslogd process. IMPORTANT: many syslogd implementations will not create files. You must create files before (re)starting syslogd. IMPORTANT: on Linux you need to put a "-" character before the pathname, e.g., -/var/log/maillog,

otherwise the syslogd process will use more system resources than Postfix. Hopefully, the number of problems will be small, but it is a good idea to run every night before the syslog files are rotated:# postfix check # egrep '(reject|warning|error|fatal|panic):' /some/log/file

The first line (postfix check) causes Postfix to report file permission/ownership discrepancies. The second line looks for problem reports from the mail software, and reports how effective the relay and junk mail access blocks are. This may produce a lot of output. You will want to apply some postprocessing to eliminate uninteresting information. The DEBUG_README document describes the meaning of the "warning" etc. labels in Postfix logging.

Running Postfix daemon processes chrootedPostfix daemon processes can be configured (via the master.cf file) to run in a chroot jail. The processes run at a fixed low privilege and with file system access limited to the Postfix queue directories (/var/spool/postfix). This provides a significant barrier against intrusion. The barrier is not impenetrable (chroot limits file system access only), but every little bit helps. With the exception of Postfix daemons that deliver mail locally and/or that execute non-Postfix commands, every Postfix daemon can run chrooted. Sites with high security requirements should consider to chroot all daemons that talk to the network: the smtp(8) and smtpd(8) processes, and perhaps also the lmtp(8) client. The author's own porcupine.org mail server runs all daemons chrooted that can be chrooted. The default /etc/postfix/master.cf file specifies that no Postfix daemon runs chrooted. In order to enable chroot operation, edit the file /etc/postfix/master.cf, and follow instructions in the file. When you're finished, execute "postfix reload" to make the change effective. Note that a chrooted daemon resolves all filenames relative to the Postfix queue directory (/var/spool/postfix). For successful use of a chroot jail, most UNIX systems require you to bring in some files or device nodes. The examples/chroot-setup directory in the source code distribution has a collection of scripts that help you set up Postfix chroot environments on different operating systems. Additionally, you almost certainly need to configure syslogd so that it listens on a socket inside the Postfix queue directory. Examples of syslogd command line options that achieve this for specific systems: FreeBSD: syslogd -l /var/spool/postfix/var/run/log Linux, OpenBSD: syslogd -a /var/spool/postfix/dev/log

My own hostnameThe myhostname parameter specifies the fully-qualified domain name of the machine running the Postfix system. $myhostname appears as the default value in many other Postfix configuration parameters. By default, myhostname is set to the local machine name. If your local machine name is not in fully-qualified domain name form, or if you run Postfix on a virtual interface, you will have to specify the fully-qualified domain name that the mail system should use.

Alternatively, if you specify mydomain in main.cf, then Postfix will use its value to generate a fully-qualified default value for the myhostname parameter. Examples (specify only one of the following):/etc/postfix/main.cf: myhostname = host.local.domain (machine name is not FQDN) myhostname = host.virtual.domain (virtual interface) myhostname = virtual.domain (virtual interface)

My own domain nameThe mydomain parameter specifies the parent domain of $myhostname. By default, it is derived from $myhostname by stripping off the first part (unless the result would be a top-level domain). Conversely, if you specify mydomain in main.cf, then Postfix will use its value to generate a fullyqualified default value for the myhostname parameter. Examples (specify only one of the following):/etc/postfix/main.cf: mydomain = local.domain mydomain = virtual.domain (virtual interface)

My own network addressesThe inet_interfaces parameter specifies all network interface addresses that the Postfix system should listen on; mail addressed to "user@[network address]" will be delivered locally, as if it is addressed to a domain listed in $mydestination. You can override the inet_interfaces setting in the Postfix master.cf file by prepending an IP address to a server name. The default is to listen on all active interfaces. If you run mailers on virtual interfaces, you will have to specify what interfaces to listen on. IMPORTANT: If you run MTAs on virtual interfaces you must specify explicit inet_interfaces values for the MTA that receives mail for the machine itself: this MTA should never listen on the virtual interfaces or you would have a mailer loop when a virtual MTA is down. Example: default setting./etc/postfix/main.cf: inet_interfaces = all

Example: host running one or more virtual mailers. For each Postfix instance, specify only one of the following./etc/postfix/main.cf: inet_interfaces = virtual.host.tld (virtual Postfix) inet_interfaces = $myhostname localhost... (non-virtual Postfix)

Note: you need to stop and start Postfix after changing this parameter.

Postfix Small/Home Office Hints and TipsOverviewThis document combines hints and tips for "small office/home office" applications into one document so that they are easier to find. The text describes the mail sending side only. If your machine does not receive mail directly (i.e. it does not have its own Internet domain name and its own fixed IP address), then you will need a solution such as "fetchmail", which is outside the scope of the Postfix documentation. Selected topics from the STANDARD_CONFIGURATION_README document: Postfix on a stand-alone Internet host Postfix on hosts without a real Internet hostname Selected topics from the SASL_README document: Enabling SASL authentication in the Postfix SMTP client Configuring Sender-Dependent SASL authentication See the SASL_README and STANDARD_CONFIGURATION_README documents for further information on these topics.

Postfix on a stand-alone Internet hostPostfix should work out of the box without change on a stand-alone machine that has direct Internet access. At least, that is how Postfix installs when you download the Postfix source code via http://www.postfix.org/. You can use the command "postconf -n" to find out what settings are overruled by your main.cf. Besides a few pathname settings, few parameters should be set on a stand-alone box, beyond what is covered in the BASIC_CONFIGURATION_README document:/etc/postfix/main.cf: # Optional: send mail as user@domainname instead of user@hostname. #myorigin = $mydomain # Optional: specify NAT/proxy external address. #proxy_interfaces = 1.2.3.4 # Alternative 1: don't relay mail from other hosts. mynetworks_style = host relay_domains = # Alternative 2: relay mail from local clients only. # mynetworks = 192.168.1.0/28 # relay_domains =

See also the section "Postfix on hosts without a real Internet hostname" if this is applicable to your

configuration.

Postfix on hosts without a real Internet hostnameThis section is for hosts that don't have their own Internet hostname. Typically these are systems that get a dynamic IP address via DHCP or via dialup. Postfix will let you send and receive mail just fine between accounts on a machine with a fantasy name. However, you cannot use a fantasy hostname in your email address when sending mail into the Internet, because no-one would be able to reply to your mail. In fact, more and more sites refuse mail addresses with non-existent domain names. Note: the following information is Postfix version dependent. To find out what Postfix version you have, execute the command "postconf mail_version".

Solution 1: Postfix version 2.2 and laterPostfix 2.2 uses the generic(5) address mapping to replace local fantasy email addresses by valid Internet addresses. This mapping happens ONLY when mail leaves the machine; not when you send mail between users on the same machine. The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.1 /etc/postfix/main.cf: 2 smtp_generic_maps = hash:/etc/postfix/generic 3 4 /etc/postfix/generic: 5 his@localdomain.local hisaccount@hisisp.example 6 her@localdomain.local heraccount@herisp.example 7 @localdomain.local hisaccount+local@hisisp.example

When mail is sent to a remote host via SMTP: Line 5 replaces his@localdomain.local by his ISP mail address, Line 6 replaces her@localdomain.local by her ISP mail address, and Line 7 replaces other local addresses by his ISP account, with an address extension of +local (this example assumes that the ISP supports "+" style address extensions). Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/generic" whenever you change the generic table.

Solution 2: Postfix version 2.1 and earlierThe solution with older Postfix systems is to use valid Internet addresses where possible, and to let Postfix map valid Internet addresses to local fantasy addresses. With this, you can send mail to the Internet and to local fantasy addresses, including mail to local fantasy addresses that don't have a valid Internet address of their own. The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.1 /etc/postfix/main.cf: 2 myhostname = hostname.localdomain 3 mydomain = localdomain

4 5 canonical_maps = hash:/etc/postfix/canonical 6 7 virtual_alias_maps = hash:/etc/postfix/virtual 8 9 /etc/postfix/canonical: 10 your-login-name your-account@your-isp.com 11 12 /etc/postfix/virtual: 13 your-account@your-isp.com your-login-name

Translation: Lines 2-3: Substitute your fantasy hostname here. Do not use a domain name that is already in use by real organizations on the Internet. See RFC 2606 for examples of domain names that are guaranteed not to be owned by anyone. Lines 5, 9, 10: This provides the mapping from "your-login-name@hostname.localdomain" to "your-account@your-isp.com". This part is required. Lines 7, 12, 13: Deliver mail for "your-account@your-isp.com" locally, instead of sending it to the ISP. This part is not required but is convenient. Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/canonical" whenever you change the canonical table. Execute the command "postmap /etc/postfix/virtual" whenever you change the virtual table.

Enabling SASL authentication in the Postfix SMTP/LMTP clientThis section shows a typical scenario where the Postfix SMTP client sends all messages via a mail gateway server that requires SASL authentication. Trouble solving tips: If your SASL logins fail with "SASL authentication failure: No worthy mechs found" in the mail logfile, then see the section "Postfix SMTP/LMTP client policy - SASL mechanism properties". For a solution to a more obscure class of SASL authentication failures, see "Postfix SMTP/LMTP client policy - SASL mechanism names". To make the example more readable we introduce it in two parts. The first part takes care of the basic configuration, while the second part sets up the username/password information./etc/postfix/main.cf: smtp_sasl_auth_enable = yes relayhost = [mail.isp.example] # Alternative form: # relayhost = [mail.isp.example]:submission smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd

The smtp_sasl_auth_enable setting enables client-side authentication. We will configure the client's username and password information in the second part of the example.

The relayhost setting forces the Postfix SMTP to send all remote messages to the specified mail server instead of trying to deliver them directly to their destination. In the relayhost setting, the "[" and "]" prevent the Postfix SMTP client from looking up MX (mail exchanger) records for the enclosed name. The relayhost destination may also specify a non-default TCP port. For example, the alternative form [mail.isp.example]:submission tells Postfix to connect to TCP network port 587, which is reserved for email client applications. The Postfix SMTP client is compatible with SMTP servers that use the non-standard "AUTH=method...." syntax in response to the EHLO command; this requires no additional Postfix client configuration. The Postfix SMTP client does not support the obsolete "wrappermode" protocol, which uses TCP port 465 on the SMTP server. See TLS_README for a solution that uses the stunnel command. With the smtp_sasl_password_maps parameter, we configure the Postfix SMTP client to send username and password information to the mail gateway server. As discussed in the next section, the Postfix SMTP client supports multiple ISP accounts. For this reason the username and password are stored in a table that contains one username/password combination for each mail gateway server./etc/postfix/sasl_passwd: # destination credentials [mail.isp.example] username:password # Alternative form: # [mail.isp.example]:submission username:password

Important Keep the SASL client password file in /etc/postfix, and make the file read+write only for root to protect the username/password combinations against other users. The Postfix SMTP client will still be able to read the SASL client passwords. It opens the file as user root before it drops privileges, and before entering an optional chroot jail. Use the postmap command whenever you change the /etc/postfix/sasl_passwd file. If you specify the "[" and "]" in the relayhost destination, then you must use the same form in the smtp_sasl_password_maps file. If you specify a non-default TCP Port (such as ":submission" or ":587") in the relayhost destination, then you must use the same form in the smtp_sasl_password_maps file.

Configuring Sender-Dependent SASL authenticationPostfix supports different ISP accounts for different sender addresses (version 2.3 and later). This can be useful when one person uses the same machine for work and for personal use, or when people with different ISP accounts share the same Postfix server. To make this possible, Postfix supports per-sender SASL passwords and per-sender relay hosts. In the example below, the Postfix SMTP client will search the SASL password file by sender address before it searches that same file by destination. Likewise, the Postfix trivial-rewrite(8) daemon will search the per-sender relayhost file, and use the default relayhost setting only as a final resort.

/etc/postfix/main.cf: smtp_sender_dependent_authentication = yes sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay smtp_sasl_auth_enable = yes smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd relayhost = [mail.isp.example] # Alternative form: # relayhost = [mail.isp.example]:submission /etc/postfix/sasl_passwd: # Per-sender authentication; see also /etc/postfix/sender_relay. user1@example.com username2:password2 user2@example.net username2:password2 # Login information for the default relayhost. [mail.isp.example] username:password # Alternative form: # [mail.isp.example]:submission username:password /etc/postfix/sender_relay: # Per-sender provider; see also /etc/postfix/sasl_passwd. user1@example.com [mail.example.com]:submission user2@example.net [mail.example.net]

If you are creative, then you can try to combine the two tables into one single MySQL database, and configure different Postfix queries to extract the appropriate information. Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/sasl_passwd" whenever you change the sasl_passwd table. Execute the command "postmap /etc/postfix/sender_relay" whenever you change the sender_relay table.

Postfix Standard Configuration ExamplesPurpose of this documentThis document presents a number of typical Postfix configurations. This document should be reviewed after you have followed the basic configuration steps as described in the BASIC_CONFIGURATION_README document. In particular, do not proceed here if you don't already have Postfix working for local mail submission and for local mail delivery. The first part of this document presents standard configurations that each solve one specific problem. Postfix on a stand-alone Internet host Postfix on a null client Postfix on a local network Postfix email firewall/gateway

The second part of this document presents additional configurations for hosts in specific environments. Delivering some but not all accounts locally Running Postfix behind a firewall Configuring Postfix as primary or backup MX host for a remote site Postfix on a dialup machine Postfix on hosts without a real Internet hostname

Postfix on a stand-alone Internet hostPostfix should work out of the box without change on a stand-alone machine that has direct Internet access. At least, that is how Postfix installs when you download the Postfix source code via http://www.postfix.org/. You can use the command "postconf -n" to find out what settings are overruled by your main.cf. Besides a few pathname settings, few parameters should be set on a stand-alone box, beyond what is covered in the BASIC_CONFIGURATION_README document:/etc/postfix/main.cf: # Optional: send mail as user@domainname instead of user@hostname. #myorigin = $mydomain # Optional: specify NAT/proxy external address. #proxy_interfaces = 1.2.3.4 # Alternative 1: don't relay mail from other hosts. mynetworks_style = host relay_domains = # Alternative 2: relay mail from local clients only.

# mynetworks = 192.168.1.0/28 # relay_domains =

See also the section "Postfix on hosts without a real Internet hostname" if this is applicable to your configuration.

Postfix on a null clientA null client is a machine that can only send mail. It receives no mail from the network, and it does not deliver any mail locally. A null client typically uses POP, IMAP or NFS for mailbox access. In this example we assume that the Internet domain name is "example.com" and that the machine is named "nullclient.example.com". As usual, the examples show only parameters that are not left at their default settings.1 /etc/postfix/main.cf: 2 myorigin = $mydomain 3 relayhost = $mydomain 4 inet_interfaces = loopback-only 5 local_transport = error:local delivery is disabled 6 7 /etc/postfix/master.cf: 8 Comment out the local delivery agent entry

Translation: Line 2: Send mail as "user@example.com" (instead of "user@nullclient.example.com"), so that nothing ever has a reason to send mail to "user@nullclient.example.com". Line 3: Forward all mail to the mail server that is responsible for the "example.com" domain. This prevents mail from getting stuck on the null client if it is turned off while some remote destination is unreachable. Line 4: Do not accept mail from the network. Lines 5-8: Disable local mail delivery. All mail goes to the mail server as specified in line 3.

Postfix on a local networkThis section describes a local area network environment of one main server and multiple other systems that send and receive email. As usual we assume that the Internet domain name is "example.com". All systems are configured to send mail as "user@example.com", and all systems receive mail for "user@hostname.example.com". The main server also receives mail for "user@example.com". We call this machine by the name of mailhost.example.com. A drawback of sending mail as "user@example.com" is that mail for "root" and other system accounts is also sent to the central mailhost. See the section "Delivering some but not all accounts locally" below for possible solutions. As usual, the examples show only parameters that are not left at their default settings. First we present the non-mailhost configuration, because it is the simpler one. This machine sends mail as "user@example.com" and is final destination for "user@hostname.example.com".1 /etc/postfix/main.cf: 2 myorigin = $mydomain 3 mynetworks = 127.0.0.0/8 10.0.0.0/24 4 relay_domains = 5 # Optional: forward all non-local mail to mailhost 6 #relayhost = $mydomain

Translation: Line 2: Send mail as "user@example.com". Line 3: Specify the trusted networks. Line 4: This host does not relay mail from untrusted networks. Line 6: This is needed if no direct Internet access is available. See also below, "Postfix behind a firewall". Next we present the mailhost configuration. This machine sends mail as "user@example.com" and is final destination for "user@hostname.example.com" as well as "user@example.com".1 DNS: 2 example.com IN MX 10 mailhost.example.com. 3 4 /etc/postfix/main.cf: 5 myorigin = $mydomain 6 mydestination = $myhostname localhost.$mydomain localhost $mydomain 7 mynetworks = 127.0.0.0/8 10.0.0.0/24 8 relay_domains = 9 # Optional: forward all non-local mail to firewall 10 #relayhost = [firewall.example.com]

Translation: Line 2: Send mail for the domain "example.com" to the machine mailhost.example.com. Remember to specify the "." at the end of the line. Line 5: Send mail as "user@example.com". Line 6: This host is the final mail destination for the "example.com" domain, in addition to the names of the machine itself. Line 7: Specify the trusted networks. Line 8: This host does not relay mail from untrusted networks. Line 10: This is needed only when the mailhost has to forward non-local mail via a mail server on a firewall. The [] forces Postfix to do no MX record lookups. In an environment like this, users access their mailbox in one or more of the following ways: Mailbox access via NFS or equivalent. Mailbox access via POP or IMAP. Mailbox on the user's preferred machine. In the latter case, each user has an alias on the mailhost that forwards mail to her preferred machine:/etc/aliases: joe: joe@joes.preferred.machine jane: jane@janes.preferred.machine

On some systems the alias database is not in /etc/aliases. To find out the location for your system, execute the command "postconf alias_maps". Execute the command "newaliases" whenever you change the aliases file.

Postfix email firewall/gatewayThe idea is to set up a Postfix email firewall/gateway that forwards mail for "example.com" to an inside gateway machine but rejects mail for "anything.example.com". There is only one problem: with "relay_domains = example.com", the firewall normally also accepts mail for "anything.example.com". That would not be right. Note: this example requires Postfix version 2.0 and later. To find out what Postfix version you have, execute the command "postconf mail_version". The solution is presented in multiple parts. This first part gets rid of local mail delivery on the firewall, making the firewall harder to break.1 /etc/postfix/main.cf: 2 myorigin = example.com 3 mydestination = 4 local_recipient_maps = 5 local_transport = error:local mail delivery is disabled 6 7 /etc/postfix/master.cf: 8 Comment out the local delivery agent

Translation: Line 2: Send mail from this machine as "user@example.com", so that no reason exists to send mail to "user@firewall.example.com". Lines 3-8: Disable local mail delivery on the firewall machine. For the sake of technical correctness the firewall must be able to receive mail for postmaster@[firewall ip address]. Reportedly, some things actually expect this ability to exist. The second part of the solution therefore adds support for postmaster@[firewall ip address], and as a bonus we do abuse@[firewall ip address] as well. All the mail to these two accounts is forwarded to an inside address.1 /etc/postfix/main.cf: 2 virtual_alias_maps = hash:/etc/postfix/virtual 3 4 /etc/postfix/virtual: 5 postmaster postmaster@example.com 6 abuse abuse@example.com

Translation: Because mydestination is empty (see the previous example), only address literals matching $inet_interfaces or $proxy_interfaces are deemed local. So "localpart@[a.d.d.r]" can be matched as simply "localpart" in canonical(5) and virtual(5). This avoids the need to specify firewall IP addresses into Postfix configuration files. The last part of the solution does the email forwarding, which is the real purpose of the firewall email function.1 /etc/postfix/main.cf: 2 mynetworks = 127.0.0.0/8 12.34.56.0/24 3 relay_domains = example.com 4 parent_domain_matches_subdomains = 5 debug_peer_list smtpd_access_maps 6 smtpd_recipient_restrictions = 7 permit_mynetworks reject_unauth_destination 8 9 relay_recipient_maps = hash:/etc/postfix/relay_recipients

10 transport_maps = hash:/etc/postfix/transport 11 12 /etc/postfix/relay_recipients: 13 user1@example.com x 14 user2@example.com x 15 . . . 16 17 /etc/postfix/transport: 18 example.com smtp:[inside-gateway.example.com]

Translation: Lines 1-7: Accept mail from local systems in $mynetworks, and accept mail from outside for "user@example.com" but not for "user@anything.example.com". The magic is in lines 4-5. Lines 9, 12-14: Define the list of valid addresses in the "example.com" domain that can receive mail from the Internet. This prevents the mail queue from filling up with undeliverable MAILER-DAEMON messages. If you can't maintain a list of valid recipients then you must specify "relay_recipient_maps =" (that is, an empty value), or you must specify an "@example.com x" wild-card in the relay_recipients table. Lines 10, 17-18: Route mail for "example.com" to the inside gateway machine. The [] forces Postfix to do no MX lookup. Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/relay_recipients" whenever you change the relay_recipients table. Execute the command "postmap /etc/postfix/transport" whenever you change the transport table. In some installations, there may be separate instances of Postfix processing inbound and outbound mail on a multi-homed firewall. The inbound Postfix instance has an SMTP server listening on the external firewall interface, and the outbound Postfix instance has an SMTP server listening on the internal interface. In such a configuration is it is tempting to configure $inet_interfaces in each instance with just the corresponding interface address. In most cases, using inet_interfaces in this way will not work, because as documented in the $inet_interfaces reference manual, the smtp(8) delivery agent will also use the specified interface address as the source address for outbound connections and will be unable to reach hosts on "the other side" of the firewall. The symptoms are that the firewall is unable to connect to hosts that are in fact up. See the inet_interfaces parameter documentation for suggested work-arounds.

Delivering some but not all accounts locallyA drawback of sending mail as "user@example.com" (instead of "user@hostname.example.com") is that mail for "root" and other system accounts is also sent to the central mailhost. In order to deliver such accounts locally, you can set up virtual aliases as follows:1 /etc/postfix/main.cf: 2 virtual_alias_maps = hash:/etc/postfix/virtual 3 4 /etc/postfix/virtual: 5 root root@localhost 6 . . .

Translation: Line 5: As described in the virtual(5) manual page, the bare name "root" matches

"root@site" when "site" is equal to $myorigin, when "site" is listed in $mydestination, or when it matches $inet_interfaces or $proxy_interfaces. Execute the command "postmap /etc/postfix/virtual" after editing the file.

Running Postfix behind a firewallThe simplest way to set up Postfix on a host behind a firewalled network is to send all mail to a gateway host, and to let that mail host take care of internal and external forwarding. Examples of that are shown in the local area network section above. A more sophisticated approach is to send only external mail to the gateway host, and to send intranet mail directly. Note: this example requires Postfix version 2.0 and later. To find out what Postfix version you have, execute the command "postconf mail_version". The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.1 /etc/postfix/main.cf: 2 transport_maps = hash:/etc/postfix/transport 3 relayhost = 4 # Optional for a machine that isn't "always on" 5 #fallback_relay = [gateway.example.com] 6 7 /etc/postfix/transport: 8 # Internal delivery. 9 example.com : 10 .example.com : 11 # External delivery. 12 * smtp:[gateway.example.com]

Translation: Lines 2, 7-12: Request that intranet mail is delivered directly, and that external mail is given to a gateway. Obviously, this example assumes that the organization uses DNS MX records internally. The [] forces Postfix to do no MX lookup. Line 3: IMPORTANT: do not specify a relayhost in main.cf. Line 5: This prevents mail from being stuck in the queue when the machine is turned off. Postfix tries to deliver mail directly, and gives undeliverable mail to a gateway. Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/transport" whenever you edit the transport table.

Configuring Postfix as primary or backup MX host for a remote siteThis section presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document. When your system is SECONDARY MX host for a remote site this is all you need:1 DNS: 2 the.backed-up.domain.tld your.machine.tld. 3 4 /etc/postfix/main.cf: IN MX 100

5 relay_domains = . . . the.backed-up.domain.tld 6 smtpd_recipient_restrictions = 7 permit_mynetworks reject_unauth_destination 8 9 # You must specify your NAT/proxy external address. 10 #proxy_interfaces = 1.2.3.4 11 12 relay_recipient_maps = hash:/etc/postfix/relay_recipients 13 14 /etc/postfix/relay_recipients: 15 user1@the.backed-up.domain.tld x 16 user2@the.backed-up.domain.tld x 17 . . .

When your system is PRIMARY MX host for a remote site you need the above, plus:18 /etc/postfix/main.cf: 19 transport_maps = hash:/etc/postfix/transport 20 21 /etc/postfix/transport: 22 the.backed-up.domain.tld relay:[their.mail.host.tld]

Important notes: Do not list the.backed-up.domain.tld in mydestination. Do not list the.backed-up.domain.tld in virtual_alias_domains. Do not list the.backed-up.domain.tld in virtual_mailbox_domains. Lines 1-7: Forward mail from the Internet for "the.backed-up.domain.tld" to the primary MX host for that domain. Line 10: This is a must if Postfix receives mail via a NAT relay or proxy that presents a different IP address to the world than the local machine. Lines 12-16: Define the list of valid addresses in the "the.backed-up.domain.tld" domain. This prevents your mail queue from filling up with undeliverable MAILER-DAEMON messages. If you can't maintain a list of valid recipients then you must specify "relay_recipient_maps =" (that is, an empty value), or you must specify an "@the.backedup.domain.tld x" wild-card in the relay_recipients table. Line 22: The [] forces Postfix to do no MX lookup. Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/transport" whenever you change the transport table. NOTE for Postfix < 2.2: Do not use the fallback_relay feature when relaying mail for a backup or primary MX domain. Mail would loop between the Postfix MX host and the fallback_relay host when the final destination is unavailable. In main.cf specify "relay_transport = relay", In master.cf specify "-o fallback_relay =" at the end of the relay entry. In transport maps, specify "relay:nexthop..." as the right-hand side for backup or primary MX domain entries. These are default settings in Postfix version 2.2 and later.

Postfix on a dialup machineThis section applies to dialup connections that are down most of the time. For dialup connections that are up 24x7, see the local area network section above. This section presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document. If you do not have your own hostname and IP address (usually with dialup, cable TV or DSL connections) then you should also study the section on "Postfix on hosts without a real Internet hostname". Route all outgoing mail to your network provider. If your machine is disconnected most of the time, there isn't a lot of opportunity for Postfix to deliver mail to hard-to-reach corners of the Internet. It's better to give the mail to a machine that is connected all the time. In the example below, the [] prevents Postfix from trying to look up DNS MX records./etc/postfix/main.cf: relayhost = [smtprelay.someprovider.com]

Disable spontaneous SMTP mail delivery (if using on-demand dialup IP only). Normally, Postfix attempts to deliver outbound mail at its convenience. If your machine uses on-demand dialup IP, this causes your system to place a telephone call whenever you submit new mail, and whenever Postfix retries to deliver delayed mail. To prevent such telephone calls from being placed, disable spontaneous SMTP mail deliveries./etc/postfix/main.cf: defer_transports = smtp (Only for on-demand dialup IP hosts)

Disable SMTP client DNS lookups (dialup LAN only)./etc/postfix/main.cf: disable_dns_lookups = yes (Only for on-demand dialup IP hosts)

Flush the mail queue whenever the Internet link is established. Put the following command into your PPP or SLIP dialup scripts:/usr/sbin/sendmail -q (whenever the Internet link is up)

The exact location of the Postfix sendmail command is system-specific. Use the command "postconf sendmail_path" to find out where the Postfix sendmail command is located on your machine. In order to find out if the mail queue is flushed, use something like:#!/bin/sh # Start mail deliveries. /usr/sbin/sendmail -q # Allow deliveries to start. sleep 10 # Loop until all messages have been tried at least once. while mailq | grep '^[^ ]*\*' >/dev/null do sleep 10 done

If you have disabled spontaneous SMTP mail delivery, you also need to run the "sendmail -q" command every now and then while the dialup link is up, so that newly-posted mail is flushed from the queue.

Postfix on hosts without a real Internet hostnameThis section is for hosts that don't have their own Internet hostname. Typically these are systems that get a dynamic IP address via DHCP or via dialup. Postfix will let you send and receive mail just fine between accounts on a machine with a fantasy name. However, you cannot use a fantasy hostname in your email address when sending mail into the Internet, because no-one would be able to reply to your mail. In fact, more and more sites refuse mail addresses with non-existent domain names. Note: the following information is Postfix version dependent. To find out what Postfix version you have, execute the command "postconf mail_version".

Solution 1: Postfix version 2.2 and laterPostfix 2.2 uses the generic(5) address mapping to replace local fantasy email addresses by valid Internet addresses. This mapping happens ONLY when mail leaves the machine; not when you send mail between users on the same machine. The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.1 /etc/postfix/main.cf: 2 smtp_generic_maps = hash:/etc/postfix/generic 3 4 /etc/postfix/generic: 5 his@localdomain.local hisaccount@hisisp.example 6 her@localdomain.local heraccount@herisp.example 7 @localdomain.local hisaccount+local@hisisp.example

When mail is sent to a remote host via SMTP: Line 5 replaces his@localdomain.local by his ISP mail address, Line 6 replaces her@localdomain.local by her ISP mail address, and Line 7 replaces other local addresses by his ISP account, with an address extension of +local (this example assumes that the ISP supports "+" style address extensions). Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/generic" whenever you change the generic table.

Solution 2: Postfix version 2.1 and earlierThe solution with older Postfix systems is to use valid Internet addresses where possible, and to let Postfix map valid Internet addresses to local fantasy addresses. With this, you can send mail to the Internet and to local fantasy addresses, including mail to local fantasy addresses that don't have a valid Internet address of their own. The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.1 /etc/postfix/main.cf:

2 myhostname = hostname.localdomain 3 mydomain = localdomain 4 5 canonical_maps = hash:/etc/postfix/canonical 6 7 virtual_alias_maps = hash:/etc/postfix/virtual 8 9 /etc/postfix/canonical: 10 your-login-name your-account@your-isp.com 11 12 /etc/postfix/virtual: 13 your-account@your-isp.com your-login-name

Translation: Lines 2-3: Substitute your fantasy hostname here. Do not use a domain name that is already in use by real organizations on the Internet. See RFC 2606 for examples of domain names that are guaranteed not to be owned by anyone. Lines 5, 9, 10: This provides the mapping from "your-login-name@hostname.localdomain" to "your-account@your-isp.com". This part is required. Lines 7, 12, 13: Deliver mail for "your-account@your-isp.com" locally, instead of sending it to the ISP. This part is not required but is convenient. Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m". Execute the command "postmap /etc/postfix/canonical" whenever you change the canonical table. Execute the command "postmap /etc/postfix/virtual" whenever you change the virtual table.

Postfix Address RewritingPostfix address rewriting purposeAddress rewriting is at the heart of the Postfix mail system. Postfix rewrites addresses for many different purposes. Some are merely cosmetic, and some are necessary to deliver correctly formatted mail to the correct destination. Examples of address rewriting in Postfix are: Transform an incomplete address into a complete address. For example, transform "username" into "username@example.com", or transform "username@hostname" into "username@hostname.example.com". Replace an address by an equivalent address. For example, replace "username@example.com" by "firstname.lastname@example.com" when sending mail, and do the reverse transformation when receiving mail. Replace an internal address by an external address. For example, replace "username@localdomain.local" by "isp-account@isp.example" when sending mail from a home computer to the Internet. Replace an address by multiple addresses. For example, replace the address of an alias by the addresses listed under that alias. Determine how and where to deliver mail for a specific address. For example, deliver mail for "username@example.com" with the smtp(8) delivery agent, to the hosts that are listed in the DNS as the mail servers for the domain "example.com". Although Postfix currently has no address rewriting language, it can do surprisingly powerful address manipulation via table lookup. Postfix typically uses lookup tables with fixed strings to map one address to one or multiple addresses, and typically uses regular expressions to map multiple addresses to one or multiple addresses. Fixed-string lookup tables may be in the form of local files, or in the form of NIS, LDAP or SQL databases. The DATABASE_README document gives an introduction to Postfix lookup tables. Topics covered in this document: To rewrite message headers or not, or to label as invalid Postfix address rewriting overview Address rewriting when mail is received Rewrite addresses to standard form Canonical address mapping Address masquerading Automatic BCC recipients Virtual aliasing Address rewriting when mail is delivered Resolve address to destination Mail transport switch Relocated users table Address rewriting with remote delivery

Generic mapping for outgoing SMTP mail Address rewriting with local delivery Local alias database Local per-user .forward files Local catch-all address Debugging your address manipulations

To rewrite message headers or not, or to label as invalidPostfix versions 2.1 and earlier always rewrite message header addresses, and append Postfix's own domain information to addresses that Postfix considers incomplete. While rewriting message header addresses is OK for mail with a local origin, it is undesirable for remote mail: Message header address rewriting is frowned upon by mail standards, Appending Postfix's own domain produces incorrect results with some incomplete addresses, Appending Postfix's own domain sometimes creates the appearance that spam is sent by local users. Postfix versions 2.2 give you the option to either not rewrite message headers from remote SMTP clients at all, or to label incomplete addresses in such message headers as invalid. Here is how it works: Postfix always rewrites message headers from local SMTP clients and from the Postfix sendmail command, and appends its own domain to incomplete addresses. The local_header_rewrite_clients parameter controls what SMTP clients Postfix considers local (by default, only local network interface addresses). Postfix never rewrites message header addresses from remote SMTP clients when the remote_header_rewrite_domain parameter value is empty (the default setting). Otherwise, Postfix rewrites message headers from remote SMTP clients, and appends the remote_header_rewrite_domain value to incomplete addresses. This feature can be used to append a reserved domain such as "domain.invalid", so that incomplete addresses cannot be mistaken for local addresses.

Postfix address rewriting overviewThe figure below zooms in on those parts of Postfix that are most involved with address rewriting activity. See the OVERVIEW document for an overview of the complete Postfix architecture. Names followed by a number are Postfix daemon programs, while unnumbered names represent Postfix queues or internal sources of mail messages. trivialrewrite(8) (std form) ^ | | v ^ | | v active smtp(8) -> qmgr(8) -< lmtp(8) local(8) trivialrewrite(8 ) (resolve)

smtpd(8) qmqpd(8) >- cleanup(8) -> incoming -> pickup(8) ^ ^ | |

|

v

bounces forwarding deferred notices The table below summarizes all Postfix address manipulations. If you're reading this document for the first time, skip forward to "Address rewriting when mail is received". Once you've finished reading the remainder of this document, the table will help you to quickly find what you need. Address manipulation Rewrite addresses to standard form Scope all mail Daemon Global turn-on control Selective turn-off control append_at_myorigin, local_header_rewrite_client trivialappend_dot_mydomain, s, rewrite(8 swap_bangpath, remote_header_rewrite_do ) allow_percent_hack main cleanup( canonical_maps 8) receive_override_options, local_header_rewrite_client s, remote_header_rewrite_do main receive_override_options, local_header_rewrite_client s, remote_header_rewrite_do main receive_override_options receive_override_options none

Canonical address mapping

all mail

Address masquerading

all mail

cleanup( masquerade_domains 8)

Automatic BCC recipients Virtual aliasing Resolve address to destination Mail transport switch

always_bcc, cleanup( new mail sender_bcc_maps, 8) recipient_bcc_maps all mail all mail cleanup( virtual_alias_maps 8) trivialrewrite(8 none ) trivialrewrite(8 transport_maps ) trivialrewrite(8 relocated_maps )

all mail

none

Relocated users table

all mail

none

Generic mapping table Local alias database

outgoing SMTP smtp(8) smtp_generic_maps mail local mail local(8) alias_maps only

none none none none

Local per-user .forward local mail local(8) forward_path files only Local catch-all address local mail local(8) luser_relay only

Address rewriting when mail is receivedThe cleanup(8) server receives mail from outside of Postfix as well as mail from internal sources such as forwarded mail, undeliverable mail that is bounced to the sender, and postmaster notifications about problems with the mail system. The cleanup(8) server transforms the sender, recipients and message content into a standard form before writing it to an incoming queue file. The server cleans up sender and recipient addresses in message headers and in the envelope, adds missing message headers such as From: or Date: that are required by mail standards, and removes message headers such as Bcc: that should not be present. The cleanup(8) server delegates the more complex address manipulations to the trivial-rewrite(8) server as described later in this document. Address manipulations at this stage are: Rewrite addresses to standard form Canonical address mapping Address masquerading Automatic BCC recipients Virtual aliasing

Rewrite addresses to standard formBefore the cleanup(8) daemon runs an address through any address mapping lookup table, it first rewrites the address to the standard "user@fully.qualified.domain" form, by sending the address to the trivial-rewrite(8) daemon. The purpose of rewriting to standard form is to reduce the number of entries needed in lookup tables. The Postfix trivial-rewrite(8) daemon implements the following hard-coded address manipulations: Rewrite "@hosta,@hostb:user@site" to "user@site" In case you wonder what this is, the address form above is called a route address, and specifies that mail for "user@site" be delivered via "hosta" and "hostb". Usage of this form has been deprecated for a long time. Postfix has no ability to handle route addresses, other than to strip off the route part. NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter, or if the remote_header_rewrite_domain configuration parameter specifies a nonempty value. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all". Rewrite "site!user" to "user@site" This feature is controlled by the boolean swap_bangpath parameter (default: yes). The purpose is to rewrite UUCP-style addresses to domain style. This is useful only when you receive mail via UUCP, but it probably does not hurt otherwise. NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter, or if the remote_header_rewrite_domain configuration parameter specifies a nonempty value. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all".

Rewrite "user%domain" to "user@domain" This feature is controlled by the boolean allow_percent_hack parameter (default: yes). Typically, this is used in order to deal with monstrosities such as "user %domain@otherdomain". NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter, or if the remote_header_rewrite_domain configuration parameter specifies a nonempty value. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all". Rewrite "user" to "user@$myorigin" This feature is controlled by the boolean append_at_myorigin parameter (default: yes). You should never turn off this feature, because a lot of Postfix components expect that all addresses have the form "user@domain". NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter; otherwise they append the domain name specified with the remote_header_rewrite_domain configuration parameter, if one is specified. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all". If your machine is not the main machine for $myorigin and you wish to have some users delivered locally without going via that main machine, make an entry in the virtual alias table that redirects "user@$myorigin" to "user@$myhostname". See also the "delivering some users locally" section in the STANDARD_CONFIGURATION_README document. Rewrite "user@host" to "user@host.$mydomain" This feature is controlled by the boolean append_dot_mydomain parameter (default: yes). The purpose is to get consistent treatment of different forms of the same hostname. NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter; otherwise they append the domain name specified with the remote_header_rewrite_domain configuration parameter, if one is specified. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all". Some will argue that rewriting "host" to "host.domain" is bad. That is why it can be turned off. Others like the convenience of having Postfix's own domain appended automatically. Rewrite "user@site." to "user@site" (without the trailing dot). A single trailing dot is silently removed. However, an address that ends in multiple dots will be rejected as an invalid address.

NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter, or if the remote_header_rewrite_domain configuration parameter specifies a nonempty value. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all".

Canonical address mappingThe cleanup(8) daemon uses the canonical(5) tables to rewrite addresses in message envelopes and in message headers. By default all header and envelope addresses are rewritten; this is controlled with the canonical_classes configuration parameter. NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter, or if the remote_header_rewrite_domain configuration parameter specifies a non-empty value. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all". Address rewriting is done for local and remote addresses. The mapping is useful to replace login names by "Firstname.Lastname" style addresses, or to clean up invalid domains in mail addresses produced by legacy mail systems. Canonical mapping is disabled by default. To enable, edit the canonical_maps parameter in the main.cf file and specify one or more lookup tables, separated by whitespace or commas. Example:/etc/postfix/main.cf: canonical_maps = hash:/etc/postfix/canonical /etc/postfix/canonical: wietse Wietse.Venema

For static mappings as shown above, lookup tables such as hash:, ldap:, mysql: or pgsql: are sufficient. For dynamic mappings you can use regular expression tables. This requires that you become intimately familiar with the ideas expressed in regexp_table(5), pcre_table(5) and canonical(5). In addition to the canonical maps which are applied to both sender and recipient addresses, you can specify canonical maps that are applied only to sender addresses or to recipient addresses. Example:/etc/postfix/main.cf: sender_canonical_maps = hash:/etc/postfix/sender_canonical recipient_canonical_maps = hash:/etc/postfix/recipient_canonical

The sender and recipient canonical maps are applied before the common canonical maps. The sender_canonical_classes and recipient_canonical_classes parameters control what addresses are subject to sender_canonical_maps and recipient_canonical_maps mappings, respectively. Sender-specific rewriting is useful when you want to rewrite ugly sender addresses to pretty ones, and still want to be able to send mail to the those ugly address without creating a mailer loop. Canonical mapping can be turned off selectively for mail received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file. This feature is available in Postfix version 2.1 and later. Example:/etc/postfix/master.cf:

127.0.0.1:10026 inet n n -o receive_override_options=no_address_mappings

-

smtpd

Note: do not specify whitespace around the "=" here.

Address masqueradingAddress masquerading is a method to hide hosts inside a domain behind their mail gateway, and to make it appear as if the mail comes from the gateway itself, instead of from individual machines. NOTE: Postfix versions 2.2 and later rewrite message headers from remote SMTP clients only if the client matches the local_header_rewrite_clients parameter, or if the remote_header_rewrite_domain configuration parameter specifies a non-empty value. To get the behavior before Postfix 2.2, specify "local_header_rewrite_clients = static:all". Address masquerading is disabled by default, and is implemented by the cleanup(8) server. To enable, edit the masquerade_domains parameter in the main.cf file and specify one or more domain names separated by whitespace or commas. When Postfix tries to masquerade a domain, it processes the list from left to right, and processing stops at the first match. Example:/etc/postfix/main.cf: masquerade_domains = foo.example.com example.com

strips "any.thing.foo.example.com" to "foo.example.com", but strips "any.thing.else.example.com" to "example.com". A domain name prefixed with "!" means do not masquerade this domain or its subdomains:/etc/postfix/main.cf: masquerade_domains = !foo.example.com example.com

does not change "any.thing.foo.example.com" and "foo.example.com", but strips "any.thing.else.example.com" to "example.com". The masquerade_exceptions configuration parameter specifies what user names should not be subjected to address masquerading. Specify one or more user names separated by whitespace or commas. Example:/etc/postfix/main.cf: masquerade_exceptions = root

By default, Postfix makes no exceptions. Subtle point: by default, address masquerading is applied only to message headers and to envelope sender addresses, but not to envelope recipients. This allows you to use address masquerading on a mail gateway machine, while still being able to forward mail from outside to users on individual machines. In order to subject envelope recipient addresses to masquerading, too, specify (Postfix version 1.1 and later):/etc/postfix/main.cf: masquerade_classes = envelope_sender, envelope_recipient, header_sender, header_recipient

If you rewrite the envelope recipient like this, Postfix will no longer be able to send mail to individual machines.

Address masquerading can be turned off selectively for mail received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file. This feature is available in Postfix version 2.1 and later. Example:/etc/postfix/master.cf: 127.0.0.1:10026 inet n n -o receive_override_options=no_address_mappings smtpd

Note: do not specify whitespace around the "=" here.

Automatic BCC recipientsAfter applying the canonical and masquerade mappings, the cleanup(8) daemon can generate optional BCC (blind carbon-copy) recipients. Postfix provides three mechanisms: always_bcc = address Deliver a copy of all mail to the specified address. In Postfix versions before 2.1, this feature is implemented by smtpd(8), qmqpd(8), or pickup(8). sender_bcc_maps = type:table Search the specified "type:table" lookup table with the envelope sender address for an automatic BCC address. This feature is available in Postfix 2.1 and later. recipient_bcc_maps = type:table Search the specified "type:table" lookup table with the envelope recipient address for an automatic BCC address. This feature is available in Postfix 2.1 and later. Note: automatic BCC recipients are produced only for new mail. To avoid mailer loops, automatic BCC recipients are not generated for mail that Postfix forwards internally, nor for mail that Postfix generates itself. Automatic BCC recipients (including always_bcc) can be turned off selectively for mail received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file. This feature is available in Postfix version 2.1 and later. Example:/etc/postfix/master.cf: 127.0.0.1:10026 inet n n -o receive_override_options=no_address_mappings smtpd

Note: do not specify whitespace around the "=" here.

Virtual aliasingBefore writing the recipients to the queue file, the cleanup(8) daemon uses the optional virtual(5) alias tables to redirect mail for recipients. The mapping affects only envelope recipient addresses; it has no effect on message headers or envelope sender addresses. Virtual alias lookups are useful to redirect mail for virtual alias domains to real user mailboxes, and to redirect mail for domains that no longer exist. Virtual alias lookups can also be used to transform " Firstname.Lastname " back into UNIX login names, although it seems that local aliases may be a more appropriate vehicle. See the VIRTUAL_README document for an overview of methods to host virtual domains with

Postfix. Virtual aliasing is disabled by default. To enable, edit the virtual_alias_maps parameter in the main.cf file and specify one or more lookup tables, separated by whitespace or commas. Example:/etc/postfix/main.cf: virtual_alias_maps = hash:/etc/postfix/virtual /etc/postfix/virtual: Wietse.Venema wietse

Addresses found in virtual alias maps are subjected to another iteration of virtual aliasing, but are not subjected to canonical mapping, in order to avoid loops. For static mappings as shown above, lookup tables such as hash:, ldap:, mysql: or pgsql: are sufficient. For dynamic mappings you can use regular expression tables. This requires that you become intimately familiar with the ideas expressed in regexp_table(5), pcre_table(5) and virtual(5). Virtual aliasing can be turned off selectively for mail received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file. This feature is available in Postfix version 2.1 and later. Example:/etc/postfix/master.cf: 127.0.0.1:10026 inet n n -o receive_override_options=no_address_mappings smtpd

Note: do not specify whitespace around the "=" here. At this point the message is ready to be stored into the Postfix incoming queue.

Address rewriting when mail is deliveredThe Postfix queue manager sorts mail according to its destination and gives it to Postfix delivery agents such as local(8), smtp(8), or lmtp(8). Just like the cleanup(8) server, the Postfix queue manager delegates the more complex address manipulations to the trivial-rewrite(8) server. Address manipulations at this stage are: Resolve address to destination Mail transport switch Relocated users table Each Postfix delivery agent tries to deliver the mail to its destination, while encapsulating the sender, recipients, and message content according to the rules of the SMTP, LMTP, etc. protocol. When mail cannot be delivered, it is either returned to the sender or moved to the deferred queue and tried again later. Address manipulations when mail is delivered via the smtp(8) delivery agent: Generic mapping for outgoing SMTP mail Address manipulations when mail is delivered via the local(8) delivery agent: Local alias database Local per-user .forward files Local catch-all address

The remainder of this document presents each address manipulation step in more detail, with specific examples or with pointers to documentation with examples.

Resolve address to destinationThe Postfix qmgr(8) queue manager selects new mail from the incoming queue or old mail from the deferred queue, and asks the trivial-rewrite(8) address rewriting and resolving daemon where it should be delivered. As of version 2.0, Postfix distinguishes four major address classes. Each class has its own list of domain names, and each class has its own default delivery method, as shown in the table below. See the ADDRESS_CLASS_README document for the fine details. Postfix versions before 2.0 only distinguish between local delivery and everything else. Destination domain list $mydestination, $inet_interfaces, $proxy_interfaces $virtual_mailbox_domains $relay_domains none Default delivery method $local_transport $virtual_transport $relay_transport $default_transport Availability Postfix 1.0 Postfix 2.0 Postfix 2.0 Postfix 1.0

Mail transport switchOnce the trivial-rewrite(8) daemon has determined a default delivery method it searches the optional transport(5) table for information that overrides the message destination and/or delivery method. Typical use of the transport(5) table is to send mail to a system that is not connected to the Internet, or to use a special SMTP client configuration for destinations that have special requirements. See, for example, the STANDARD_CONFIGURATION_README and UUCP_README documents, and the examples in the transport(5) manual page. Transport table lookups are disabled by default. To enable, edit the transport_maps parameter in the main.cf file and specify one or more lookup tables, separated by whitespace or commas. Example:/etc/postfix/main.cf: transport_maps = hash:/etc/postfix/transport

Relocated users tableNext, the trivial-rewrite(8) address rewriting and resolving daemon runs each recipient through the relocated(5) database. This table provides information on how to reach users that no longer have an account, or what to do with mail for entire domains that no longer exist. When mail is sent to an address that is listed in this table, the message is returned to the sender with an informative message. The relocated(5) database is searched after transport(5) table lookups, in anticipation of transport(5) tables that can replace one recipient address by a different one. Lookups of relocated users are disabled by default. To enable, edit the relocated_maps parameter in the main.cf file and specify one or more lookup tables, separated by whitespace or commas. Example:/etc/postfix/main.cf:

relocated_maps = hash:/etc/postfix/relocated /etc/postfix/relocated: username@example.com otheruser@elsewhere.tld

As of Postfix version 2, mail for a relocated user will be rejected by the SMTP server with the reason "user has moved to otheruser@elsewhere.tld". Older Postfix versions will receive the mail first, and then return it to the sender as undeliverable, with the same reason.

Generic mapping for outgoing SMTP mailSome hosts have no valid Internet domain name, and instead use a name such as localdomain.local. This can be a problem when you want to send mail over the Internet, because many mail servers reject mail addresses with invalid domain names. With the smtp_generic_maps parameter you can specify generic(5) lookup tables that replace local mail addresses by valid Internet addresses when mail leaves the machine via SMTP. The generic(5) mapping replaces envelope and header addresses, and is non-recursive. It does not happen when you send mail between addresses on the local machine. This feature is available in Postfix version 2.2 and later. Example:/etc/postfix/main.cf: smtp_generic_maps = hash:/etc/postfix/generic /etc/postfix/generic: his@localdomain.local her@localdomain.local @localdomain.local hisaccount+local@hisisp.example hisaccount@hisisp.example heraccount@herisp.example

When mail is sent to a remote host via SMTP, this replaces his@localdomain.local by his ISP mail address, replaces her@localdomain.local by her ISP mail address, and replaces other local addresses by his ISP account, with an address extension of +local (this example assumes that the ISP supports "+" style address extensions).

Local alias databaseWhen mail is to be delivered locally, the local(8) delivery agent runs each local recipient name through the aliases(5) database. The mapping does not affect addresses in message headers. Local aliases are typically used to implement distribution lists, or to direct mail for standard aliases such as postmaster to real people. The table can also be used to map "Firstname.Lastname" addresses to login names. Alias lookups are enabled by default. The default configuration depends on the operating system environment, but it is typically one of the following:/etc/postfix/main.cf: alias_maps = hash:/etc/aliases alias_maps = dbm:/etc/aliases, nis:mail.aliases

The pathname of the alias database file is controlled with the alias_database configuration parameter. The value is system dependent. Usually it is one of the following:/etc/postfix/main.cf: alias_database = hash:/etc/aliases (4.4BSD, LINUX) alias_database = dbm:/etc/aliases (4.3BSD, SYSV /usr/local/lib/sasl for version 1.5.x or /usr/lib/sasl2 -> /usr/local/lib/sasl2 for version 2.1.x. Reportedly, Microsoft Outlook (Express) requires the non-standard LOGIN and/or NTLM authentication mechanism. To enable these authentication mechanisms, build the Cyrus SASL libraries with:% ./configure --enable-login --enable-ntlm

Building Postfix with Cyrus SASL support These instructions assume that you build Postfix from source code as described in the INSTALL document. Some modification may be required if you build Postfix from a vendor-specific source package. The following assumes that the Cyrus SASL include files are in /usr/local/include, and that the Cyrus SASL libraries are in /usr/local/lib. On some systems this generates the necessary Makefile definitions: Cyrus SASL version 2.1.x% make tidy # if you have left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"

Cyrus SASL version 1.5.x% make tidy # if you have left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"

On Solaris 2.x you need to specify run-time link information, otherwise the ld.so run-time linker will not find the SASL shared library: Cyrus SASL version 2.1.x% make tidy # remove left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \ -R/usr/local/lib -lsasl2"

Cyrus SASL version 1.5.x% make tidy # if you have left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ -I/usr/local/include" AUXLIBS="-L/usr/local/lib \ -R/usr/local/lib -lsasl"

Using Cyrus SASL version 1.5.xPostfix supports Cyrus SASL version 1.x, but you shouldn't use it unless you are forced to. The makers of Cyrus SASL write: This library is being deprecated and applications should transition to using the SASLv2 library (source: Project Cyrus: Downloads). If you still need to set it up, here's a quick rundown: Read the regular section on SMTP server configurations for the Cyrus SASL framework. The differences are: Cyrus SASL version 1.5.x searches for configuration (smtpd.conf) in /usr/lib/sasl/ only. You must place the configuration in that directory. Some systems may have modified Cyrus SASL and put the files into e.g. /var/lib/sasl/. Use the saslpasswd command instead of saslpasswd2 to create users in sasldb.

Use the sasldblistusers command instead of sasldblistusers2 to find users in sasldb. In the smtpd.conf file you can't use mech_list to limit the range of mechanisms offered. Instead, remove their libraries from /usr/lib/sasl/ (and remember remove those files again when a system update re-installs new versions).

Credits Postfix SASL support was originally implemented by Till Franke of SuSE Rhein/Main AG. Wietse trimmed down the code to only the bare necessities. Support for Cyrus SASL version 2 was contributed by Jason Hoos. Liviu Daia added smtpd_sasl_application_name, separated reject_sender_login_mismatch into reject_authenticated_sender_login_mismatch and reject_unauthenticated_sender_login_mismatch, and revised the docs. Wietse made another iteration through the code to add plug-in support for multiple SASL implementations, and for reasons that have been lost, also changed smtpd_sasl_application_name into smtpd_sasl_path. The Dovecot SMTP server-only plug-in was originally implemented by Timo Sirainen of Procontrol, Finland. Patrick Ben Koetter revised this document for Postfix 2.4 and made much needed updates. Patrick Ben Koetter revised this document again for Postfix 2.7 and made much needed updates.

Postfix IPv6 SupportIntroductionPostfix 2.2 introduces support for the IPv6 (IP version 6) protocol. IPv6 support for older Postfix versions was available as an add-on patch. The section "Compatibility with Postfix :]]" (on some systems you should specify "\>" instead; for details see your system documentation). The "if /pattern/" and "endif" eliminate unnecessary matching attempts. DO NOT indent lines starting with /pattern/ between the "if" and "endif"! The two "Message-ID:.* :]]" (on some systems you should specify "\< and \>" instead; for details see your system documentation). The "\." matches "." literally. Without the "\", the "." would match any character.

Blocking backscatter mail with other forged informationAnother sign of forgery can be found in the IP address that is recorded in Received: headers next to your HELO host or domain name. This information must be used with care, though. Some mail

servers are behind a network address translator and never see the true client IP address.

Blocking backscatter mail from virus scannersWith all the easily recognizable forgeries eliminated, there is one category of backscatter mail that remains, and that is notifications from virus scanner software. Unfortunately, some virus scanning software doesn't know that viruses forge sender addresses. To make matters worse, the software also doesn't know how to report a mail delivery problem, so that we cannot use the above techniques to recognize forgeries. Recognizing virus scanner mail is an error prone process, because there is a lot of variation in report formats. The following is only a small example of message header patterns. For a large collection of header and body patterns that recognize virus notification email, see http://www.dkuug.dk/keld/virus/ or http://www.t29.dk/antiantivirus.txt./etc/postfix/header_checks: /^Subject: *Your email contains VIRUSES/ DISCARD virus notification /^Content-Disposition:.*VIRUS1_DETECTED_AND_REMOVED/ DISCARD virus notification /^Content-Disposition:.*VirusWarning.txt/ DISCARD virus notification

Note: these documents haven't been updated since 2004, so they are useful only as a starting point. A plea to virus or spam scanner operators: please do not make the problem worse by sending return mail to forged sender addresses. You're only harassing innocent people. If you must return mail to the purported sender, please return the full message headers, so that the sender can filter out the obvious forgeries.

Postfix Built-in Content InspectionBuilt-in content inspection introductionPostfix supports a built-in filter mechanism that examines message header and message body content, one line at a time, before it is stored in the Postfix queue. The filter is usually implemented with POSIX or PCRE regular expressions, as described in the header_checks(5) manual page. The original purpose of the built-in filter is to stop an outbreak of specific email worms or viruses, and it does this job well. The filter has also helped to block bounced junk email, bounced email from worms or viruses, and notifications from virus detection systems. Information about this secondary application is given in the BACKSCATTER_README document. Because the built-in filter is optimized for stopping specific worms and virus outbreaks, it has limitations that make it NOT suitable for general junk email and virus detection. For that, you should use one of the external content inspection methods that are described in the FILTER_README, SMTPD_PROXY_README and MILTER_README documents. The following diagram gives an over-all picture of how Postfix built-in content inspection works: Postmaster notifications | v Network or Built-in Postfix Delivery Network or -> -> -> -> local users filter queue agents local mailbox | ^ | v Undeliverable mail Forwarded mail The picture makes clear that the filter works while Postfix is receiving new mail. This means that Postfix can reject mail from the network without having to return undeliverable mail to the originator address (which is often spoofed anyway). However, this ability comes at a price: if mail inspection takes too much time, then the remote client will time out, and the client may send the same message repeatedly. Topics covered by this document: What mail is subjected to header/body checks Limitations of Postfix header/body checks Preventing daily mail status reports from being blocked Configuring header/body checks for mail from outside users only Configuring header/body checks for mail to some domains only

What mail is subjected to header/body checksPostfix header/body checks are implemented by the cleanup(8) server before it injects mail into the incoming queue. The diagram below zooms in on the cleanup(8) server, and shows that this server handles mail from many different sources. In order to keep the diagram readable, the sources of postmaster notifications are not shown, because they can be produced by many Postfix daemon processes. bounce(8) (undeliverable) | v cleanup(8) -> incoming queue

smtpd(8) (network) \ qmqpd(8) -\ (network) -/ pickup(8) / (local)

^ | local(8) (forwarded) For efficiency reasons, only mail that enters from outside of Postfix is inspected with header/body checks. It would be inefficient to filter already filtered mail again, and it would be undesirable to block postmaster notifications. The table below summarizes what mail is and is not subject to header/body checks. Message type Network mail Network mail Local submission Local forwarding Source smtpd(8) Header/body checks? Configurable Undeliverable mail bounce(8) No qmqpd(8) Configurable pickup(8) Configurable local(8) No

Postmaster notice many No How does Postfix decide what mail needs to be filtered? It would be clumsy to make the decision in the cleanup(8) server, as this program receives mail from so many different sources. Instead, header/body checks are requested by the source. Examples of how to