Postfix config

Platforms:
any Linux distro

What You'll Need:
Postfix 2.2+
cyrus-sasl 2.1.19+
3rd party email account

A typical email scenario: you're a developer, and you've got a development Linux box at home. You need to be able to send emails from your code or cron jobs, but you're too lazy to set up a full fledged email server on your LAN. Or you just want to use an email account provided by Google Apps, Yahoo, or your ISP.

Enter the Postfix.

Most Linux distros come with Sendmail already installed, and is usually the default mail client used by the running services. However, Postfix beats the crap out of Sendmail and is a complete, seamless replacement. Here's how I got it going on my CentOS box.

Install

Install Postfix and cyrus-sasl with your application manager of choice. If you're compiling from source, be sure to make Postfix with the -DUSE_SASL_AUTH flag for SASL support and -DUSE_TLS for TLS support.

$ yum install postfix cyrus-sasl

Stop the sendmail service

$ /etc/init.d/sendmail stop

Remove sendmail from the startup runlevels

$ chkconfig --del sendmail

Typical Setup

Edit /etc/postfix/main.cf

# Set this to your server's fully qualified domain name.
# If you don't have a internet domain name,
# use the default or your email addy's domain - it'll keep
# postfix from generating warnings all the time in the logs
mydomain = local.domain
myhostname = host.local.domain

# Set this to your email provider's smtp server.
# A lot of ISP's (ie. Cox) block the default port 25
# for home users to prevent spamming.  So we'll use port 80
relayhost = yourisp.smtp.servername:80

smtpd_sasl_auth_enable = yes
smtpd_sasl_path = smtpd
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_type = cyrus
smtp_sasl_auth_enable = yes

# optional: necessary if email provider uses load balancing and
# forwards emails to another smtp server
# for delivery (ie: smtp.yahoo.com --> smtp.phx.1.yahoo.com)
smtp_cname_overrides_servername = no

# optional: necessary if email provider
# requires passwords sent in clear text
smtp_sasl_security_options = noanonymous

There's roughly a 99.9% chance that your email provider's SMTP server requires authentication. We need to set that up with the username and password given by your email provider.

Add the following line to /etc/postfix/sasl_passwd

yourisp.smtp.servername:80 username:password

The above server hostname and port must exactly match the value for "relayhost" in /etc/postfix/main.cf.

Generate a postfix lookup table from the previous file

$ postmap hash:/etc/postfix/sasl_passwd

Test the lookup table, if all is good then the following will return the specified username:password

$ postmap -q yourisp.smtp.servername:80 /etc/postfix/sasl_passwd

Make sure the sasl_passwd and sasl_passwd.db files are readable/writable only by root

$ chmod 600 /etc/postfix/sasl_passwd
$ chmod 600 /etc/postfix/sasl_passwd.db

Add postfix to be started at boot

$ chkconfig --add postfix

Fire up Postfix

$ /etc/init.d/postfix start

Test it out using sendmail alias from the command prompt

$ sendmail email@example.com
Postfix is good to go.
.

Gmail Setup

If you're attempting to relay mail using Gmail, then it will be necessary to use TLS with Postfix. You'll have to point Postfix at your server's trusted CA root certificate bundle, but luckily "...client-side certificates are not required when relaying mail to GMail".

First, double-check that Postfix was configured with SSL support (ie. ldd should return at least one line starting with libssl):

$ whereis -b postfix
postfix: /usr/sbin/postfix /etc/postfix /usr/libexec/postfix
$ ldd /usr/sbin/postfix
...
libssl.so.6 => /lib/libssl.so.6 (0x00111000)
...

Now we need to find your server's CA root certificate bundle, which is typically distributed with openssl. The bundle file is used by Postfix to verify Gmail's SSL certificate (signed by Thawte). On my CentOS server, this file was located at /etc/pki/tls/certs/ca-bundle.crt, but may be in a different location on your box (ie. /etc/ssl/certs).

$ locate ca-bundle.crt
/etc/pki/tls/certs/ca-bundle.crt

Edit /etc/postfix/main.cf with the following values:

relayhost = smtp.gmail.com:587

# your FQDN, or default value below
mydomain = local.domain

# your local machine name, or default value below
myhostname = host.local.domain
myorigin = $myhostname

# SASL
smtpd_sasl_path = smtpd
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_type = cyrus
smtp_sasl_auth_enable = yes
smtp_sasl_security_options = noanonymous

# TLS
smtp_sasl_tls_security_options = noanonymous
smtp_use_tls  = yes
smtp_tls_CAfile = /path/to/your/ca-bundle.crt
smtp_sasl_tls_security_options = noanonymous

If you haven't already, add the following to /etc/postfix/sasl_passwd

smtp.gmail.com:587 username:password

Generate a postfix lookup table from the previous file

$ postmap hash:/etc/postfix/sasl_passwd

Make sure the sasl_passwd and sasl_passwd.db files are readable/writable only by root

$ chmod 600 /etc/postfix/sasl_passwd
$ chmod 600 /etc/postfix/sasl_passwd.db

Restart postfix and send a test email

$ postfix reload
$ sendmail email@example.com
Test relay thru Gmail
.

Troubleshooting

Monitor postfix mail log in a separate session with the following command

$ tail -f /var/log/maillog

If the log is displaying the following error

(Authentication failed: cannot SASL authenticate to server ...: no mechanism available)

then set this variable in /etc/postfix/main.cf

smtp_sasl_security_options = noanonymous

If the log is displaying this error

553 Sorry, that domain isn't in my list of allowed rcpthosts. (in reply to RCPT TO command)

check your username and password in /etc/postfix/sasl_passwd. Your user name is usually your full email address. If you have to fix it, don't forget to use postmap to generate a new lookup table.