diff --git a/src/content/docs/ispmail-trixie/100-start.md b/src/content/docs/ispmail-trixie/100-start.md index 23d4105..3750210 100644 --- a/src/content/docs/ispmail-trixie/100-start.md +++ b/src/content/docs/ispmail-trixie/100-start.md @@ -6,12 +6,13 @@ sidebar: order: 100 --- -This is the 12th edition of the ISPmail guide. A free guide to setting up a mail server for friends and family using -open-source software. Email on the internet nowadays is in the hands of few huge companies. Take back control and host -your own mail server. Get a cheap virtual server and read along. This guide is comprehensive and will walk you through -everything you need to know. I am publishing this guide without any commercial motives. All you need to invest is your -time. And thanks to Debian you will get automatic security updates and do not have to worry about anything until the -next stable release comes out in 2-3 years. +Good to have you here. This is the 12th edition of the ISPmail guide. A free guide to setting up a mail server for +friends and family using open-source software. Email on the internet nowadays is in the hands of few huge companies. +Take back control and host your own mail server. Get a cheap virtual server and read along. This guide is comprehensive +and will walk you through everything you need to know. I am publishing this guide without any commercial motives. All +you need to invest is your time. And thanks to Debian you will get automatic security updates and do not have to worry +about anything until the next stable release comes out in 2-3 years. And perhaps you come back then to upgrade your +server. ## What your mail server will do @@ -20,10 +21,9 @@ next stable release comes out in 2-3 years. - **Send** emails out to the internet. Connections will be encrypted when possible. - **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. -- Provide a **webmail** interface so users can access their emails securely from any location using a web browser. -- Let your users fetch email using **IMAP** or **POP3** and send email through your servers using **SMTP**. -- Add automatic cryptographic signatures (**[DKIM / Domain Keys](https://en.wikipedia.org/wiki/DomainKeys)**) to - outgoing emails to prove that you are the owner of your domain. +- Have a **webmail** interface so users can access their emails securely from any location using a web browser. +- Let your users fetch email using **IMAP** and send email through your servers using **SMTP**. +- Add automatic cryptographic signatures using DKIM to outgoing emails to prove that you are the owner of your domain. - Allow users to manage server-based **filter rules**. Distribute incoming emails to different folders. Forward copies. Or send out-of-office notifications. - Mitigate **brute force** attacks. @@ -33,21 +33,21 @@ next stable release comes out in 2-3 years. - **Linux experience**. Preferably a Debian-derivative. No godlike skills required. But know your basics: navigating the file system, editing files, watching log files. Have some basic understanding of DNS. Bonus points if you have played with an SQL database and know about SELECT, INSERT, rows, columns. -- **Time**. 2 hours to get the basic service running. Maybe a day if you want all the optional bells and whistles. -- A **server** that runs Debian Trixie. 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 distributions than Debian 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. So for the easiest way choose Debian Trixie. +- **Time**. 2 hours to get the basic service running. Maybe a day if you are not an everyday Debian user. +- A **server** that runs [Debian Trixie](https://www.debian.org/releases/trixie/). 1 GB of RAM and a 20 GB disk/SSD is + fine for your friends and family. Just rent a cheap virtual server. Other distributions than Debian 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 and do some research. So for the smoothest ride go with Debian. - The hosting provider you chose to run your server on needs to allow **SMTP send and receive**. These providers are known to be troublesome: - Hetzner (DE, FI, US): Will allow SMTP after a month of paying for their service and per a request issued at https://console.hetzner.cloud/limits - DigitalOcean (US): Blocks SMTP and tells you that running your own mail server is a bad idea. Avoid. - 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](https://multirbl.valli.org/) before you start. - If you rent a virtual server from your favorite hosting company you probably won’t have any problems. But if you want - to run the service from your home, this is something you need to check. + usually can’t operate the mail server from a residential IP address at home because those IP ranges are blacklisted by + most other mail servers. Make sure that your IP address is not [blacklisted](https://multirbl.valli.org/) before you + start. If you rent a virtual server from your favorite hosting company you probably won’t have any problems. But if + you want to run the service from your home, this is something you need to check. - An **internet domain** (or several) to receive emails for. You need to be able to set A, MX and TXT records for that domain. You should also be able to set PTR records for your IP address because some mail servers on the internet require you to have matching forward and reverse DNS records. @@ -65,6 +65,17 @@ some detail in a complex setup goes wrong and they have no idea how to fix it. E 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 supposedly easy route. +## What's new + +The last updates to this guide – up to Debian Bookworm – were mainly minor changes. However this time I have spent many +weeks to improve the guide. Most sections are completely rewritten. Explanations about SMTP versus submission were +added. I dived deep into RFCs and reference documentation. I have used more features of the +[Astro/Starlight](https://starlight.astro.build/) framework (the software that is used to render this guide) to add +visual guides like task lists or image galleries or foldout sections to help you understand what's going on on a mail +server without getting lost. And I have replaced all my configuration examples with blocks that you can copy/paste into +your shell. So this guide is supposed to be shorter and faster to follow while at the same time trying to be more +comprehensive. Please leave your feedback in the comment sections whether this approach appeals to you. + ## Ready? The entire tutorial is split into several pages. You can find the different chapters on the left. The navigation within diff --git a/src/content/docs/ispmail-trixie/110-whats-new.mdx b/src/content/docs/ispmail-trixie/110-whats-new.mdx index b1d3064..ae66c05 100644 --- a/src/content/docs/ispmail-trixie/110-whats-new.mdx +++ b/src/content/docs/ispmail-trixie/110-whats-new.mdx @@ -15,13 +15,14 @@ import { Aside } from "@astrojs/starlight/components"; Did you follow the ISPmail guide for Debian Bookworm to install your mail server? Then let's take it to Debian Trixie. -# Architectural changes +## Architectural changes -In the past I tried to keep things similar to previous versions of this guide. Most of us are happy with their mail -servers and want to change as little as possible when a new Debian release comes along. Just a few improvements: +I always try to keep things similar to previous versions of this guide. Most of us are happy with their mail servers and +want to change as little as possible when a new Debian release comes along. Just a few changes that come with the newer +software versions: - **rsyslogd** was a classic choice to write log files like /var/log/mail.log. As Debian is using _systemd_ we no longer - need rsyslogd and logrotate. The logs can be read using _journalctl_ instead. If you miss it, just + need rsyslogd and logrotate. The logs can be read using _journalctl_ instead. If you miss log files, just `apt install rsyslog`. - **smtpd_tls_security_level** is now only enabled for the `submission` service. That disables authentication for SMTP connections on port 25. This emphasizes the separation of TCP 25 for server-to-server connections (without @@ -29,7 +30,7 @@ servers and want to change as little as possible when a new Debian release comes - **certbot** is now using the `python3-certbot-apache` package. Getting and renewing certificates is now handled magically by Apache without any downtime or additional configuration. -# Version changes +## Version changes A new Debian stable release comes with newer software versions. So I checked the changelogs to determine what we will have to change: @@ -40,10 +41,10 @@ have to change: - rspamd 3.4.1 -> 3.12.1. No breaking changes. - Roundcube 1.6.1 -> 1.6.11. No breaking changes. -# Fresh installation +## Fresh installation -Please do not try to upgrade your previous server using `apt-get dist-upgrade`. It is very hard to do the upgrade -without losing mails. Set up a new server instead. Once you are ready, come back here. +Do not try to upgrade your existing server using `apt-get dist-upgrade`. There are too many changes especially with +Dovecot. Start with a fresh installation on another server and then migrate. ## Preparing the DNS/IP switch @@ -106,8 +107,9 @@ Details are found in the rspamd chapter. ## Migrate the Maildirs hot -Fortunately Dovecot uses the maildir format that stores emails as plain files on disk. Login to the new (Bookworm) -server and use *rsync* to copy over the mails from the old (Bullseye) mail server: +(**Hot** means: copy the files why they are still in use and potentially change while you do that.) Fortunately Dovecot +uses the maildir format that stores emails as plain files on disk. Login to the new (Trixie) server and use *rsync* to +copy over the mails from the old (Bullseye) mail server: ``` rsync -va oldserver:/var/vmail/ /var/vmail/ @@ -119,9 +121,11 @@ There is no need to shut down Dovecot on your production Bullseye server. Copyin will not break anything. This is called a “hot copy". It may not be consistent but it will save time during the final synchronization. -## Copy certificates +Another way to copy over the emails is using Dovecot's +[doveadm-sync](https://doc.dovecot.org/main/core/man/doveadm-sync.1.html) command. It may be especially handy if you +need to copy emails from another server where you only have IMAP access but cannot access the files directly. -(TODO: ignore with Caddy) +## Copy certificates Copy over everything in /etc/letsencrypt and /var/lib/rspamd/dkim from your old to the new server. @@ -136,8 +140,9 @@ You told your users about the downtime, right? The time has come? Okay. Shut dow ## Migrate the emails cold -Let’s synchronize again. *rsync* will only copy those files that have changed which makes it much faster than the first -sync. On your new server run: +(**Cold** means: the processes have stopped or you made sure that there is no user activity so that the files can be +copied consistently.) Let’s synchronize again. *rsync* will only copy those files that have changed which makes it much +faster than the first sync. On your new server run: ``` rsync -va --delete oldserver:/var/vmail/ /var/vmail/ @@ -146,7 +151,7 @@ rsync -va --delete oldserver:/var/vmail/ /var/vmail/ (The “`--delete`" option makes sure that files that have been removed from the old server will also be deleted from the new server. So if a user has deleted an email it will be deleted on the new server as well.) -# Switch the DNS records +## Switch the DNS records For all your domains you will have to change the DNS “MX" or “A" record to point to your new server. diff --git a/src/content/docs/ispmail-trixie/120-installing-debian.mdx b/src/content/docs/ispmail-trixie/120-installing-debian.mdx index 7f742a8..f5e82c1 100644 --- a/src/content/docs/ispmail-trixie/120-installing-debian.mdx +++ b/src/content/docs/ispmail-trixie/120-installing-debian.mdx @@ -14,14 +14,14 @@ import { FileTree } from "@astrojs/starlight/components"; Debian Trixie server, just skip this page. -You have a blank computer or virtual machine? Then simply install Debian Bookworm yourself. Get a boot medium from the +You have a blank computer or virtual machine? Then simply install Debian Trixie yourself. Get a boot medium from the [Debian website](https://www.debian.org/distrib/netinst). The smaller _network installer_ is sufficient – it will download all required packages directly from the internet. Make sure you choose ‘English’ as the installation language even if it is not your native language. If you have trouble with the server you will more likely find help when searching for English error messages on the internet. -Most of the installation is pretty straightforward. You don’t need me holding your hand. I strongly recommend that you -use the _logical volume manager_ (LVM) for your partitions to stay flexible if your server grows. See my +Most of the installation is pretty straightforward. You don’t need me holding your hand. However I strongly recommend +that you use the _logical volume manager_ (LVM) for your partitions to stay flexible if your server grows. See my [article on LVM](https://workaround.org/understanding-lvm/) if you want some help understanding its concept. ## Partitioning diff --git a/src/content/docs/ispmail-trixie/130-install-packages.mdx b/src/content/docs/ispmail-trixie/130-install-packages.mdx index 8ff394e..73eed3c 100644 --- a/src/content/docs/ispmail-trixie/130-install-packages.mdx +++ b/src/content/docs/ispmail-trixie/130-install-packages.mdx @@ -18,7 +18,7 @@ DEBIAN_FRONTEND=noninteractive \ apache2 python3-certbot-apache libapache2-mod-php \ php-intl php-mbstring php-xml unzip certbot \ roundcube-mysql roundcube roundcube-plugins swaks libnet-ssleay-perl \ - ufw mutt unattended-upgrades mariadb-server \ + mutt unattended-upgrades mariadb-server \ rspamd redis-server opendkim-tools bind9-dnsutils pwgen ``` @@ -28,7 +28,7 @@ While the server is downloading and installing the packages, let me give you a q Postfix is the MTA (mail transport agent) that speaks SMTP to send and receive emails. This package installs Postfix with support for MariaDB databases. - **dovecot** \ - Dovecot manages the emsrc/content/docs/ispmail-trixie/140-install-packages.mdx emails using IMAP. + Dovecot manages the emails on disk and lets users access them via IMAP. - **-lmtpd** \ LMTP (Local Mail Transfer Protocol) provides the glue between Postfix and Dovecot. - **-managesieved** \ @@ -50,8 +50,6 @@ While the server is downloading and installing the packages, let me give you a q package is needed to test encrypted connections. - **certbot** \ Gets a free TLS certificate from [_Let's Encrypt_](https://letsencrypt.org/) for encrypting network communication. -- **ufw** \ - Universal FireWall. A simple tool to manage firewall rules to limit access to your server. TODO: omit? - **mutt** \ A console-based program that can speak IMAP and also read Maildirs directly. Very helpful for testing the functionality of your mail server. Think of it as a text-based Thunderbird. diff --git a/src/content/docs/ispmail-trixie/150-virtual-domains.md b/src/content/docs/ispmail-trixie/150-virtual-domains.md index b047171..3f54e62 100644 --- a/src/content/docs/ispmail-trixie/150-virtual-domains.md +++ b/src/content/docs/ispmail-trixie/150-virtual-domains.md @@ -10,7 +10,7 @@ Your mail server will have one fully qualified domain name — for example, `pos domain is `example.com`. If someone visits `https://example.com/`, they might be greeted by the Roundcube webmail login page. -But your server doesn’t have to handle only one domain. You might have mailboxes like: +But your server doesn’t have to handle only one domain. You can have mailboxes on multiple domains like: - `jack@example.com` - `lucy@example.com` diff --git a/src/content/docs/ispmail-trixie/155-database.mdx b/src/content/docs/ispmail-trixie/155-database.mdx index 4c4bd20..0780bae 100644 --- a/src/content/docs/ispmail-trixie/155-database.mdx +++ b/src/content/docs/ispmail-trixie/155-database.mdx @@ -11,9 +11,7 @@ import { Tabs, TabItem } from "@astrojs/starlight/components"; Now it’s time to prepare the MariaDB database that stores the information that controls your mail server. In the process you will have to enter [SQL](http://en.wikipedia.org/wiki/SQL) queries – the language of relational database servers. -You may enter them in a terminal window using the ‘mariadb’ command. But if you are less experienced with SQL you may -prefer using a web interface. That’s what you installed _[Adminer](https://www.adminer.org/)_ for. TODO: link to Adminer -setup in a later section +You may enter them in a terminal window using the ‘mariadb’ command. diff --git a/src/content/docs/ispmail-trixie/158-certbot.mdx b/src/content/docs/ispmail-trixie/158-certbot.mdx index df6d528..924f339 100644 --- a/src/content/docs/ispmail-trixie/158-certbot.mdx +++ b/src/content/docs/ispmail-trixie/158-certbot.mdx @@ -19,7 +19,7 @@ Your mail server can't work properly without a valid TLS certificate. It will be Your mail server will be able to host email addresses for many domains. But a TLS certificate is usually issued for a single [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) like `mail.example.org`. That _common name_ is -an important part of the certificate. It must match the name you use to talk to the server. +an important part of the certificate. It must match the name your users use to talk to the server. **Correct**: Your mail server is addressed as `mail.example.org`. The TLS certificate was also issued to `mail.example.org`. @@ -88,13 +88,15 @@ If you like Certbot, please consider supporting our work by: In /etc/letsencrypt/live/**mail.example.org** you will find a couple of files now: -- cert.pem: the certificate file -- chain.pem: the _chaining_ or _intermediate_ certificate. This certificate provides information how the LetsEncrypt +- **cert.pem**: the certificate file +- **chain.pem**: the _chaining_ or _intermediate_ certificate. This certificate provides information how the LetsEncrypt certificates are linked to other known certificate authorities. It is generally a good idea to always send this certificate along with your own for clients who may not know LetsEncrypt properly yet. -- fullchain.pem: this file contains a concatenation of the _cert.pem_ and the _chain.pem_. This is the preferred file to - use when a piece of software asks where to find the _certificate_. -- privkey.pem: the private key file. Keep it secret. +- **fullchain.pem**: this file contains a concatenation of the _cert.pem_ and the _chain.pem_. This is the preferred + file to use when a piece of software asks where to find the _certificate_. +- **privkey.pem**: the private key file. Keep it secret. + +Well, actually those are not files but _symbolic links_ pointing to the "archive" directory. But don't worry about that. @@ -103,6 +105,15 @@ In /etc/letsencrypt/live/**mail.example.org** you will find a couple of files no Your new certificate is only valid for 3 months. Fortunately the renewal is happening automatically. A _systemd timer_ checks your certificate frequently and triggers a renewal one month before it expires. +It is important that services that use the certificate load the new certificate after an automatic renewal. This shell +command will create a file `/etc/letsencrypt/cli.ini` that handles it: + +```sh title="Run this on your server" +echo > /etc/letsencrypt/cli.ini "post-hook = systemctl reload postfix dovecot apache2" +``` + +Perfect. You won't have to worry about the certificate again. +
Click here to learn how the renewal works… @@ -118,13 +129,4 @@ systemctl cat certbot.service _Systemd timers_ are similar to cron jobs. They require more work to set up but have some nice features and make you look cooler. -It is important that services that use the certificate load the new certificate after an automatic renewal. This shell -command will create a file `/etc/letsencrypt/cli.ini` that handles it: - -```sh title="Run this on your server" -echo > /etc/letsencrypt/cli.ini "post-hook = systemctl reload postfix dovecot apache2" -``` - -Perfect. You won't have to worry about the certificate again. -
diff --git a/src/content/docs/ispmail-trixie/160-postfix.mdx b/src/content/docs/ispmail-trixie/160-postfix.mdx index a8c86db..6d3ef00 100644 --- a/src/content/docs/ispmail-trixie/160-postfix.mdx +++ b/src/content/docs/ispmail-trixie/160-postfix.mdx @@ -42,7 +42,7 @@ If the information is **not** available you just get no answer: In SQL language Postfix has to ask MariaDB the question: ```sql -SELECT "yes" FROM virtual_domains WHERE name='example.net' +SELECT "yes" FROM virtual_domains WHERE name='example.net'; ``` Run the following code in your shell to create a configuration file creating that mapping: @@ -62,8 +62,6 @@ and `dbname` definitions tell Postfix how to connect to the database. And the `q domain is present in the database table `virtual_domains`. Using `SELECT 1` we return just the number 1 if such an entry was found. In fact it does not matter what we return. Any _answer_ is fine. -Don't forget to replace the `MAILSERVER-PASSWORD-HERE` by your own password for the `mailserver` user. - ### Virtual Aliases Now let's deal with aliases. As shown earlier an alias redirects an email to another email address. So the _question_ @@ -112,7 +110,7 @@ specific email address. Actually the _answer_ is usually not `1` but the path to the mailbox on disk. But that applies only if Postfix would be saving the email to disk on its own. In our setup the email will be passed on to Dovecot in a later step. Dovecot will -then handle the files on disk. Postfix just has to know is whether a mailbox exists. And that's why **any** _answer_ is +then handle the files on disk. Postfix just has to know is whether a mailbox exists. And that's why _any_ answer is sufficient here. ### Tell Postfix @@ -152,6 +150,6 @@ john@example.org 1 ``` -If you get anything else, please check those three config files. Perhaps the database password is wrong? +If you get anything else, please check those three config files again. diff --git a/src/content/docs/ispmail-trixie/165-dovecot.mdx b/src/content/docs/ispmail-trixie/165-dovecot.mdx index 5a3b6e4..a6be5da 100644 --- a/src/content/docs/ispmail-trixie/165-dovecot.mdx +++ b/src/content/docs/ispmail-trixie/165-dovecot.mdx @@ -11,7 +11,7 @@ import StepListReceive from "../../../components/StepListReceive.astro"; -In this chapter we will mainly configure Dovecot so that it knows how to deliver incoming emails. +In this chapter we will configure Dovecot so that it knows how to deliver incoming emails. ## Setting up the vmail directory @@ -42,7 +42,7 @@ for our purpose. The `/etc/dovecot/conf.d/10-auth.conf` file is dealing with authentication. At the end of this file you will find a list of authentication backends that Dovecot ships with. By default it will use system users (those from /etc/passwd). But we -want to use the MariaDB database backend so go ahead and change this block to: +want to use the MariaDB database backend so go ahead and **change this block** to: ``` #!include auth-system.conf.ext