Ubuntu 16.04 -- using gmail as a secure smtp postfix relay

[updated June 4, 2018 for Ubuntu 16.04]

I do a lot of Ubuntu installs for work - setting up development platforms - and part of the requirements for this platform is to get email working so that I can send email from the new install.

One problem is that the FQDN (fully-qualified domain name) for whatever machine I may be working on isn't. 

Another issue is that I don't want my "From" email address to go-out as anything other than a legitimate email address so I'd want to mask, say, "mshallop@pamcakes" to my public email: "mshallop@gmail.com".

What I set-up, finally, is the ability to use Google's gmail as an SMTP relay for my work environments, using SASL authentication and my public gmail account.  This blog post is the tutorial for doing so using Ubuntu 13.04 desktop.

There are a lot of blog posts, tutorials, forum messages, etc., on the web explaining how to set-up mail on Ubuntu and, specifically, how to use Google's gmail as a relay.  These sites are usually in response to the error messages you get when trying to send mail from tools like the command-line mail, or PHP mail, etc.:

postfix/smtp[3016]: connect to smtp.gmail.com[2607:f8b0:4002:c01::6c]:587: Network is unreachable

postfix/smtp[31323]: connect to alt3.gmail-smtp-in.l.google.com[]:25: Connection timed out

Specifically, error messages like "connection timed out" or "Network is unreachable" that appear in your mail log when you attempt to send email from your machine.

The problems is that the posts I followed are either for a previous release of Ubuntu, or for another Linux variant.  Through some trial-and-error, I was able to derive a working postfix configuration which is what I'm sharing with you in this post.

First, install the necessary packages if you've not done so already:

sudo apt-get install postfix mailutils libsasl2-2 ca-certificates libsasl2-modules

Next, and for sake of form, let's just assume that you've either su'd over to root, or you're prefacing all the commands with sudo. 

Once the packages are installed, cd into the /etc/postfix directory as we're going to do all of the work from here.

First, edit the main.cf file.

This stub, is part of the default file - I've highlighted some of the changes I made to the default configuration:

myhostname = pamcakes.shallop.com
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
myorigin = /etc/mailname
mydestination = pamcakes.shallop.com, pamcakes, localhost.localdomain, localhost
mailbox_size_limit = 0
recipient_delimiter = +
inet_protocols = all
mynetworks =,
inet_interfaces = loopback-only

shallop.com is a FQDN and I use it on all the machines on my LAN.  Which is also why you see the 192 IP in "mynetworks". 

Next, I am adding the following SASL and TLS configuration directives at the end of the file:

relayhost = [smtp.gmail.com]:587
smtp_tls_loglevel = 1
smtp_tls_security_level = encrypt
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_sasl_mechanism_filter = CRAM-MD5, PLAIN, LOGIN
smtp_generic_maps = hash:/etc/postfix/generic

Save the changes and exit the editor.

Next, we're going to create the sasl_passwd file we referenced in main.cf:

[smtp.gmail.com]:587 YOUR_EMAIL@gmail.com:YOUR_GMAIL_PASSWORD

Save this file and execute these commands:

chmod 400 sasl_passwd
postmap sasl_passwd

If you get an error compiling the sasl_password that looks similar to:

postmap: fatal: bad string length 0 < 1: setgid_group =

Then go back and re-edit your main.cf file and comment-out the line that looks like this:

setgid_group =

The postmap command will create your database file so that you should now have two files in your /etc/postfix directory:

-r-------- 1 root root63 Dec5 10:45 sasl_passwd
-rw------- 1 root root 12288 Dec5 10:45 sasl_passwd.db

In the next step, I want to alias my local user name (mshallop) and my domain names (pamcakes, pamcakes.shallop.com, localhost) to my gmail address.  This is so any mail I send via postfix will rewrite the local names to "proper" internet address. 

Create the file: generic and add content similar to the following:

mshallop@localhost                mshallop@gmail.com
mshallop@pamcakes mshallop@gmail.com
mshallop@pamcakes.shallop.com mshallop@gmail.com
mshallop@shallop.com mshallop@gmail.com

All these entries mean is that when postfix sees something from the column on the left, it will rewrite (map) the address to the value in the column on the right.  You're going to want to change this according to what your local domain and user names are on your system.

Create the generic database using postmap (again):

postmap generic

And you should now have these files in your /etc/postfix directory:

-rw-r--r-- 1 root root 167 Dec5 11:09 generic
-rw-r--r-- 1 root root 12288 Dec5 11:10 generic.db

Finally, restart postfix services:

systemctl restart postfix

If you get more errors when starting postfix, again assuming you used a vanilla (deferred) install, then edit the main.cf file and comment-out the directives responsible for generating the error.

And send a test mail:

mail -s 'Test mail' mshallop@maplehillchaos.com < /etc/motd

You should, after the appropriate delay, see your mail appear in whatever inbox you sent it to... in your log files, you should see something similar to:

Dec5 12:20:16 pamcakes postfix/qmgr[10962]: 421C8241748: from=<mshallop@pamcakes.shallop.com>, size=829, nrcpt=1 (queue active)
Dec5 12:20:16 pamcakes postfix/smtp[10986]: Untrusted TLS connection established to
smtp.gmail.com[]:587: TLSv1.1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)
Dec5 12:20:18 pamcakes postfix/smtp[10986]: 421C8241748: to=<mshallop@targetcw.com>, relay=smtp.gmail.com[]:587, delay=2.6, delays=0.03/0.04/1.2/1.4, dsn=2.0.0, status=sent (250 2.0.0 OK 1386274820 g6sm161512656pat.2 - gsmtp)
Dec5 12:20:18 pamcakes postfix/qmgr[10962]: 421C8241748: removed

The email received, will have your gmail address in the "From" header.  The only indication that the email came from your Ubuntu platform will be located in the "Received" header:

Return-Path: <mshallop@gmail.com>
Received: from pamcakes.shallop.com ( [])
by mx.google.com with ESMTPSA id g6sm161512656pat.2.2013.
for <mshallop@targetcw.com>
(version=TLSv1.1 cipher=ECDHE-RSA-RC4-SHA bits=128/128);
Thu, 05 Dec 2013 12:20:19 -0800 (PST)
Received: by pamcakes.shallop.com (Postfix, from userid 1000)
id 421C8241748; Thu,5 Dec 2013 12:20:16 -0800 (PST)
To: <mshallop@targetcw.com>
X-Mailer: mail (GNU Mailutils 2.99.97)
Message-Id: <20131205202016.421C8241748@pamcakes.shallop.com>
Date: Thu,5 Dec 2013 12:20:16 -0800 (PST)
From: mshallop@gmail.com (Micheal Shallop)

Now all email I send from this new development environment will be sent out, securely (because TLS), via Google's smtp relay.  Mail received will appear to the recipient as originating from my gmail account and any replies will be correctly addressed.

May 21, 2016 Update:

I've tested this on Ubuntu 14.04 and it works.
YSK that if you've secured (properly) your google account, you may see an error similar to the following in your mail.log:

May 21 11:31:04 bluto postfix/smtp[12039]: 545D21C1019: SASL authentication failed; server smtp.gmail.com[] said: 534-5.7.14 Please log in via your web browser and?534-5.7.14 then try again.?534-5.7.14 Learn more at?534 5.7.14 https://support.google.com/mail/answer/78754 u127sm35624047pfb.82 - gsmtp May 21 11:31:04 bluto postfix/smtp[12039]: connect to smtp.gmail.com[2607:f8b0:400e:c03::6d]:587: Network is unreachable

This message is telling you, basically, that Google hasn't seen this machine before, accessing your account, and to login from that machine via a browser to implicitly authorize this box.

For me, my servers are usually headless which poses a bit of a problem - especially if you're running the server version of ubuntu.

The work-around is to use lynx, a test-based browser, to login to your gmail account.  You can install lynx thus:

apt-get install lynx-cur

And then use it to login to your gmail account.  Once you've done so, you should be able to send emails via your new SMTP relay.


Final note, if you're using 2FA (two factor authentication) on your gmail account, this set-up will not work.  I tried logging in using lynx and received a validation request on my phone, but that's apparently session-based (to the pseudo-browser of lynx) and you'll not be able to send email (using postfix) while 2FA is enabled.