ISPmail guide for Debian Jessie

christoph-haasWelcome to the ISPmail tutorial for Debian Jessie. Since Debian Woody I have provided step-by-step-instructions for setting up and operating your own mail server. So this is already the seventh issue. Yay.

A personal note: I have been working on this issue for three weeks in my spare time. And I deliberately removed any advertisements from workaround.org because I’m opposed to that. So if this guide helps you in any way please consider donating. You can find the appropriate links at the very bottom of this page. Thank you. And of course your feedback or questions are welcome – comment on any page of the ISPmail guide that you find appropriate.

What this tutorial is about

This tutorial teaches you all the basics about running a mail server that is completely controlled by you, as secure as you like and fully powered by open-source software. And while you are setting up your mail server you will learn a lot about communication protocols like IMAP or SMTP. You will also learn how emails find their way through the internet using DNS records. You can use it to run a free mail server for your company, your familiy, your friends or just for yourself. You can put any number of accounts and domains on it. So screw “free” mail services and take control of your email communication again. Essentially all you need is a computer hooked to the internet, an installation medium of Debian Jessie and a little time. When you are done your mail server will be able to…

  • receive and store email for your users from other mail servers on the internet
  • let your users retrieve the email through IMAP and POP3 using TLS-encrypted connections
  • let your users define rules what to do with incoming email – e.g. distribute them to their mail folders or reply automatically
  • let your users send (“relay”) email to the internet using SMTP authentication
  • offer a beautiful webmail interface so that your users can manage their email just using a web browser
  • deal with spam effectively without losing emails

What this tutorial is not about

If you are lazy or in a hurry or just don’t want to learn anything about mail servers – then this guide is not for you. There are ready solutions like iRedMail that you may want to consider. But running a mail server requires a certain technical understanding. And that’s what the ISPmail guide is for. Experience from giving support in the #postfix channel on IRC shows that sysadmins fail because some detail in a complex setup goes wrong and they have no idea how to track it down. Go with ready solutions if you like. But I have a feeling that we meet again. And you will probably not save time either taking the easy route.

Why is it called ISPmail?

The software components that are used in this guide are proven and powerful enough so that you could become an ISP (internet service provider) yourself and sell email services. You will need powerful servers, a backup solution, proper monitoring, staff and a bigger internet connection. But essentially the system will work for 10 or 10,000 users.

Does this guide work with other flavors of Linux?

The software components are available on most Linux distributions. However the versions will vary slightly and the installation paths in your filesystem will be different. So feel free to work through this guide to learn the basics. But be prepared if pieces do not work out of the box. I am considering to offer this tutorial for Ubuntu 14.04 LTS because it gets increasingly popular – but currently the priority is upon Debian Jessie.

Things you will need

The server setup described here is standard work for a professional system administrator. Depending on your level of knowledge and experience you may walk through this document easily or need more patience to get to grips with the basics. It works best if are familiar with basic system administration tasks like editing text files or starting/stopping services, DNS and MySQL. Make sure you have:

  • One or more internet domains to receive email at. Either you manage the DNS yourself or you let domain providers do that for you. However you need to be able to change DNS records. If your ISP just offers “web sites” or “web redirects” then transfer your domain to a decent provider.
  • A computer capable of running Debian Jessie. Unless you have special needs I would suggest you get a low-cost virtual server from your favorite hosting company. Those start at $5 for example at Vexxhost. Start with 10 GB of mailbox space per user, 1 GB of RAM and any CPU.
  • A  permanent internet connection and an IP address for your mail server that does not change. The IP address should not be blacklisted on the internet. Check the IP address at web sites like http://www.anti-abuse.org/multi-rbl-check/ or http://rbl-check.org/. If your IP address shows up on black lists then other mail servers on the internet will likely refuse your emails or consider them spam.
  • Experience with operating a Linux system – preferably even a Debian/Ubuntu system.
  • Basic understanding of DNS. You will need to set up DNS records of the domains that you like to receive email for. At least you need someone who can manage “MX” and “A” records for your domain.
  • Enough skills to install and configure a basic MySQL database server. You will not need to tune the server. But you should understand the basics of relational databases (databases, tables, rows, fields/columns) and the meaning of simple SQL queries.
  • Control over the firewall that connects your server to the internet. You will need to allow certain TCP ports through to your mail server. Also make sure that your internet provider does not block any ports. Professional ISPs are usually not a problem. But cheap home ISPs often block ports like TCP/25 which is used for the SMTP protocol.
  • Time. 2 hours of time if you are a seasoned Linux administrator. Or 2 days if running your own Linux server on the internet is a new topic for you.

To do

Although the tutorial is complete as it is I am working on these additional sections:

  • Automatic deployment with Ansible
  • Automatic signing of outgoing email using domain keys (DKIM)
  • A Ruby-on-Rails web application that helps you manage your mail server

Please respect the copyright

Please ask if you would like to use parts on your own web site. Feel free to contact me if you have any questions or leave a donation if you found the tutorial useful. I am maintaining these tutorials in my spare time and am not making any money with it. It annoys me to find copies of this tutorial or parts of it on other web sites. I think you will understand that.

About this tutorial

Over a decade 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 me quite 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 over ten years ago. 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 and hope they will work. 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. Unlike many other Postfix tutorials on the internet this is already the seventh 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 pages. Please use the links on the right side to navigate through the pages. You are also invited to comment on the pages or ask questions. Just use the comment feature at the bottom of each page.

36 thoughts on “ISPmail guide for Debian Jessie”

    1. Christoph Haas

      Thanks for your comment, nbb… Yes port 587 should be open. I will add that.

      I should also elaborate on the use of DKIM as I did in previous issues. The OpenDKIM milter is pretty easy to integrate and just requires a little key and DNS record creation. I wished more people would use DKIM. And as the large freemailer seem to obey the signature it’s worth adding it.

      When it comes to DMARC and SPF though I’m not that convinced. SPF is a pathetic attempt to fight spam in my opinion. It never worked well and broke easily when someone forwarded their email. You just can’t explain your users how SPF is supposed to work and when it breaks. I think that the same is true for DMARC on a more complex level. All these measures help but they are too error-prone for my taste.

  1. Hi Chris,

    Many thanks for the ISPmail guides, I have been running my own mail server, using your Wheezy tutorial , for about 6 months now and I must say, it rocks.

    Now, I am in the planning stages to upgrade to a Jessie based server and I have two questions, one fairly easy and one a bit more complex.

    I want to run Mailman so that I can run a few mailing lists for some people, is it a fairly easy task to get mailman running on the server?

    Now onto the more complex question. I am wanting to split the server into three logical services, filtering, postfix+dovecot, and datastore. Is it fairly easy to split the three functions out like that, and also is it worth the hassle of having the three separate functions on separate servers? I hope that makes sense.

    Keep up the good work!

    1. Christoph Haas

      Hi Paul. Good to hear that your mail server works well.

      Regarding mailman: yes, that should be pretty easy. It’s been a while since I used mailman though. So this is rather memory and guessing. I suggest you create a new subdomain like lists.example.org. Add a transport map (postconf transport_maps=hash:/etc/postfix/transport) and use “lists.example.org mailman:”. The “mailman:” service is already defined in the /etc/postfix/master.cf. Then follow the mailman documentation.

      Regarding splitting the services. Is there a reason you consider it? In a very large mail server installation (tens of thousands of user in a freemail service) that may make sense. But then there are further topics to deal with like high availability, backup MX servers, backup, monitoring, MySQL cluster… I would not suggest doing that unless there is need for it.

      1. Hi Chris,

        The main reason is extensibility, say I want to add a second, or third MX record, all I would need to do is to clone the SPAM filtering server, and I do not have to worry about syncing email between the two servers.

        Paul

        1. Christoph Haas

          Adding more mail exchangers is a very good idea. The important part is making sure that you do not accept emails for invalid users. So you need to have your list of valid users available on all MX servers. You could set up a MySQL master/slave replication for example and connect the server through a VPN (I usually use OpenVPN for that purpose).

          The backup servers need a mapping just like virtual_domains and virtual_users. But in this case you define the relay_domains setting (domains that you are willing to forward to the main mail server) and the relay_recipient_maps (email addresses that you consider valid). So the backup MX can safely reject non-deliverable email right at the doorstep.

          I would suggest placing a second MX server at another place on the internet. Even if your primary mail server is unavailable then the secondary will receive email and try to forward them (by default) for three days. Usually that’s enough time to fix the situation.

  2. Clockmender

    This may be a dumb question, but I will ask anyway:

    Can I follow your tutorial to the letter on a virgin ubuntu server? Most of what I have read so far looks exactly as for ubuntu

    Thanks.

    1. Ubuntu is based on Debian, so most things that work on Debian should work on Ubuntu as well. However, depending on which version of Ubuntu you’re using your packages may be a lot more recent than the ones on Debian. This may not be an issue, but if you take a look at Christoph’s tutorials for Postfix 2.9 and 2.11 you’ll see that quite a bit has changed between those two versions. Configuration options may have moved to different files, config files may have been split up, and so on.

      tl;dr: You should be able to, but some additional research and tinkering may be required.

  3. Hello,
    nice workaround! It’s really the best one for mail server basics.

    Question I have: could you also add user quota? So the space is restricted for each user.

  4. Hi,

    I am following your tutorials since years, atm replacing my squeeze mail server with a jessie one. I never said THANK YOU. So I am doing that now 🙂

    Keep up the good work!

    Robert

  5. Michael Schopferer

    Hi Chris,

    like others I’m using your tutorials for years now to run a small mail server for the family. Thank you very much! It’s so clear and step-by-step.

    Recently I faced some problems from gmail.com due to fragmentary IPv6 configuration. Do you have any experience or guides for settung up the server with IPv6 protocoll?

    Thanks,
    Michael

  6. Hicham LEMGHARI

    Hello Chris,

    A lot of thanks from a moroccan geek who follow your tuts from the lenny version (was it the first one ?)

    Going to migrate from the wheezy tuto to the jessie one next week !

    Thanks again,
    Hicham

  7. Mike Booth

    Howdy Chris,

    Thanks to your guide, I’ve had a stable Wheezy mail server running for several years. It taught me the basics so I could provision a small server and run it on a cheap $5 a month VPS alongside other services like ownCloud.

    I just redid the server from scratch using Jessie and it runs great. LMTP kicks butt! Today I’m installing OpenDKIM so we’ll see how that goes. I should probably read up on DMARC too.

    Thank you for your time & effort,
    Mike

  8. Thank you for this excellent tutorial. I could set up my own mail server alone. Great job.

  9. Hello Chris,

    I’m struggling trying to import my mailboxes from one imap provider to my brand new mailserver on Debian Jessie…

    Perhaps I’m missing something… I’ve tried to use the imapc backend with pop3 uid sync with no luck..

    I’ve configured the imapc and pop3c backends and trying to use doveadm -v -o mail_fsync=never backup -R -u me@mail.it imapc:

    It seems to work , but sometime it fails, so I suppose there is something missing.

    Unfortunately all the dovecot docs I’ve found are outdated (2.1), so no support for incremental sync… And seems to me some backends changed a lot from 2.1 to 2.2

    Do you have any experience with this? Can you suggest which method to migrate a handful of existing mailboxes from an imap server (no ssh access)?

    Hints are really appreciated and more than enough: I don’t want you to write a tutorial just for me… 🙂

    Thanks,
    Raffaele

    1. Just an update…

      The configuration was correct, but I’ve hit some kind of size-related problem…

      I’ve migrated all the mailbox using that config without any issue, but one failed (the first I tried and that always failed). That was the biggest mailbox I have (about 1Gb). For that mailbox only I’ve commented out the pop3c part and it worked many times without issues…

      Thanks for this tutorial… I’ve used the woody one and it worked flawlessly for some years and this seems to work really well too!

      Raffaele

  10. Vinny Pimpinella

    This is a great tutorial. Thank you.. I am shopping around for a vps host that supports Debian 8. Strangely I haven’t had much luck without spending more than I would like. I did find one that supports Debian 7. Can I apply your latest tutorial on Debian 7? I know you had a tutorial for wheezy as well, but I like the new features in the Kate’s tutorial. Otherwise, I guess I’ll keep looking. Thanks

    1. Christoph Haas

      I should probably mention that in the guide. To backup the database all you need is a “mysqldump mailserver” that outputs the database which is usually rather small even for a few thousand mail accounts. Then you can just backup the /var/vmail directory as files. No need to stop the Dovecot service. You should also backup the /etc directory containing your configuration and the list of installed packages (dpkg –get-selections).

      Of course the backup should be stored on another server. I used to run “Bareos” for a while for backups. But recently I have switched back to the simpler “rsnapshot” that allows me to use SSH (using a public key with an empty passphrase for that purpose) to backup all data to another server.

  11. Hi there,
    does the email server need to have a Public IP Adress? can’t i have the email server local on my router an Just forward the Ports?
    this line here confuses me a bit:
    “A permanent internet connection and an IP address for your mail server that does not change. The IP address should not be blacklisted on the internet. Check the IP address at web sites like http://www.anti-abuse.org/multi-rbl-check/ or http://rbl-check.org/. If your IP address shows up on black lists then other mail servers on the internet will likely refuse your emails or consider them spam.”

    1. As long as it is a static IP address, it would be fine. However, if it is a dynamic IP address, you’d need to sign up with DynDNS or something else that automatically detects the changes. Besides, Most RBLs will mark your site as SPAM because they don’t like changing IP addresses.

  12. Lorenzo Salvador Osorio

    Hello, I ask you to give me permission to use your information to make my own howto in spanish in my blog sosoriosv.blogspot.com to the spanish community that use Debian Jessie operating system

    God bless you

    Lorenzo Salvador Osorio

    1. Christoph Haas

      Ola Lorenzo… sure, go ahead. Please just kindly link back to workaround.org.

  13. Hi great tuto
    I am trying to do it but i have set 3 servers.
    1 for postfix and devcot
    1 for mysql
    1 for nginx and roucube.
    I have managed to get and send mail with smtp and imap.
    But it doesnt work with roundcube in the log of dovcot i can see communication with both server dovcot listing maildir but it finish with handshake.
    So i think it’s a matter of certificat does i need to use the same certificat for roundcube nginx and dovcot postfix ?
    Can i symply copy one for postfix for each server ?
    Regards

    1. Hey Tom,

      As far as I can tell, Roundcube only needs access to the filesystem where the mails are stored so I would say you need to make the mail folder accessible to the nginx server via NFS, SMB, or something else. I can’t imagine certificates are involved here.

      Regards,
      Tom

    2. It would be nice if someone could write a follow-up to this tutorial on how to make the setup more resistant to failures, i.e. make the entire setup redundant and separating the functions to different servers. I might spend some time on writing that tutorial should I find the time.

      1. Christoph Haas

        Don’t underestimate the effort it takes to write such a guide. 🙂 In my opinion if you followed this tutorial, understand the details and have a working setup it should be easy for a professional system administrator to create a more resilient configuration. But that’s really beyond what a “copy/paste” tutorial can deliver.

  14. Hello Chris,

    I’m really gratefull for the work that you are doing. I’ve been using your setup for quite a while now and it’s working really well. The only thing that I’m missing is the autoresponse function to use with your tutorial. Have you thought about it ? Mybe there is a ready made solution which we might be able to use ?

    Would be great if you could let us know.

    Thank you once again
    Kind Regards

    1. Christoph Haas

      Nice. Although DKIM signing will be dead simple and will not even require editing the master.cf. Be surprised. 🙂

  15. Diego Quiroga

    Thank you very much! This tutorial was great to me. I have a working server with this instructions, and its doing the job really fine. And the more important: I learned a lot!
    Thanks for share your knowledge. Keep on the way. Great Job!

  16. Marc Becker

    Hi Christoph,

    first of all: thank you for this great tutorial. Im following this tutorial since years and setup multiple servers corresponding to your tutorial.

    Now I think it’s time to do my part and therefore I started the project to deploy a mailserver via ansible. This project is now finished and I can do an automatic deployment of a mailserver. I would like to publish this ansible project on github as open source.

    Before I publish the project, I ask you to read the license terms and the notes on your tutorial and to give me your “ok” for publication.

    Please contact me via mail and I will send you credentials to login to my private repository and will answer further questions.

    Thanks in advance and kind regards,

    Marc

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to Top