What this tutorial is *NOT* about
If you just need a no-cost mail server quickly and don't care about the technical mumbo-jumbo then this is the wrong place for you. There are ready solutions like
iRedMail if you are in a hurry. Don't expect to learn much though if you chose the dark side. I personally recommend you understand what you are doing - that's what the ISPmail tutorials are for. Experience from giving support in the #postfix channel on IRC shows that most hobby sysadmins fail because some detail in a complex setup goes wrong and they have no idea how to track it down. Actually I have a feeling that other projects use the ISPmail tutorials to get started, too. :)
What this tutorial is about
You are interested in learning all the basics about running your own mail server using Debian Squeeze? Be my guest. All you need is a computer running Debian (Squeeze) and an internet connection. This tutorial explains step-by-step how to set up such a server and give you lots of background information in the process. Depending on the internet connection and server hardware you will be able to run a reliable mail service for thousands of domains and users.
Soon you will be proud operator of a mail server that can:
- receive and store email for your users from other mail servers on the internet
- let your users retrieve the email through IMAP and POP3 - even using SSL-encrypted connections
- receive and forward ("relay") email for your users using SMTP authentication
- offer a webmail interface to read emails in a web browser
- detect most spam emails and filter them out or tag them
License/Copyright
This tutorial is copyrighted 2011 Christoph Haas (email@christoph-haas.de). It can be used freely under the terms of the
GNU General Public License. Don't forget to refer to this URL when using it. Thank you.
Things you will need
The server setup described here is totally standard work for a professional system administrator. Depending on your level of knowledge and experience you may walk through this document easily or curse the author and fail miserably. You will need to know or learn about different topics regarding basic system administration tasks, DNS, SMTP, MySQL and POP3/IMAP. What you will need:
- A computer to run Debian on (e.g. a dedicated server)
- A Debian installation medium (I prefer a Debian netinstall CD)
- An internet connection
- If your internet connection has a dynamic IP address then you will need an SMTP relay (most decent ISPs offer that) because you usually can't send out emails directly to other mail servers.
- An internet domain and control over its MX record
- Control over your firewall (if you have one) to open the needed ports for SMTP, IMAP and POP3.
- 1-8 hours of time depending on your knowledge.
About this tutorial
Many years ago I wanted to turn my Debian server into a mail server with virus scanning, spam detection, email forwarding, POP3 and IMAP access and a webmail service. All the components were available but it took a while until they worked properly together. So I summed up my desk full of scrawly notes into a tutorial that has become pretty famous. According to my web server statistics it's still the most frequently read article at workaround.org.
This document is not a simple copy-and-paste tutorial where you just copy the commands from the web site and run it on your server. Instead it will make you understand the different components that you are setting up. In the end you will be skilled enough to debug problems yourself. If you feel you need help with your setup then try the hints in the Troubleshooting section or ask on the
mailing list. Unlike many other Postfix tutorials on the internet this is already the sixth edition. Writing this tutorial took a lot of work so these are not just quick draft notes thrown together but a consistent document guiding you.
The whole tutorial is split into several chapters. Please use the links on the right side or below to navigate through the tutorial. If you prefer all content on a single page (e.g. for printing the tutorial) then use the "
printer-friendly" link below. You are also invited to comment on the pages - just click on the "
Add new comment" link at the bottom.
If you like the tutorial then a
tiny donation is appreciated to run the servers and pay for the internet connection.
94 Comments
Got Stuck!
Submitted by Anonymous (not verified) on
Thank you for great work!
Starting the application manually that's all right!
But Starting automatically using runit doesn't work. Actually at this stage what I'm doing is just copying an pasting.
The /var/vmail/ispwebadmin/ exists and belongs to the vmail user.
That's what I get when trying:
root@mail:~# sv status /etc/service/ispwebadmin
down: /etc/service/ispwebadmin: 0s, normally up, want up
root@mail:~# sv start /etc/service/ispwebadmin
timeout: down: /etc/service/ispwebadmin: 1s, normally up, want up
When trying to save "/etc/sv/ispwebadmin/log/run" I get:
"/etc/sv/ispwebadmin/log/run" E212: Can't open file for writing
Press ENTER or type command to continue
TIA
To create the
Submitted by Christoph Haas on
To create the /etc/sv/ispwebadmin/log/run file you need root permissions. Do you fail to create that script? Or does it fail to run?
Script created
Submitted by Anonymous (not verified) on
- As for /etc/sv/ispwebadmin/log/run it was about /etc/sv/ispwebadmin/log/ directory that didn't existed yet. }:-[
- Viewing the status the message looks a bit different:
mail:~# sv status /etc/service/ispwebadmin
down: /etc/service/ispwebadmin: 17s, normally upwarning: /etc/service/ispwebadmin: unable to open supervise/ok: file does not exist
; down: log: 17s, normally up
mail:~# sv start /etc/service/ispwebadmin
timeout: down: /etc/service/ispwebadmin: 1s, normally up, want up
Could it be that your
Submitted by Christoph Haas on
Could it be that your /etc/sv/ispwebadmin/supervise directory does not exist? I'm not an expert with supervisord or runit to be honest. This is the directorys and files of /etc/sv/ispmailadmin on my server:
Looks the same
Submitted by Anonymous (not verified) on
mail:~# find /etc/sv/ispwebadmin
/etc/sv/ispwebadmin
/etc/sv/ispwebadmin/supervise
/etc/sv/ispwebadmin/supervise/pid
/etc/sv/ispwebadmin/supervise/stat
/etc/sv/ispwebadmin/supervise/status
/etc/sv/ispwebadmin/supervise/control
/etc/sv/ispwebadmin/supervise/ok
/etc/sv/ispwebadmin/supervise/lock
/etc/sv/ispwebadmin/log
/etc/sv/ispwebadmin/log/run
/etc/sv/ispwebadmin/run
Hmm. Do you have a
Submitted by Christoph Haas on
Hmm. Do you have a symlink /etc/service/ispwebadmin -> /etc/sv/ispwebadmin ?
Think I strictly followed the
Submitted by Anonymous (not verified) on
Think I strictly followed the ispwebadmin-1.0.2 readme text.
mail:~# ls /etc/service -l
total 0
lrwxrwxrwx 1 root root 19 Jan 14 09:44 ispwebadmin -> /etc/sv/ispwebadmin
Bummer. Honestly I'm a bit
Submitted by Anonymous (not verified) on
Bummer. Honestly I'm a bit out of ideas here.
Thank you for great work and
Submitted by Anonymous (not verified) on
Thank you for great work and for your attention, any way! I'll take time to read runit and supervise documentation and come back if succeeded. Mean while I'll start the application manually.
Transport to 2 different IPs?
Submitted by Anonymous (not verified) on
Chris,
I've been using this cookbook for some years for our organisation's email. We recently migrated to MS Exchange and I've kept the Postifix\Mysql\Mailman server for virus and spam scanning as well as easy redirects to generic accounts. e.g sales@xxx.com i.e Postfix shares the Internet domain.
Can you please advise if it's possible to get Postfix to route mail to servers based on cost? We have main and backup MS Exchange servers that synch mail databases. I'm trying to work out how to get Postifx to route email to the backup server in the event that the main one goes down.
Thanks,
Greg.
Any admin utilities you would recommend?
Submitted by Anonymous (not verified) on
Hi,
I am seriously thinking of migrating my old qmail servers to a setup similar to this document.
One thing I don't see, is an easy way to administer day to day stuff like adding alieses, changing quota etc. I have found a project called PostfixAdmin - but that seems like a completely new install.
What is the recommended way to manage the daily stuff? Doing it via sql seems a bit overkill.
Are there any nice utilities you would recommend?
Users reported that the
Submitted by Christoph Haas on
Users reported that the ISPwebAdmin tool I wrote for Lenny works well for Squeeze. Try it.
GRS-Mailmanager
Submitted by Anonymous (not verified) on
The GRS Mailmanager version for Lenny also works for squeeze.
Look at http://www.grs-service.ch/pub/grs_mminstallation.html for the latest Lenny version.
Regards Peter
Excellent guide in setting up a new mailserver
Submitted by Anonymous (not verified) on
Cristoph,
Thank you very much for putting together this guide. I have experience as a sysadmin, but until recently have never needed to set up a mailserver from scratch (only maintaining and updating existing installatios).
I've used this setup successfully on a number of servers and have learned a lot in the process.
The configuration is also general enough to work with distributions other than Debian. It works great with CentOS 5.x (of course substituting yum for apt-get, using the correct CentOS package names and config file locations, etc.).
-Justin Franks
Postfix 2.8
Submitted by Anonymous (not verified) on
Hi,
I really like your tutorial and I use it to configure my mail servers for a while.
I would like to know, do you plan to make an update to it for latest postfix and dovecot versions? I'm especially interessed with postscreen use in postfix 2.8 but I screw postfix config trying to configure it.
Thanks a lot for your work and for your answer.
kalon33.
Postfix in Debian Squeeze
Submitted by Christoph Haas on
Postfix in Debian Squeeze will always stay the same version (with just security patches applied). So unless a new Debian release comes out I won't likely change it. After all it takes immense efforts for me to maintain this tutorial the way it is. And there are virtually dozens of further topics around mail serving that are worth explaining. If you want to use a non-stable version of Postfix or Dovecot then you should understand enough of these pieces of software that you don't need a tutorial. My 2¢.
Do you know if your guide works on Ubuntu?
Submitted by Corry (not verified) on
I have followed a few of the cut-paste guides and came very close to getting a working mail system, but I like the fact that yours seems to actually teach, and not just say "type this..." I got started on ubuntu simply because that's the CD a friend gave me. I have my apache et al configured and working, so I'd hate to start over. Can you tell me if your guide will be close enough to follow, or is there a similar guide you know of specifically for Ubuntu? (I have 10.04 installed)
Debian Squeeze was released
Submitted by Christoph Haas on
Debian Squeeze was released in February 2011 so the versions of Ubuntu 10.04 and Squeeze are probably not too far off. I'd say you should give it a try. After all this guide gives you (as you said) additional knowledge what you are actually doing so I'm confident you will be able to fix minor issues that may come from version differences.
It worked. (Ubuntu 10.04)
Submitted by Corry (not verified) on
I already had Ubuntu / apache / MySQL installed, so I skipped the Debian / apache / mysql setup, but the parts I used were accurate as far as I can tell. (I skipped DKIM, greylisting and AMaVis) I used MTS Mail administration that you recommended. (http://www.motechsystems.com/mail_admin.phps) I had to edit the file to fix some database field names and field order, but I was able to create a user, send and receive email. If you'd like the edited version of his file, let me know and I'll send it to you.
Thank you!
Well, it's been an interesting few days!
Submitted by Peterg22 (not verified) on
Just thought I'd drop by a leave a comment to thank you and your fellow commenters for enabling me to get a mail server up and running! It's something I did quite some time ago on a previous box, but this time I feel as though I actually have a reliable, secure system. I'd definitely emphasise the need to run open-relay tests on completion though - I didn't have a problem, luckily.
What's good about the article is that it gets you up and running, but also helps you're understand why things work as they do: very educational. Of course, there have been countless tweaks to config files as I gain a greater understanding but that's to be expected. I went on to install Squirrelmail and now have a truly usable system that I'm using every day. I'm most surprised that I got TLS/SSL to work! Wow!
So thanks once again and I'll come back regularly, and hopefully post some tips that will be of use to others.
Troubleshooting: dovecot: auth-worker(default): SSHA256 password
Submitted by Peterg22 (not verified) on
This problem had been plaguing me for a while, especially as I wasn't knowingly using SSHA256. It wasn't until I logged in using webmail (Squirrelmail) and mistyped my password while watching a debug log that all became clear. If you're getting the same problem, hopefully this explanation will help!
myserver dovecot: auth-worker(default): ssha256_verify(user@example.com): SSHA256 password too short
myserver dovecot: auth(default): client in: AUTH#0111#011PLAIN#011service=imap#011secured#011lip=127.0.0.1#011rip=127.0.0.1#011lport=143#011rport=50050#011resp=AHBl******==
myserver dovecot: auth-worker(default): sql(user@example.com,127.0.0.1): query: SELECT email as user, password FROM virtual_users WHERE email='user@example.com';
myserver dovecot: auth-worker(default): sql(user@example.com,127.0.0.1): Password mismatch
myserver dovecot: auth-worker(default): ssha256_verify(user@example.com): SSHA256 password too short
myserver dovecot: auth-worker(default): Invalid OTP data in passdb
myserver dovecot: auth-worker(default): sql(user@example.com,127.0.0.1): PLAIN-MD5(wrong password) != 'e1********************'
myserver dovecot: auth(default): client out: FAIL#0111#011user=user@example.com
myserver dovecot: auth(default): new auth connection: pid=25038
myserver dovecot: imap-login: Aborted login (auth failed, 1 attempts): user=<user@example.com>, method=PLAIN, rip=127.0.0.1, lip=127.0.0.1, secured
myserver dovecot: auth-worker(default): ssha256_verify(user@example.com): SSHA256 password too short
myserver dovecot: auth-worker(default): Invalid OTP data in passdb
Thank you
Submitted by Ascendor (not verified) on
I just wanted to say thank you for this really really great tutorial. It helped alot. Great work.
great work
Submitted by Olli (not verified) on
nice tutorial, thank you.
Do you how to configure the server, so new (unknown) users can create their own new account without my interaction? Like it works, if you get yourself an email address at lavabit.com or any other random provider? I tried to find a tutorial but couldn't find one. Cheers, Olli.
Thanks. Yes, you can allow
Submitted by Christoph Haas on
Thanks. Yes, you can allow your users to create new accounts. All it takes is a row in the virtual_users table. You could write a web interface to create new users for example.
Will there be an update for Wheezy?
Submitted by axolotl (not verified) on
THX, it's not just a great tutorial it's the best I've found.
Will there be a Version for wheezy or does anybody know if the squeeze tutorial works with wheezy testing?
Yes, I intend to write a
Submitted by Christoph Haas on
Yes, I intend to write a tutorial for Wheezy. You can probably use the current setup on Wheezy. Just that Dovecot has split their monolithic configuration file into several files. So you would have to find the proper locations and distribute the Dovecot configuration settings properly. I'm running Wheezy on a test server successfully with Roundcube as a web mail interface.
I would recommend to stay on Squeeze for the moment though. Shouldn't be long until Wheezy is released.
Nice
Submitted by d.greeley (not verified) on
I would first like to thank you for you awsome write up. Not only did you help me get my mail server up and running, but tauught me a lot of "why's" not just copy/paste. I am deeply appreciative for all your hard work.
Question on the Wheezy write-up: will you be including postfixadmin? I know it uses a diferent scheme in the db than you do, and thus realize if you do include it, you'll likely use it to set up the database. Thanks again for all your effort.
Very kind feedback - thank
Submitted by Christoph Haas on
Very kind feedback - thank you. :) I like to know that there are more think-alikes who don't just run through copy/paste tutorials and curse the world because at some point stuff breaks.
Regarding PostfixAdmin… I can take a look whether it can be adapted to the database schema. I'm aware that we don't currently have a good management interface. Mine (based on Pylons) doesn't deploy well. And the other PHP-based interfaces aren't that great either. :(
Thanks!
Submitted by Diego Duclos (not verified) on
I've been able to setup my mailserver completely. Complete with ssl, https (for roundcube) and with postgres as backend (I've adapted your examples).
Would like to thank you a lot for this writeup, it spared me a lot of time and frustration.
Vacation messages
Submitted by PhilCo (not verified) on
IS there any way a email user can access the DB to put in a vacation message ? I just need to know if its even possible to code into a manager system. Nothing fancy.
Vacation plugin
Submitted by Arek (not verified) on
I'm also looking for tested vacation plugin for roundcube and Christophs mailserver schema...
Any tips?
There is some plugins there: http://trac.roundcube.net/wiki/Plugin_Repository
but working with postfixadmin mainly.
The simplest way is to use
Submitted by Christoph Haas on
The simplest way is to use Sieve-style filters is to enable an "out-of-office" automatic reply. See here.
I'm already running a Wheezy setup with the newer version of Dovecot. The good news is that Sieve-filter handling is nowadays built into Dovecot. And Roundcube can communicate perfectly well with Dovecot. So expect a user-friendly beautiful solution for Wheezy. :)
Thanks mate!
Submitted by asse (not verified) on
Just wanted to say a big thanks champ!
Many years ago (think it was 2003) when i first started to look at linux, and wanted to setup my (first) own mailserver.
Because my current mail provider had systemcrash and "lost" all my emails twice within 12 months :(
I googled around, and tried alot of different postfix+mysql guides, but never got them to work satisfactory until i found your guide.
Must say that it was the perfect guide, a noob trying out linux, and just wanting to learn how to setup his first mailserver without to much trouble :)
It was just great info about what technicial stuff that was going on, and showed clearly what to write in cli, and the possibility to modify/tweak to your own needs.
Because of you, i learned everything i needed to know, and later, to build more ontop of your setup.
- I added MXbackup, and split it over 3 different hosts (cheap vps) located in germany, UK, and sweden..
I did this because, the 'main' mail host also ran webmail, and websites at the time, and was.. let be honest not that powerful.
So mail scanning part could easily be done by the cheap vps' to increase loadtime on http/https - and if mx10 + mx20 died/crashed the mx30 (main) would still get emails + do scanning.. :)
Also i added
- my own global blacklist of domain senders (alot spam from specifik senders, that don't get added to RBL)
- extended the DB tabes to migrate other web application into your mail setup (same email login/password)
- added vira/spam scanning + mxbackup for other domains/servers that didn't end up on my mail mail host (spam hotel i think it's called?)
- web interface to manage everything through mysql (users,domains,aliases,mxbackup,scanning etc. etc.) divided into seperat groups to be able to configure everything seperatedly.
- automatick update of RBL lists, amavis, spamassassin, mysql sync on all mx-hosts.
I can almost keep on going :)
So to sum up, i just want to let you know that because of you, this was possible.
And ever since i got this setup working, i started to play more and more with linux.
And today (around 10 years later, give or take a couple of years) i'm an linux sysadmin working my 5. year with big ass 10gbit/fiber linux calculation clusters, netapp cluster storage systems (>400TB) and everything that comes with it :)
I believe that, if not for your guide i would had never gotten into linux, and would not be the same place that i am today.
Thanks alot champ, you really changed my life.
Thanks, got it working!
Submitted by xit (not verified) on
Thanks, got it working!
One question though, if I send a mail to a non-existing virtual account (whatever@myurl.com) folders for that account would be created in /var/vmail. Is it possible to dispose messages that are being sent to non-existing addresses?
Debian Wheezy
Submitted by Ryan (not verified) on
Debian 7 Wheezy was just released yesterday, do you plan on publishing another guide for Wheezy? I'm sure a number of people including myself would be interested.
An updated guide would be
Submitted by Felix (not verified) on
An updated guide would be great.
It would be even better to get it as long as squeeze is still supported.
Absolutely. Thanks for your
Submitted by Christoph Haas on
Absolutely. Thanks for your interest. I have already prepared a few notes but I have to QA it and tidy it up. Before you start to cheer… that may well take 2-3 months. :) Not because I'm lazy but mainly because I have to finish two other projects first.
Host Not found try again in mailq
Submitted by Michael Beddall (not verified) on
Hi I have been working from this amazing tutorial and have hit a problem that I can't seem to resolve. I keep getting
(Host or domain name not found. Name service error for name=hotmail.com type=MX: Host not found, try again)
in mailq
Any advice would be greatly recived :) Thank you Mike
That looks like a DNS
Submitted by Christoph Haas on
That looks like a DNS resolution problem on your mail server. Try this command:
If should return a list of responsible mail servers from Micro$oft:
If you get no output you need to check your DNS settings in /etc/resolv.conf or the proper operation of your local DNS server. After fixing the DNS problem you probably need to restart Postfix.
host or domain name not found. Name service error for name=hotma
Submitted by Mike (not verified) on
Hi thank you for your reply i did that and got :
5 mx4.hotmail.com
5 mx2.hotmail.com
5 mx3.hotmail.com
i am still getting (host or domain name not found. Name service error for name=hotmail.co.uk type=mx: host not found, try again)?
This time you seem to have
Submitted by Christoph Haas on
FreeBSD
Submitted by Pannonius (not verified) on
Thanks for this great tutorial. It is in the right place between pure "recipe" tutorials (as they drive me crazy with statement as "now let we start Postfix! It works!" - but mine don't ... so, where to find a solution?) and Wietse's manual, which should be learned finally, but for new users it is too large and too tehnical ... The "big picture" is, for example, something what newbies desperately needs!
I run a FreeBSD on my server, but, thanks to portability of the software, I could use Your tutorial without any problem.
I couldn't wait for the modification for use of Dovecot 2 in cooperation with Postfix 2...
Thanks again!
Upgrading to Wheezy
Submitted by Alex (not verified) on
I have just done it and... I should have not !!!! Dovecot and postfix are messing around. When is this Wheezy tutorial up ????? :)
thanks
Dovecot requires quite a few
Submitted by Christoph Haas on
Dovecot requires quite a few configuration changes. But I won't be able to provide the new tutorial soon. Have to finish another project first.
Pages