Good day!

I recently spent several hours poring over configuration files and telnet sessions, trying to figure out why I couldn't send email from my linux machine any more.

For years I have used the postfix mailer to handle sending email out to the world, and enjoyed using dinosaurish text-based e-mail clients like pine and mutt, or web-based SquirrelMail. Email I write is dropped into the mail queue, and then postfix relays it to my ISP's mailserver and from there, to the world.

Well recently I changed ISPs, and I received errors from my ISP's mailserver: relay not available.
Turns out, my ISP requires authentication in order to relay mail through it - a reasonable yet annoying requirement. This is what I had to do to get it to work. Read on....

Caveat: this tutorial assumes you have a working postfix installation, and just need to add SASL authentication so that you can use your new ISP's mailserver as a relay when you didn't have to auth to a relay before.

Caveat 2: If your ISP does not want you to do this, then don't. I am not liable! I actually contacted my ISP and told them what I was doing, they didn't mind as long as I authed properly.

Step 1: Determine AUTH Method

Before starting, you might as well check what AUTH method your mailserver understands. Luckily, this is very easy to do with telnet (actual hostnames are masked for security).

At your shell prompt, type:

$ telnet mail.yourmailserver.com 25

This will establish a connection to your mailserver. You'll see something like this:
Trying [ip address of mail server]...Connected to mail.yourmailserver.com.Escape character is '^]'.220 YourMailServer SMTP Server Ready

The mailserver is waiting for you to send a command. Type
and hit enter. You should see something like this:


What you're interested in is the AUTH line. My mailserver tells me it does authorization via LOGIN. You may also see PLAIN here, or potentially things like TLS or SSL. If you can use TLS or SSL, you should. The postfix website has good info on using TLS to secure your mail transactions, or google can help you with that as well.

Step 2: Ensure You Have the Libraries

You need to have certain libraries installed to use SASL to authenticate via SMTP, not the least of which is SASL.

I use debian, so for me it was as simple as
apt-get install libsasl2 libsasl2-modules

You need the modules package, or else postfix will error, and your mail log will be filled with errors that say you have no valid transport methods available.

Moving along....

Step 3: Postfix Confguration: SASL Passwords

Before you can continue, you need a valid email account and password with your ISP. Some ISPs don't give you an email account right off, you may need to sign into your account and create one, or call tech support to get one. Please make a special note of what your ISP requires for logging in, for example if you were to use their webmail service or use POP3 to download email to your local client (for example, via fetchmail). You must use the same UserID or you will get an authentication error 500 5.7.9 or something similar back from the mailserver. In many cases, you need to use
not just

You will be creating a file to hold your userID and password so postfix knows what it is when it needs to use them. You should be root to do this, as you want all config files to be owned by root. The prompt here is indicated by $ -- it may be different on your system.
$ echo "mail.yourmailserver.com userid@yourmailserver.com:password" > \ /etc/postfix/sasl_passwd$ chown root:root /etc/postfix/sasl_passwd$ chmod 600 /etc/postfix/sasl_passwd

(In the first command you can omit the backslash and type line 2 on the same line as line 1. I split the row up here to make it more readable.)
The last two commands prevent anyone but root from reading your password, this way nobody can snoop your emails, or do other nefarious things.

Lastly, you need to inform postfix that it is using the file.
$ postmap hash:/etc/postfix/sasl_passwd
This will create a file /etc/postfix/sasl_passwd.db

Next you need to edit the config files.

Step 4: Postfix Configuration: Put It All Together

You should (or must) be root to complete this step. This step assumes you have a working postfix main.cf config file, and are simply adding SASL for SMTP authorization in order to use your new ISP mail server to relay your email.

Using your favorite file editor (I prefer vi) open the file /etc/postfix/main.cf

Add the following lines to the main.cf file:
default_transport = smtpsmtp_sasl_auth_enable = yessmtp_sasl_password_maps = hash:/etc/postfix/sasl_passwdsmtp_sasl_security_options =smtp_sasl_type = cyrussmtp_sasl_mechanism_filter = loginrelayhost = mail.yourmailserver.net
Note, smtp_sasl_security_options is set to nothing. You don't need any options here, but you do need the row, according to the info I found when setting this up.
Also, you will set smtp_sasl_mechanism_filter to the AUTH method your server uses (we got this info in step1). Mine is login, but yours might be plain, tls, or something else.

Save the file, and quit the editor.

Restart postfix (may vary on different distributions):
$ /etc/init.d/postfix restart
And that should be it! Send yourself or your friends some emails, and see what happens.

Read on for some troubleshooting tips.

Step 5: Troubleshooting Tips

Make extensive use of the mailq tool. It is a command you can type at the prompt, and it will tell you if mail is sitting on the postfix queue waiting to be sent, and the status of the mail. Generally, you want the mail queue to be empty. If it's not empty, then usually there are problems. The error messages you see can be useful in troubleshooting your problem. For example, it will tell you if you had authorization failures, or if you're having a relay problem.

Your system logs are your friend. If the mailq shows mail is not getting out, but isn't clear enough why, check /var/log/maillog or /var/log/mail.log either with your favorite text editor, or by
tail -f  /var/log/mail.log
(use ctrl-c to end a tail -f session). Here you will be able to view more detailed error messages, such as this gem:
Aug  7 09:57:27 excelsior postfix/qmgr[639]: warning: connect to transport esmtp: No such file or directory
(This ended up being a typo in my main.cf file, where I had default_transport set to esmtp by accident. changing it to smtp fixed everything.)

Telnet is a handy tool. I've already told you how to telnet to a mail server, here are some other useful commands you can use if things aren't working.

EHLO - as mentioned, will display the capabilities of the mailserver. Also, should always be issued when you first sign on, it's how you say "hello" to the mail server.

HELO subdomain.domain.com - Also says hello to the mail server, but the mail server will not tell you its configuration. You should use your own hostname here, but are not required to.

AUTH - begins the process of authorization, which we are using SMTP/SASL to handle for us. This is a good way to troubleshoot if something went wrong in your config. However AUTH is not intuitive to use. You will get a reply that looks like gibberish, but the server is asking for your username, in base64 encoding. You must reply in like. If you don't know the base64 encoding of your userID or signon info, use a Base64 converter to translate it, copy/paste the string into the telnet session and hit enter. The server will then reply, and will then expect your base-64-encoded password. Send it using the same process.
This is how you can find out if your email isn't getting out because of an authorization failure.

MAIL FROM: email@address.com - starts the process of sending an email. Response should be OK.

RCPT TO: recipient@email.address.com - must follow MAIL FROM: command, and you should get OK as a reply. If not, the error message will likely be something about relay not permitted. Well, we knew that, this is what we're trying to fix.

DATA - starts the process of sending an email, but really if you get this far, this isn't the best way to troubleshoot your problem.

QUIT - obviously, closes the SMTP connection.
Thank you, this is a very useful tutorial. I will use it!

About This Instructable




Bio: I am a graphic art hobbyist, web cartoonist, and wannabe electronics hobbyist. Other hobbies: cooking, baking, exercise, computers, video games, trivia, and some more I ... More »
More by technosapien:3D Clips For Prescription Glasses Home-made Kale Chips Create a PDF (from ANYTHING!) 
Add instructable to: