Setting Up Postfix
From InstallationWiki
| Official Page |
| Project Documentation |
| Download |
|
Postfix is a modular mail transfer agent developed by IBM researcher and physics Ph.D. Wietse Venema. It is free software and was released publicly for the first time in 1998 under the name VMailer. It is written in C and currently consists of about 70,000 lines of code (comments excluded) and works on most non-historic variants of UNIX and Linux.
As a pure mail transfer agent, Postfix does not provide any service for allowing users to collect their mail via POP, IMAP, and so on. That task must be carried out by some other piece of software, the e-mail client. The software discussed in this tutorial for retrieving the e-mail from the host is Courier.
All current Postfix documentation as well as the source code and links to third-party software and archives of the very active mailing list can be found at the Postfix web site at http://www.postfix.org/.
Contents |
[edit] Installation and Basic Configuration
In this section, we will take a look at how to obtain and install Postfix as well as how to make the first and most basic configuration changes. By the end of this section you will be able to use Postfix to send and receive e-mail messages.
[edit] Choosing the Postfix Version
There are two separate branches of Postfix development; the official release and the experimental release. The official release is sometimes referred to as the stable release, but that is somewhat misleading as it implies that the experimental release is unstable.That is not the case. The experimental release is used to introduce all new Postfix features. When the implementations of the features and their interfaces (for example, their configuration parameters) have stabilized sufficiently, they are brought into the official release. The only changes made to the official release are bugfixes and fixes for portability problems.
The experimental release is fully usable in production environments, but the code is of course less tested and configuration parameters and their semantics may change between releases. If you choose to use the experimental release you should build and install Postfix from source code instead of using some package management system (say RPMs). This will allow you to easily apply any patches for newly discovered problems.
The experimental release has a version number that indicates the number of the upcoming official release together with the release date of the experimental release in question. For example, at the time of writing the current official release was 2.1 and the current experimental release was 2.2-20041215.
[edit] Installing from a Package
Probably all current Linux distributions include Postfix as a package that can easily be installed. You are better off with the distribution's package unless you are comfortable building software from source and, if required, debugging any build problems that might occur. Most packages come pre-built with some extra features that would otherwise require a more complicated build process.
Because there are many different packaging systems, the actual process of installing the Postfix package(s) will not be covered here. Please consult the documentation of your package management system for details.
A word of caution for users of distributions that allow multiple mail transfer agents to be installed at the same time: If you are installing Postfix to replace another mail transfer agent you should make sure the previous software is properly removed from your system. Since probably all mail transfer agents provide a sendmail program, this file is installed with a name such as sendmail.postfix, and a symbolic link points from sendmail to sendmail.postfix or whatever mail transfer agent's sendmail program is chosen to be the main one. If that symbolic link does not point to Postfix's sendmail program, you might get surprised when you attempt to send a message.
[edit] Installing from Source Code
Installing Postfix from the original source code is not very difficult and enables you to run any version you want and not just the version chosen by the package maintainer of your Linux distribution. The Postfix source code can be downloaded from a number of mirrors accessible from the main Postfix web site (http://www.postfix.org/download.html).
Once you have downloaded and unpacked the archive in a suitable directory (/usr/ local/src is typical), you will notice that the Postfix build system does not use GNU autotools and does therefore not have the configure script that one normally finds in the root directory of the unpacked archive. The Postfix build system will automatically take care of this step. Do not worry if you want to install Postfix in some non‑standard location, you will get an opportunity to set various installation directories later.
If you need to enable non-standard features such as support for MySQL or LDAP lookups, you must inform the build system about this and where to find the libraries and include files for the feature. For exact instructions and details about each non-standard feature, please review the README file for each and every one of them. For example, the MySQL instructions found in README_FILES/MYSQL_README tell you to run the following command to enable MySQL support when building Postfix:
$ make -f Makefile.init makefiles \ 'CCARGS=-DHAS_MYSQL -I/usr/local/mysql/include' \ 'AUXLIBS=-L/usr/local/mysql/lib -lmysqlclient -lz -lm'
Adjust the paths to where the MySQL include files and shared libraries are located on your system. You must have the development libraries for MySQL installed. If you need more than one extra feature you will have to combine the commands given in each of the README files.
After this, you are all set to build Postfix:
$ make
When the build is completed (hopefully without errors), it is time to create a user and groups that Postfix uses for many of its daemons. Start by adding two groups, postfix and postdrop. You can for example use the groupadd tool, which probably is available in your Linux distribution:
$ groupadd postfix $ groupadd postdrop
The next step is to create a user named postfix. This user requires no shell access, nor a valid home directory. The primary group of this new user should be the newly created postfix group. Here is how to do it using the useradd tool:
$ useradd c postfix -d /tmp g postfix s /bin/false postfix
Now, you should add something similar to the following to /etc/passwd:
postfix:x:12345:123:postfix:/tmp:/bin/false
And something like the following to /etc/group:
postfix:x:123: postdrop:x:321:
The next and final step is to install your newly built Postfix. If you are installing Postfix for the first time in this particular Linux installation, run the following command:
$ make install
This command will guide you through an interactive installation procedure where you get to choose various installation directories and file locations.
If you are upgrading Postfix from a previous release, run the following command instead:
$ make upgrade
All right! Postfix is now installed on your system, and you will soon be ready to use it.
To make sure that Postfix starts when your system boots, some extra measures are needed. Most Linux systems have a SysV-style init, so you to construct an init script and make proper links in the runlevel directories.
[edit] The Postfix Configuration
Like most UNIX software, Postfix reads its configuration from text files stored under the /etc directory. Postfix configuration files are usually stored in /etc/postfix, but you can configure Postfix to use any other directory. Postfix uses two main configuration files, master.cf and main.cf, and any auxiliary files that you set up yourself.
After a change to any of these files, Postfix must be reloaded. This can be done with the same program that started Postfix, via the init scripts, or via some other service management tool that your distribution provides:
postfix reload /etc/init.d/postfix reload /etc/rc.d/init.d/postfix reload
Postfix restart required after changing inet_interfaces:
If the inet_interfaces parameter is changed, a reload is not enough. Postfix must be stopped and restarted for the changes to take effect. This is also true for the inet_protocols parameter introduced in Postfix 2.2.
[edit] main.cf
The file you will be editing most frequently is main.cf. That file defines the parameters that control the behavior of Postfix's daemon processes. Each line has the following form:
parameter = value
This simply means that the parameter named parameter is given the value value. A parameter may only be specified once in main.cf. If you by mistake give the same parameter different values at different places in main.cf, the last occurrence will be the one used by Postfix. Apart from this, the order in which parameters are listed in main.cf is insignificant. However, within a parameter value the order of the keywords may matter. For example, the following two parameters are not necessarily equivalent:
parameter = A, B parameter = B, A
If the value of a parameter is not specified in main.cf, Postfix will use the default value. The default value for most parameters is hard-wired in the source code, but some default values are determined at build time, and a few of them at run time.
Lines in main.cf can be marked as comments by starting them with #.
# These two lines are comments. They can be used to temporarily # disable parameters, or to explain the configuration. mydomain = example.com mydestination = $mydomain, localhost
This short example also shows how the current value of another parameter can be inserted when setting a parameter value; simply type a dollar sign directly followed by the name of the parameter whose value you wish to obtain. The last line above is equivalent to the following:
mydestination = example.com, localhost
Sometimes it is not convenient to have everything on one line. By starting a line with whitespace, you tell Postfix that the line is a continuation of the previous line. For example, the following two are equivalent (the first example is a single line, and has wrapped here because of page constraints):
smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination
In Postfix 2.1 and later, the format of the main.cf configuration file is documented in the postconf(5) manual page, which also describes all available configuration parameters.
The postconf program is very useful for examining the current and default value of main.cf parameters. Start the program with one or more parameter names as options and it will report the values that Postfix would use. If you use the -d option, postconf will report the default value of the parameter(s) you list.
For example, here is how to compare the current value of mydestination with its default value:
$ postconf mydestination mydestination = $mydomain, localhost.$mydomain $ postconf -d mydestination mydestination = $myhostname, localhost.$mydomain, localhost
Using this method is often quicker than looking in main.cf or wading through a huge manual page to find the default value. It also reveals the actual value Postfix thinks a parameter has, making it easier to spot mistypes.
[edit] master.cf
The master.cf file configures the Postfix master daemon that we discussed earlier. Each line in master.cf defines a service that a certain program carries out. For example, the daemon that receives and processes SMTP connections, smtpd, is one service. The program that delivers messages to the local users, local, is another service. In addition to the 15 20 services that Postfix defines from the start, you can add your own services.
The fifth column in master.cf controls whether each service should be run in a chroot environment. chroot is a UNIX feature that changes the root of the file system, making it impossible to access a file outside the new root directory even if a running process is compromised by an evildoer with root privileges. The source distribution of Postfix disables chroot completely by default, but some Linux distributions have it enabled. Although chroot is a security feature that can be quite useful as an extra safety net, it makes Postfix more difficult to maintain and is more or less useless unless the rest of your system is really tight.
In Postfix 2.2 and later, the format of the master.cf configuration file is documented in the master(5) manual page. In earlier releases, most of that information can be found in comments in the master.cf file itself.
For most simple Postfix setups, master.cf does not need to be touched at all.
[edit] Lookup Tables
Some information cannot be conveniently represented in main.cf or master.cf. Postfix's concept of lookup tables allows information to be stored in external files, relational databases, or LDAP directories.
To Postfix, a lookup table is an abstract entity that maps one string, the lookup key, to another string, the lookup result. Those who are mathematically inclined may look upon it as a function or as a collection of (key, value) tuples and programmers may recognize it as a 'hashtable'. Basically it is like a phonebook; you look up a name and get a phone number back.
In most cases, the simple indexed lookup table types will often be the most convenient ones. An indexed lookup table is nothing more than a text file that you can edit using your favorite text editor. The first part of each line, up to the first whitespace, will be taken as a lookup key and the rest of the line will be taken as the corresponding value.
[edit] key value
The term 'indexed' is used because Postfix does not read these text files directly. That would be too slow. Instead, the text files are built to indexed binary files that simple database libraries can read. In the Linux environment, the lookup table type 'hash' is the most commonly used one. It uses the Berkeley DB library, as does the 'btree' type. To build the indexed file, the postmap program is used. You do not have to reload or restart Postfix after having updated an indexed file with postmap. Postfix will discover the updated file itself and restart its daemon processes as required.
The topic of lookup tables can fill a whole tutorial by itself, so this section will just mention them briefly. We will use lookup tables in a few places later in this tutorial, for example, when we set up policies for spam control.
For a more elaborated discussion of lookup tables and a list of all available lookup table types, see DATABASE_README (http://www.postfix.org/DATABASE_README.html) and the manual pages that document the use of some of the more complex lookup table types.
[edit] Getting Postfix Up and Running
Now that you have installed Postfix, let us make some basic configuration changes, fire it up and take it for a test drive. If you installed Postfix from a package you may already have answered some configuration questions and have had Postfix started for you.
[edit] Domains and Hostnames
Before starting Postfix, let us review some fundamental settings in main.cf. The first ones concern the names of your domain and your mailhost. The mydomain parameter should be set to your main Internet domain. If you run Example, Inc. having the domain http://www.example.com/, the following setting would be reasonable:
mydomain = example.com
The value of mydomain will affect how Postfix transforms hostnames that are not fully qualified. This means that all bare hostnames encountered in places like sender and recipient addresses will be qualified with this domain a hostname such as jeeves will in this case be turned into jeeves.example.com. We will also refer to mydomain in other parameters using the $parameter notation described earlier. Note that the feature of appending mydomain can be disabled by setting the append_dot_mydomain parameter to NO, and some Linux distributions make this modification by default. In general, the value should be left as YES.
A related parameter is myhostname, which incidentally tells Postfix the hostname of the machine. The hostname is among other things used as default when the Postfix SMTP server greets a client and when the SMTP client says HELO to a server. Postfix is normally able to determine this by itself, but sometimes you want to override this. Use the postconf command to see if the current value looks good:
$ postconf myhostname myhostname = jeeves
Yes, this looks fine. Note that this hostname is not fully qualified, so the actual hostname used in various places will include mydomain.
A parameter that is related to mydomain is myorigin. This parameter specifies the domain that should be used to qualify e-mail addresses that have no domain part at all. This may seem highly irregular but it is actually pretty common. Messages submitted with the sendmail program will by default get the current username as the sender address, and because usernames do not have domains the username will be qualified with myorigin before the message is delivered anywhere. By default, myorigin is set to the same value as myhostname:
$ postconf d myorigin myorigin = $myhostname
This should be OK, but you might want to set it to mydomain instead:
myorigin = $mydomain
The next parameter we will give attention is mydestination. That parameter is quite important because it tells Postfix which domains are considered local, that is, which domains should be delivered to UNIX accounts on this machine. Unlike mydomain and myorigin, mydestination may contain multiple domains separated by space or commas. By listing example.com here, Postfix will accept messages addressed to joe@example.com and deliver them to the UNIX user 'joe'.
One important property of local domains is that they are all considered equal. If example.com and example.net are both listed in mydestination, joe@example.com will be equivalent to joe@example.net. If you need additional domains where the users are not equal you need to implement virtual alias domains, described in the Virtual Alias Domains section.
Returning to Example, Inc., you will want to have example.com listed in mydestination since it is your primary domain. The old domain, example.net, should also work for the time being so that one should be included too. Additionally, it is wise to list the value of myhostname in mydestination as well as making sure that mail addressed to localhost gets delivered properly. This yields the following complete list of local domains for Example, Inc.:
mydestination = $mydomain, example.net, $myhostname, localhost.$mydomain
So why localhost.$mydomain instead of just localhost if we want messages to root@localhost to be delivered locally? Remember that mydomain is used to qualify all hostnames that are not already fully qualified (one may argue that localhost in fact already is a fully qualified hostname, but Postfix does not make a special case for that hostname). The address root@localhost will be rewritten to root@localhost.example.com.
Two very important Postfix parameters, mynetworks and mynetworks_style, control which hosts are allowed to use your server as a relay. Setting these incorrectly may allow your server to be abused by spammers and the likes, so it is important that you get them right. By default, all hosts on the subnets that your server is directly connected to will be allowed access. This should be secure in most cases.
[edit] Indirect Mail Delivery through Your ISP
Some Internet service providers do not allow their customers to directly access remote mail servers via the standard SMTP port (25). Instead they provide a relay server that all outbound messages must go through. This policy is common for residential cable or DSL connections, but some providers have the same policy for commercial-grade connections. If such is that case, you need to configure Postfix to deliver all outbound messages indirectly via your ISP's relay server.
This is done with the relayhost parameter, which contains the hostname or IP address of the relay server to use. The following forms are allowed:
relayhost = example.com relayhost = [mail.example.com] relayhost = [1.2.3.4]
The first form will cause Postfix to perform an MX lookup on the hostname, just as it would do for a normal message delivery. Enclosing the hostname in square brackets as in the second example suppresses the MX lookup. The square brackets are also required in the third case when an IP address is specified.
Optionally, the hostname or address can be followed by :port to specify an alternative TCP port. Note that you cannot specify multiple hostnames or addresses to achieve fallback or load balancing behavior. If you need fallback hosts if the normal relay server is unreachable, take a look at the fallback_relay parameter. Refer the Other Useful Configuration Parameters section for additional information on other parameters.
[edit] Choosing Network Interfaces
The inet_interfaces parameter decides the network interfaces that Postfix will use for both listening to new connections and sending out messages. If you have multiple network interfaces and you do not want Postfix to use all of them, you can adjust this parameter to list the addresses or hostnames of the interfaces you do want Postfix to use.
Some Linux distributions set inet_interfaces to localhost by default, which means that Postfix will only listen on the loopback interface. This makes at least some sense for workstations, but it is obviously completely unusable for servers that need to receive messages from foreign hosts. If the Postfix packaging of your Linux distribution has this feature, just delete or comment the inet_interfaces line from main.cf to disable it. Postfix will then use the default value of all, which of course means that all interfaces should be used.
Again, note that changing inet_interfaces requires Postfix to be restarted. A reload is not enough.
[edit] Choosing Mailbox Format for Local Deliveries
By default, Postfix delivers local messages (messages to domains listed in mydestination) into files in mbox format. The mbox format for mailboxes stores all messages of a mailbox in a single text file. These files are named after the user and go into the directory specified by mail_spool_directory (normally /var/mail or /var/spool/mail). If the user desires additional mailboxes to store messages, those files are stored somewhere in the user's home directory (often in $HOME/mail or $HOME/Mail).
The mbox format has a few flaws that make it rather undesirable. The single-file format makes message deletion expensive since the whole file must be rewritten completely unless the message deleted is the last one, in which case the file can just be truncated. Mbox also puts up hurdles when multiple processes need to access the same mailbox concurrently, which for example, happens when a user uses a POP server to retrieve and delete messages while new mail is being delivered. This requires that some method of exclusive locking is used to avoid the concurrent access that might corrupt the files. Such locking is not a big problem if all software run on the same machine, access the same local file system, and agree on which locking method to use, but it is a royal pain if mailboxes need to be accessed over the network via, say, NFS.
To avoid these problems, D. J. Bernstein, the author of software such as qmail and djbdns, designed the maildir format for mailboxes. As the name implies, maildir uses directories and one file per message. Deletion of messages is always very fast, but on the other hand it takes longer to scan a mailbox and produce a list of all messages since all message files have to be opened and read. Maildir is safe to use with NFS. In the maildir delivery format, the inbox of a user is typically found in $HOME/Maildir.
To configure Postfix to deliver new messages to local users to $HOME/Maildir, set the home_mailbox parameter like this:
home_mailbox = Maildir/
Note the slash at the end of the line; it is important! Postfix follows the convention used by many other programs that a mailbox location ending with a slash denotes maildir. If you omit the slash, Postfix will try to deliver messages to the mbox file $HOME/Maildir.
The home_mailbox parameter is only effective for local domains when Postfix performs the delivery itself. If delivery is made by some other delivery agent such as Procmail or Maildrop, you have to configure that software for maildir delivery.
The IMAP/POP server you will be introduced to later, Courier, does not support the mbox format at all. Converting mailboxes between mbox and maildir is not difficult, so if you want to switch format later that is not a problem.
[edit] Error Reporting
The final step is to make sure that Postfix and real people around the world can notify you as a postmaster about error conditions. Internet standards require all domains to have a postmaster address, but you do not need to create an account with that name. Instead you can use the aliasing feature of Postfix to redirect messages addressed to the postmaster address to yourself and any other people that manage the mail system. Also, you should redirect messages to the root account.
Aliases will be discussed in more detail in the Local Aliases section, but this step should be done right now so we will take a quick look anyway. To make Postfix redirect root's messages and accept messages addressed to postmaster even though no such user account exists, the local alias table must be modified. The configuration parameter alias_maps controls the location of the lookup tables that define such mappings:
$ postconf alias_maps alias_maps = hash:/etc/aliases, nis:mail.aliases
Here the local aliases are stored in the file /etc/aliases (additionally, Postfix will look for aliases in the NIS map mail.aliases). Edit that file so that it contains two lines similar to these:
postmaster: root root: jack, jill
This means that messages addressed to the postmaster will be sent to the root user, and messages to the root user will be redirected to the users, 'jack' and 'jill'. Save the file and run the newaliases command so that Postfix will pick up the changes to the file.
The type of problems that Postfix will report to the postmaster is configurable with the notify_classes parameter. By default, only resource problems such as out-of-disk-space problems and software problems will be reported, but you may configure Postfix to report more types of problems. For example, you might also want to know about SMTP protocol violations:
noticy_classes = resource, software, protocol
When Postfix reports a problem, a transcript of the SMTP session is included. This can be a valuable debugging aid.
Opt for more extensive error reporting rather than too terse reporting. If you receive too many error reports, see if you can use the filtering features of your delivery agent or your mail client to remove the error reports that are not interesting reading. Protocol violations by badly written spam software can typically be ignored, but if one of your own computers behaves badly you will want to know about it.
[edit] Other Useful Configuration Parameters
In addition to the configuration parameters covered so far, I will mention a few others that can be useful to know about. You will most likely do fine using their default values. If you want more information about them please consult the documentation that came with your version or Postfix, or read the documentation online from http://www.postfix.org/documentation.html.
| Parameter | Description |
| always_bcc | Sends a copy of each message to a specified recipient. This can be used for e-mail archiving. If you need more fine-grained control over which messages are copied, take a look at sender_bcc_maps and recipient_bcc_maps. The latter two parameters require Postfix 2.1 or later. |
| defer_transports | Contains names of transports (delivery agents, more or less) whose deliveries should be temporarily deferred. This allows you to suspend local message deliveries if the file system for the home directories is broken or unavailable but the rest of the system works fine. |
| delay_warning_time | By default, Postfix does not send a warning if a message cannot be delivered for some time. Setting this parameter to a particular duration, say 5h for five hours, will cause Postfix to send a single warning message when messages have been undeliverable for that period of time.
A word of caution, though: Your users may not be able to interpret this warning message correctly. Even though Postfix clearly states that it is only a warning and that the message does not need to be resent, many users do not understand this and resend their delayed message. |
| mailbox_size_limit | This parameter controls the maximum size of a local mailbox, or maximum size of a message when using maildir mailboxes. The default of 50 MB may be too low especially if you are using the default mbox format for mailboxes. |
| maximal_queue_lifetime | Specifies how long Postfix will retry failed deliveries of messages before they are returned to the sender. The default of five days is reasonable. |
| message_size_limit | This parameter controls the maximum size of a message. The default value of 10 MB is reasonable (mail is not the best transport method for large files), but may need to be adjusted. Remember that messages are only sent using 7 bits, so if you want to allow 20 MB binary files you must add about 35% to compensate for the overhead of the 7-bit encoding of the file. |
| proxy_interfaces | If your server is connected to the Internet via a proxy or NAT device so that Postfix cannot determine all network addresses that can be used to reach the server, add those addresses to this parameter. |
[edit] Starting Postfix and Sending the First Message
With these settings in place, it is time to start Postfix. Use the following Postfix command to do this:
$ postfix start
postfix/postfix-script: starting the Postfix mail system
To verify that Postfix is running, take a look in the log file. Postfix logs via the standard syslog interface, and the exact location of the log files depends on the syslog daemon configuration. The mail logs will typically be named /var/log/maillog, /var/log/mail.info, or something similar.
Jan 3 21:03:28 jeeves postfix/postfix-script: starting the Postfix mail system
Jan 3 21:03:29 jeeves postfix/master[22429]: daemon started -- version 2.1.5
Postfix is now ready to receive and deliver messages. To try it out, use your favorite mail client and send a test mail to yourself. If your mail client uses SMTP, remember to reconfigure it to use your server.
If you get an error message from your mail client when you try to send the test message, read your log again. Does it show any traces of a connection from the host on which you run your mail client? If so, is any error message logged? To get hints on how to debug Postfix problems, see the Troubleshooting Postfix Problems tutorial.
Once you have sent the message successfully you will also want to check that it is delivered properly. Since you have not yet configured a POP or IMAP server that road is not an option, but if you fancy a mail client that reads mail directly from the file system (mail, Pine, Mutt, and many more) things should work fine as long as your mail client is configured to look for new messages in the same place as Postfix delivers them. If you have chosen maildir delivery, the default settings of your mail client probably won't do.
In any case, reading the mailbox directly from the file system is always an option. With normal mbox delivery, the mailbox file has the same name as the user and resides in the directory pointed to by the mail_spool_directory configuration parameter. With maildir delivery, the message will typically be found in a file of its own in the $HOME/Maildir/new directory.
If all has gone well, the message was delivered to the expected place.
[edit] Additional References
For instructions on troubleshooting Postfix, click here.
[edit] Source
The source of this content is Chapter 2: Setting Up Postfix of [1] by Patrick Ben Koetter, Carl Taylor, Magnus Back, Ralf Hildebrandt, David Rusenko, Alistair McDonald (Packt Publishing, 2005).
