ISPmail guide for Debian 11 “Bullseye”

christoph-haas

Stop using public freemail/cloud services like G**gle Mail. This is a complete and free guide that teaches you how to set up and run your own mail server. At the end of the guide you will have your own fully featured mail server based on open-source software using a cheap (virtual) server. And you will have learned all about the various components, protocols and technologies.

This guide is free. There is no catch. I am publishing this guide without any commercial interest. My motivation is to get more people away from centralized email services. The internet wasn’t meant to run on services offered by only few monopolistic companies. People have become lazy and stopped caring. But running your own server must not become a forgotten art. As IT managers blindly follow the hype to put everything into the “cloud” we sysadmins get stupider by the day. If the trend continues only few people will know how to run a mail server while everyone else is degrading into stupid consumers. Don’t let that happen to you.

So what will the mail server cost you? The only recurring costs you may face are for running your mail server and for renting a domain. Cheap virtual servers are usually available at around $5 / 5€ per month and have enough space to run a mail server for your friends and family. The software being used is completely free and open-source. You can even sell your service if you like. After all it is called “ISPmail” (ISP = internet service provider). Are you a sysadmin and your organization needs a mail server for a few hundred users? Go with this guide. It has been battle-tested by thousands of other sysadmins and constantly evolved over the last 20 years.

What your mail server can do

  • Receive emails on your domains.
  • Filter out spam. (We will not deal with detection of Wind*ws malware though.)
  • Send emails out to any other servers/domains on the internet. Connections will be encrypted when possible.
  • Add automatic cryptographic signatures (DKIM / Domain Keys) to outgoing emails to prove that you are the owner of your domain.
  • Store as many emails for as many email addresses as you have disk space. Set limits (“quotas”) per user. The only limit is the size of your disk.
  • 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 a web browser.
  • Mitigate brute force attacks.

What you will need

  • Linux experience. Preferably a Debian-derivative. 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. 2 hours to 2 days.
  • server that runs with Debian Bullseye. 1 GB of RAM and a 20 GB disk/SSD is fine for your friends and family. Rent a cheap virtual server. Or use a decommissioned laptop. Other Linux distributions likely come with other versions of the software and have different configurations and paths on disk. It will work but you will need to deviate from this guide.
  • Your server needs to have 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 blacklisted by most other mail servers. Make sure that your IP address is not blacklisted before you start. If you rent a virtual server from your favorite hosting company you probably won’t have any problems.
  • An internet domain (or several) to receive emails for. You need to be able to set A, MX and TXT records for that domain.
  • Patience. We will proceed slowly and after every step ensure that are still on track. Don’t hurry and skip parts even if they appear confusing 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. Or join the chat channel.

What this is not about

If you just want to have a working mail server and do not care how it works then this guide is not for you. Check out ready solutions like mailinabox or iRedMail. Running a mail server requires 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 fix it. Email has evolved a lot over the past 40 years. 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 entire tutorial is split into several pages. Please use the links on the right side to navigate through the pages. Let’s go.

44 thoughts on “ISPmail guide for Debian 11 “Bullseye””

  1. Nice! Just at the right moment. Few ours earlier it was not there and i thought whether I should try the Debian 10 guide on Debian 11. Reloaded now and it was there 😉 Thanks

  2. Christoph Haas

    @Nomsis. Nice timing. I wasn’t even sure how to announce that the new guide is online. 🙂

  3. Awesome and just in time 🙂 Thanks indeed for your great work. I appreciate that very much.

    1. Christoph Haas

      I find it tricky (beyond acceptable) to run different processes within the same Docker container. For testing I started with a Vagrant box and later deployed on a cheap virtual server. If you are interested in scaling or dockerisation maybe Kubernetes is an option. That however will require that you are willing to jump through piles of burning catfood. 🙂

      1. FYI, I’m pretty sure mailu uses different docker containers. K8s just seems overkill for just setting up a small mailserver. I was interested in docker because of the isolation, but it seems like its not worth it for the humongous headache. Also, what comment system do you use?

        1. Christoph Haas

          Simple VMs seem a good level of abstraction. 🙂 The web site runs on WordPress with a little customisation and plugins. It’s not ideal for writing structured documentation but having a search index, comments and a little automation helps.

  4. From the beta warning- If you get stuck or find something that does not make sense **tough** then please do not hesitate to post a comment on the respective page.

    I think you meant **though**??

    I’ve been following your guides for several years and have been running my own email server. Thank you for such a thorough guide and for the privacy, security, and independence it provides. I do like to think that I learned a few things about postfix and dovecot along the way.

    I’ll test out the guide in a VM and let you know if I spot anything.

  5. Hi Christoph,

    thank you very much for the tutorial! May I ask some advice?
    I don’t want to expose my e-mail server to the outside world because it’s only used for family purpose. So i would need to receive mails from an external POP Mailserver and also for the outbound I would need to use a “smarthost” since I do have changing IP’s. How hard is it to add these functionalities to your proposed setup?

    Regards
    Udo

    1. Christoph Haas

      Moin Udo. Not hard. I suggest you install and configure “fetchmail”. It will frequently (e.g. once a minute) get the emails from the POP3 server and deliver them locally to your ISPmail server. If your server is on a dynamic (and therefore likely blacklisted) IP then you will need an SMTP server where you can send your emails. If your internet provider does not offer anything like that (or restricts it to certain sender email addresses) then something like https://serversmtp.com/ may help you. If it’s just for your family maybe you qualify for their free plan with 6000 mails/month.

      Renting a VM (e.g. Hetzner) may make things a bit easier though.

  6. This looks like just what I need, but I suspect some additional feedback is needed before getting started…

    I have a functional Debian 9 server running postfix which needs to be upgraded to Bullseye. It supports IMAP, POP3 and WebMail, runs DKIM, and uses spamassassin and clam AV. Purchasing new hardware is probably not an option as it isn’t physically necessary – the server has a 6th gen i7 with lots of RAM and lots of free disk space.

    I am trying to determine the cleanest upgrade path on the same hardware, with as little down time as possible, and would appreciate thoughts and recommendations on how best to approach this challenge.

  7. As is made clear in the “Migrating from a…” documentation, a “from scratch” installation is the preferred method. This is especially important since you’re advancing two Debian versions and the underlying tools have changed (ie. MySQL to MariaDB). Spamassassin, last used in the Debian 8 configuration, has been replaced by rspamd. The encryption schemes have changed as well. Making all of these changes to an old installation would be a formidable task.

    An i7 with lots of ram certainly isn’t necessary. Anything that supports AES-NI is probably sufficient. My backup server runs on ten year old i5 machine with 2GB of RAM and a 500GB hard drive. My main server runs on a $7/month VPS.

    The question is whether or not you can afford to have your current server down for the time it takes you to install, configure and test the new setup.

  8. Karl-Peter Baum

    Hi Christoph,
    Thank you for your excellent email server setup guide, and that you keep it up to date.

    I got my email server up and running on Buster about a year ago, based upon your guide. I am now planning to create a new virtual machine to setup based upon your email guide for Bullseye. I had some issue with getting the Buster email server running on my home server, however with perseverance I managed to get it working. The main issue was the nuances associated with my home server setup that required minor deviations from your guide to get working. Also after a few months of operation the Roundcube web mail stopped working and I have never got around to fault finding as I was intending to update to Bullseye anyway.

    It is interesting to see how many old websites and blogs with such instruction setups have not been updated since 2016-2018. It seems like many people have lost interest or perhaps they have moved to another medium.

    On my home server I run my webserver (raw html, that I do not update much anymore), wiki server (based upon Dokuwiki), Cloud server (based upon Nextcloud) . I also use the home server as my NAS. I originally use Ubuntu on my server, but am slowly migrating to Debian, as Debian seems meaner and leaner than Ubuntu :-). The past couple of years I have also been primarily using Manjaro Linux for my home desktop machine. However I still use Windows on my home machine on occasion and solely for work on company laptop.
    I also run my own separate Linux based router using nftables, with Wireguard remote access.
    I have played with IPv6 however as my home ISP only provides a static IPV4 address I am not currently using IPv6.

  9. harshness – thank you for the reply. If doing an in-place upgrade, I may throttle back and stop at Buster for now, saving Bullseye for another time. It looks like that should keep me current for a couple of more years. As you said, the downtime required is a big concern. Ideally I’d be able to do a new build offline, then find a way to port it to the current hardware. While pondering that I’ll be plowing thru the release notes on Buster…

  10. Thank you Christoph. This will be the third edition of this guide that I’ve used to build my mail servers. It’s very much appreciated

  11. Thank you for such great work and understanding. Many companies so desperately use the cloud services and even forgets that one server has more then enough capacity to run 3-5 services for free.

    However the arguments I heard was, that hiring professional dev-ops is expensive and practically they can’t guarantee that internal team will be able to ensure stability compare to clouds.

    Regardless the remarks above I am happy to tell I am using your tutorials since ~2012 and they always worked great for me.

  12. I wonder if it makes sense to setup dovecot as submission server and let postfix just do the mta part.

  13. Thank you very much for this very detailed and up-to-date guide. I really enjoyed reading it and learned a lot.

    Have you ever thought about creating a container based deployment out of this guide? Having this guide’s setup packed in a docker-compose file or Kubernetes Helm chart would be awesome.

  14. Does anyone run ARC (not to be confused with DMARC)?

    http://arc-spec.org/

    I plan to try getting this running on my server; interested if anyone has already done so and could share potential pitfalls to avoid

    1. Debian Bullseye doesn’t include the OpenARC package. It is unclear if dkimpy’s ARC plays well with others. rspamd looks questionable as well.

      Is DKIM not getting it done for you?

      1. >Is DKIM not getting it done for you?

        Now that Google and other big mail providers are implementing/have implemented ARC, I’m interested in following suit because I suspect sooner rather than later those big providers will start using ARC as another data point for reputation scores and I want to maximize deliverability.

        1. Hi Nathan,

          I want to maximize deliverability as well. Can you share us what else I can do?

  15. Hi there,

    This is a create tutorial I am using here an there since many years. Thanks for all the work.
    I am wondering, if somebody has some solution implementing a multi factor authentication in dovecot? Probably specific app passwords are needed to overcome the limits of imap and smtp.
    This would be easy in roundcube, but this would not help with imap

    Best regards
    Matthias

  16. Hey there,

    first of all a big thank you for this amazing guide. Easily one of the very best technical guides I ever had the pleasure to consume and follow.

    Throughout the guide you’re referencing several times, that Postfix is running in a *chroot*ed environment. While following along, I noticed that *bullseye* installed Postfix 3.5.13 (as of yesterday), which by default does not run its services in chrooted mode. But I failed to notice a step that actually modified *master.cf*.

    Is your Postfix setup in fact running in chroot-mode? Is this enabled by the backwards-compatible configuration option in *main.cf*?

    1. Christoph Haas

      Hey, thanks for the comment. Yes, I just checked a Bullseye installation and according to /etc/postfix/master.cf all important processes have “y” in the “chroot” column.

      1. Hey Christoph, thank your for the swift reply. Disregard my comment (or even delete it). My error is kind of embarassing… I keep my terminal windows scaled down, basically to around 80 oder 90 characters width. My VI and all of my other editors are setup to show a guide @80 characters. So, while having “vi /etc/postfix/master.cf“ visible, the columns got messed up… With a full-width terminal they align and – you guess it already? – the services are indeed running chrooted…

        1. Christoph Haas

          Don’t we all screw up once in a while? 🙂 I believe it’s better to question if something works as expected than to just ignore it.

  17. Blat Blatnik

    Thanks for the great guide Christoph!

    I almost followed it to the end, and everything was explained well and working great. And this is coming from a complete networking/linux beginner.

    Towards the end I realized my ISP blocks port 25, to stop spam or something. That’s a complete showstopper, sadly. I guess g**gle and friends will keep owning all of my email data for the time being.

    But I learned a lot from following along. If my situation changes in the future I will definitely be back for the next iteration of this.

  18. Nice Tutorial!
    Thanks a lot for your awesome work. I followed your guide and was able to setup my Mailserver! It worked like a charm 🙂 And I really learnt a lot about the inner workings thanks to your good explanations.

    But I have one question referring to the PHP Version 7.*: ist it a security risk when the Support for this version ends at the upcoming November?

    1. Christoph Haas

      Thanks for the feedback. Good work that you made it through. 🙂 No, PHP security support is not a problem. The Debian developers who create the installation packages work closely with the PHP developers. Every security issue is dealt with. Either the security fix is “backported” (adapted) to the older PHP version. Or a new minor version is provided. So as long as you update your system (I recommend the “unattended-upgrades” package to do that atuomatically) you won’t have any trouble.

      See also: https://security-tracker.debian.org/tracker/source-package/php7.4

  19. I am thinking of installing this email server virtualized as a KVM guest. And use virtiofs to store the emails on the host filesystem by sharing the “vmail” folder.
    The idea is to have a small guest (~5-6GB) and unconstrained email storage.
    Would that work? Or this is a bad idea.

    1. Christoph Haas

      That would totally work. You may get a warning message from rspamd that it cannot use certain CPU features to speed up crypto functions. But that can safely be ignored.

    2. What else are you doing with your mail server that you need to containerize the mail server?

      1. I am planning on having both ISPconfig and the email server on one server (dual Xeon, 96GB RAM, 6x4TB HDDs).
        I prefer to use ISPconfig to manage a few websites. And the workaround email server setup that proved, over the years, to be robust (Thanks Christoph for all your work. I, really learned a lot & enjoyed setting it up and using it).
        This server is too big for either one on its own.
        I’m still struggling with the virtual setup. Can’t get the correct permissions for vmail to read&write to shared folder.
        I’ve been using VirtualBox for years and started to use KVM/Qemu for almost a year now.
        Still no luck

        Sorry for late reply, but I just saw your comment.
        Thanks

        1. If the websites are all administered by you, a simple reverse proxy would likely be a whole lot less fuss.

  20. I have been running an ISPMail server on a Raspberry Pi 2 with the Raspbian version of Debian 11 Bullseye. I succeeded in upgrading the OS from Debian 11 Bullseye to Debian 12 Bookworm using [link]

    Be sure to take a full backup of the microSD card before attempting this upgrade.

  21. Hi,
    has anyone updated from Debian 11 to Debian 12? is there any problem or configuration file to fix after the upgrade ?

    1. I upgraded the OS from Debian 11 to Debian 12 on my Raspberry Pi 2 running ISPMail. It has worked well since the upgrade 5 weeks ago. These are the issues I encountered:

      1. During the OS upgrade roundcube gets uninstalled. To fix this after the upgrade, run “apt install roundcube” and elect to keep your existing configuration files. Reboot.

      2. When running the usual “apt update && apt -y full-upgrade && apt autoremove && apt clean” there is a complaint about a certificate error. To fix this run “cp /etc/apt/trusted.gpg /etc/apt/trusted.gpg.d/”

      3. When you write a new email in roundcube, the file attachment size is limited to 2mb. To fix this edit /etc/php/8.2/apache2/php.ini In this very long configuration file, find the section shown below, edit it and reboot
      ; Maximum allowed size for uploaded files.
      ; https://php.net/upload-max-filesize
      upload_max_filesize = 2M

      4. There is a configuration error mentioned repetitively in /var/log/roundcube/error.log To fix this go to /usr/share/roundcube/bin/ then run the update script “./update.sh”. When asked for the old Roundcube version say 1.4.13 Do not change the SMTP, etc. names, select the default N. Reboot.

      5. To fix “audit” errors constantly appearing in /var/log/kern.log and /var/log/syslog, Install auditd with the command “apt install auditd” Reboot. Consider whether you wish to edit /etc/audit/auditd.conf and change the 2nd line to “write_logs = no” to reduce the logging in /var/log/audit/audit.log

      6. In /etc/php there are two configuration directories 7.4/ and 8.2/ As Debian 12 is running on PHP 8.2.7 so you can recursively delete the old 7.4 directory with the command “rm -r /etc/php/7.4”.

  22. Christoph Haas

    I am about to prepare a draft in the next weeks. Debian 11 will have support for a year so you won’t need to hurry. But if you want to try on your own let us know your experience.

  23. hi,
    Based on your guide, i had successfully installed in Debian 12. It is based on postfix 3.7.4 dovecot 2.3.19.1 roundcube 1.16.1 – once again thanks for your wonderful mailserver installation guide.

  24. Hello Christoph,

    Your guide is awesome. Thanks a lot for your work
    I create my own ansible playbook for a full mail server installation on debian bookworm. It works as a charm
    https://github.com/Machtorn/isp-mail-bookworm

    I encountered just some issue with rspamd seems due to ipv4 issue with the three workers. And have to install rsylog because bookworm come with journald as default.

Leave a Reply

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

Scroll to Top