ISPmail on Debian Buster – your mail server workshop

Old Debian version

This guide is for an older version of Debian. You may want to use the most current guide.

christoph-haas

Would you like to have your own mail server? Are you familiar with Linux? Then this guide will help you set it up. All it takes is a little time and effort, the monthly costs of a cheap virtual server (starting at around 5€) and a domain at your favorite hosting provider. The software being used is completely free and open-source. You can even make money with it. After all it is called “ISPmail” (ISP = internet service provider). Are you a sysadmin and your employer needs a mail server for their 500 employees? Or do you just want to get rid of freemail services for yourself? Then go with this guide. It has been battle-tested by thousands of other readers.

The setup is based on open-source software. There is no catch. I don’t charge for this guide. If you learn something and end up with a working mail server this makes me happy. Yes, I’m a bit weird, I know. If you feel you would like to return the favor you can easily make me happy by clicking on the donation link at the bottom of this page. And please respect the copyright. I have seen literal copies of my work on the internet by people even making money with it. That’s annoying.

This guide is different from most other because you will learn how email transport and delivery works. You will obtain the skills needed to install, reliably run and troubleshoot your mail server. I firmly believe that those skills are necessary because what good is a broken server with a sysadmin who doesn’t even know where to find the log files.

I have maintained this guide since Debian Woody was released in 2002. It has taken me entire holidays to write and maintain it. So thank you all for your kind feedback and support – I would probably have discontinued this guide without you. And this is already the ninth edition. Un… fucking… believable. 🙂

What your mail server will do…

  • Receive emails for your own domain.
  • Filter out most of the spam and malware.
  • Send emails out to any other servers/domains on the internet.
  • Encrypt all connections (if the other mail servers have encryption enabled, too).
  • Add cryptographic DKIM signatures to outgoing emails automatically to help others verify your emails as authentic.
  • Store as many emails for as many email addresses as you have disk space.
  • Optionally encrypt emails on the server.
  • Set quotas (mailbox size limits) per user.
  • Let your users fetch email using IMAP or POP3 and send email through your servers using SMTP.
  • Allow users to manage server-based filter rules. Distribute incoming emails to different folders. Forward copies. Or send out-of-office notifications.
  • Provide a webmail interface so users can access their emails securely from any location using just a web browser.
  • Mitigate brute force attacks.
  • Have firewall rules to protect the server.

What you will need

  • Linux experience. Preferably using a Debian-derivative like Debian, Ubuntu or Mint. No godlike skills required. But know your basics: navigating through the file system, editing files, watching log files and having basic understanding of DNS and SQL (SELECT, INSERT, rows, columns).
  • Time and patience. You will need 2 hours to 2 days depending on your skills. We will proceed slowly and after every step ensure that no mistakes were made. Don’t hurry and skip parts even if they appear confusing or boring at first. If you get lost just submit your question at the bottom of any page throughout this guide and help is on the way.
  • server that runs with Debian Buster. (Support for other Debian-derivatives is considered.) 1 GB of RAM and a 20 GB disk is fine for your friends and family. Rent a cheap virtual server. Or use a decommissioned laptop or old PC. Other Linux distributions likely come with other versions of the software and have different default configuration – so your mileage will vary if you use anything else than Debian.
  • A public IP address that does not belong to a range of typical ISP customers. You usually can’t operate the mail server from a dialup IP address at home because those IP ranges are globally blacklisted as mail servers. Make sure that your IP address is not blacklisted before you start.
  • An internet domain (or more) to receive emails for. You need to be able to set A, MX and TXT records for that domain.

Why this guide may not be for your

You don’t care about learning anything? You just need a working mail server quickly? There are ready solutions like iRedMail that you may want to consider. Preparing and running a mail server requires a certain technical understanding. And that’s what the ISPmail guide is for. Experience from giving support to other sysadmins shows that most problems appear because some detail in a complex setup goes wrong and they have no idea how to track it down. Email has evolved a lot over the past 35 years and has become a complex matter. 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.

Ready?

The whole tutorial is split into several pages. Please use the links on the right side to navigate through the pages. Make sure you have the server, a non-blacklisted IP and a domain ready. Let’s go.

46 thoughts on “ISPmail on Debian Buster – your mail server workshop”

  1. Great! Many thanks for your efforts on maintaining this super useful mail-server tutorial.
    I am going to try it out over the weekend.

    First remark: the next buttons on this and the next page are not working

    1. Christoph Haas

      Please let me know how far you get. 🙂 Thanks for the hint… fixing the ‘next’ buttons right away.

  2. Thank you Christoph. You are a trusted knowledge source. This is a big contribution to the community.

    1. Christoph Haas

      Freut mich, wenn ich helfen kann. Und vor allem freut es mich, dass ich endlich fertig geworden bin. 🙂

  3. Yay! I’ll be working on setting this up over the next couple of weeks and migrating my old setup!

  4. Just arrived here to get the setup working again. Just migrated to buster and the “old” setup does not work anymore. I have a clue of what went wrong, but I want to go along your guide to not miss anything. The old setup was set up with one of your older guides and I went from there, with some additional settings.
    But now to the reason I wanted to leave a comment here:
    You don’t necessarily need a non-blacklisted IP to be able to sent mails from your mailserver. You can also relay your mails using another mailserver that allows it. E.g. Gmail allows you to relay mails through google servers.

    1. Christoph Haas

      Out of curiosity: does gmail not check whether the sender address is a Google address?

      1. You can verify your address with Google. Google will send a mail with a link to verify you have control over that email address and then you can use that address as sender address.

  5. Dear Christoph,

    thank you so much for this guide and update, we’ve been running it for almost a decade now 🙂 i was wondering if you ever looked at the possiblities for an HA version with duplicate of the main services ?

    Thanks again.

    1. Christoph Haas

      A decade is nice. Good to see that someone actually reads the guides. 🙂

      Unfortunately in the last years I didn’t have a larger project (or employer) that required such a setup. Let’s say I have a general idea how that could work. haproxy as a load balancer. Multiple SMTP servers querying the same database – or even multiple database in a master/slave replication fashion. The most interesting challenge is probably disk storage. I probably wouldn’t trust NFS so I think I would give GlusterFS a try. And in any serious environment I would instantly replace MariaDB by PostgreSQL. 🙂

      If running Kubernetes (especially on-premise) weren’t such an evil pain in the donkey that might actually be a nice way to run the components.

      1. Thanks, we’ve been looking in that direction so i guess we’ll keep digging. the email volume isn’t that big, nor the user count but it is an interesting Learning experience 😀

  6. Hi Christoph and Friends!
    You write: “A server that runs with Debian Buster. (Support for other Debian-derivatives is considered.)”

    What do you mean by this? Is it possible to apply this guide also (for example) to Ubuntu 20.04 LTS?
    I’m thinking about Ubuntu LTS for longer support time, albeit ethically…

    Thanks!

    1. Christoph Haas

      Mainly I was thinking about Ubuntu, Mint and similar distributions. The issue is software versions and to describe configurations options properly and get the components to work together and have it tested. Currently I’m still fixing smaller issues that I missed despite my testing even in Debian Buster. And realistically I cannot invest enough time to test it on other distributions thouroughly. So… this might be one feature that I may not be able to provide.

    2. Hi Davide,

      usually it is no problem to apply this tutorial to Debian-like OSes (like Ubuntu – I do that for years now). As far as you have basic knowledge of what happens “under the hood” it should be no problem. I think as soon 20.04.1 is out I will give it a try – I will switch to new server HW in any case and this summer will, be a larger change. In most cases versions of used software or file locations are slightly different.

  7. I will try and let you know!
    I don’t demand any further commitment from you, you are already doing a lot !!!

    Thanks!

    davide

  8. Christoph, your guides are fantastic!! I have been using them since Lenny!!

    Quick question: When it comes to ipv4 and ipv6 can they both be done at the roundcube level “https:// and then leave all mx records in IPV4 and only allow smtp over ipv4. Some server hosting services don’t allow ipv6 smtp. Would roundcube still function properly? I’m new to ipv6.

    1. Christoph Haas

      Paul, thanks for the nice words and glad to have you as a long-term fan. 🙂

      If the sender does not speak IPv6 it will fall back to IPv4. So if your server supports IPv6 I would strongly suggest to use it.

      Or is there an actual ISP that support IPv6 but blocks SMTP over it?

      1. Hey Christoph,

        Thanks for the info. Its not really a ISP issue just the server hosting company DigitalOcean.
        DigitalOcean allows ipv6 public ip but does not allow ipv6 over smtp. I found this posting that explained why.
        “Admin Response
        Hi, We do not allow SMTP over IPv6 because when IPV6 addresses are blacklisted providers will blacklist the entire /64. Due to this it is not very useful to allow DigitalOcean users to run mail servers on IPV6.”

        So if I setup a AAAA record for the public ipv6 and don’t bother with the mx record for ipv6 a Roundcube user would not have any issues sending emails etc..? My thinking is if a user is on the road he or she could connect to email using native ipv6 and at work where ipv4 is used, then they could submit from a email client ie Thunderbird. Would that work?

        Thanks again for all your work,
        Paul

  9. Hi Christoph,

    Your guide is amazing 🙂
    I will set up my mail server in couple of days and say goodbye to Tutanota.

    I will adapt your guide to redirect traffic throw a nginx reverse proxy.
    the certificates and security rules for all my sites are managed by the reverse proxy.

    So, could you put a recap of all port that have to be opened/redirect on the router/reverse proxy please ?

    Thanks in advance

    1. Christoph Haas

      Hi Romain. Thanks you. The ports you will need are 80 (Letsencrypt renew), 443 (Webmail), 25 (SMTP), 110 (POP3), 143 (IMAP), 587 (Submission).

  10. Is there a resume of some sort were we can find the changes from the first release of the tutorial?

    1. Christoph Haas

      Hi Guido. I’m afraid I don’t have such a large changelog, just the diffs between the versions that I put into a “Migrating from …” page.

  11. Andreas Lotz

    @Christop and all other Experts:

    I am trying to educate myself on establishing Full-Text Search/Index to Dovecot/IMAP/Roundcube. I only find “older” references to SOLR, Lucene, etc., but nothing recent.
    I am probably missing something, but is this not a very desirable added benefit?

    I would love to learn more about success stories and add a solid recommendation to this excellent guide.

    1. Trying to wire thousands of individual message files that may be arbitrarily moved to different folders (if you use IMAP) into a search engine is surely not trivial.

      Full-text is generally a tool for gathering all “articles” into one central index. E-mail at the server level doesn’t fit that model very well as you need to keep the articles partitioned by user. It is probably better handled by a competent e-mail client application (i.e. Thunderbird).

      1. Ash Gittins

        It may be non-trivial but this is not new territory, fast full-text search is a well-explored topic and frankly fairly expected feature of a modern mail service.

        An IMAP mail client should hand this off to the server, as it makes no sense for an imap client to have to download all messages from the server to search them – the whole point of having an imap server is to leave all that up at the server, and for the client to only consume as much as the user wants at any one time (be that one email or all of them) – this also applies to stateless web clients like roundcube.

        @Andreas I’m trying to work this out, too. Solr/Lucene seem too heavy-weight for my needs.

        It seems that there are two new(ish?) (since last time I looked) options, being fts-elastic (https://github.com/filiphanes/fts-elastic) which uses a separate elastic search server, and fts-xapian (https://github.com/grosjo/fts-xapian) which I _think_ works standalone so might be a great possibility for small/medium deployments who want a reasonably simple solution. Both appear actively maintained, but I haven’t tried either yet, as I don’t know yet how best to integrate it with the docker deployment I use (https://github.com/jeboehm/docker-mailserver/issues/99).

        Hope that helps, I’ve been low-key frustrated by this for ages! 🙂

  12. Christoph, this looks like an incredibly detailed guide — thank you. I do have one question, though: I would like to set up and configure the e-mail server such that it *could* be accessed over the internet with just the addition of the MX records to the DNS. However, for an extended interim period, I wish to confine its access only to a few people accessing it across a LAN (and bridged VPN in the same subnet, so essentially *still* a LAN). I have admin control over my gateway router and I can add any records needed to dnsmasq for LAN access. The gateway router runs OpenWRT and uses dnsmasq for local DNS and all non-local accesses are handed by dnsmasq to Unbound, which is internet-facing. Are there any special considerations for operating the e-mail server in this “intranet” environment?

    1. Christoph Haas

      That’s not easy… if possible at all. You would have to emulate the systemd process because several processes from Dovecot, Postfix etc. have to get started.

      To try out the whole setup I’m working with a Vagrantfile. However it might be possible to create different containers. One for Postfix. One for Dovecot. One for rspamd. One for mysqld. One for the web server. Then either use docker-compose or go big and ugly and use Kubernetes. In my opinion that’s more of a scientific idea than something I would really spend my time on.

      In the end containers may be a good idea but in reality I find they suck badly. Their images are huge (1 GB is more the norm than the exception from what I found) and usually the Dockerfiles are pretty much a spaghetti mess of shell craziness. 🙂

  13. Paul-Henri

    Hi Christopher,
    Thank you very much for your guide witch helps me a lot in my trip to setup my mail server.
    In your guide, you don’t talk about the need of a PTR record to point to the mail server. As I saw that is needed in several guides and I don’t have one, I’m very curious if it’s mandatory to avoid sent mails being classify as spam by other mailservers ? Do I have to send mails trough relayhost ?
    Thanks by advance for your advise.

  14. Dear Christoph,
    I believe this document is such a big contribution to the world. Thank you a lot for your great effort.
    I need to tell you, I followed your documentation and installed a fully functional mail server on my Ubuntu 20.04. So imho I can tell that ISPMail is compatible with Ubuntu.
    I need your advice on one thing; I am planning to write a python program to automate ISPMail installation and configuration. I came to that thought after deploying 2 times (1 for the test and 1 for the production). Do you think it is a good idea? And would you have any objections for it?

    1. Christoph Haas

      Hi Nuri. Thanks for your comment. Really glad to have yet another free mail server in the world. 🙂
      Regarding the automation I would not re-invent the wheel. Especially Python is very verbose when doing common system administration tasks. Instead use Ansible. If you haven’t worked with it: it’s using Python but you mainly deal with YAML-formatted text files where you describe what you want to happen. Have a look at the Git repository where I store Ansible files for the current guide: https://git.workaround.org/ispmail/ispmail-buster-ansible

      It may have some rough edges but it should give you a head start and save you a lot of work.

  15. Thank you for the information Christoph. I haven’t used Ansible so much, I am kind of new to Linux. I’ll follow your advice and work on it, using your ansible files too.
    I believe it would be a good challenge for me. Appreciated 🙂

  16. The link to the Matrix room currently links directly to the “Riot” web app.

    It should probably instead use the “matrix.to” service.

  17. Hallo Cristoph,

    ich nutze deinen Mailserver seit Jessie.
    Herzlichen Dank für Deinen Einsatz bzgl. Mailserver.
    Bevor ich Dein Tutorial entdeckt habe, habe ich viele andere Tutorials ohne Erfolg ausprobiert.
    Ich habe es nie hinbekommen.
    Bei Dir jede einzelne Stufe Deines Tutorials testen zu können, Fehler lokalisieren zu können, hat mir sehr geholfen.
    Was soll ich sagen, mein Mailserver läuft seit Jessie ohne jegliche Mucken.
    Sorry das ich mich erst jetzt melde.
    Was soll ich sagen, Danke.

    Gruß Torsten

  18. This is great, I spent a good hour or so looking for a decent learning guide for setting up a mailserver, and this is it. Thanks for helping people like me expand their knowledge of FOSS and expand their skillset 🙂

  19. > If you feel you would like to return the favor you can easily make me happy by clicking on the donation link at the bottom of this page.

    Uhm, where exactly is the donation link…?

    1. Christoph Haas

      Oops. Thanks for the hint. I simplified the overall design of this site and apparently broke the footer. Re-added. 🙂

  20. Hello,
    Thanks Christoph for the amazing guides. I used the Squeeze one and the Jessie one on 2 separate servers.
    I just got 2 computers to replace the old ones. I’ll follow the Buster guide. What is the best way to migrate the 2 old databases to Buster?
    Thanks,

    1. You’re looking to have a “noreply@example.com” that shunts mail to dev/null?

  21. Thank you for your guide that enabled me to successfully move/upgrade my mail server from qmail to Postfix.

  22. Gerard-Jos

    Hi Christoph,

    Same story for me, Excellent guides. Well thought out of.
    And Thanks allot for this guide, for i have truly learned from this. And before finding this site, I was lost with all the “just do this, or “iredmail this”.
    So I wish you and perhaps those that helped too, the best of luck. And thanks again. For your outstanding efforts, in providing those willing to learn. A place, to learn.

    1. Christoph Haas

      Thank you very much for the kind words. I’m so glad that many of us haven’t given up to try and understand how everything works. While the cloud providers try to take that knowledge away and leave us dumb and dry.

Leave a Reply to Michael Cancel reply

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

Scroll to Top