More pages added
This commit is contained in:
parent
2fdf2840cb
commit
f2df688c33
8 changed files with 496 additions and 22 deletions
|
|
@ -13,21 +13,38 @@ export default defineConfig({
|
||||||
components: {
|
components: {
|
||||||
Footer: "./src/components/Footer.astro",
|
Footer: "./src/components/Footer.astro",
|
||||||
},
|
},
|
||||||
customCss: [
|
customCss: ["./src/styles/custom.css"],
|
||||||
"./src/styles/custom.css",
|
|
||||||
],
|
|
||||||
sidebar: [
|
sidebar: [
|
||||||
{
|
{
|
||||||
label: "Guides",
|
label: "ISPmail for Debian 12",
|
||||||
items: [
|
items: [
|
||||||
// Each item here is one entry in the navigation menu.
|
// Each item here is one entry in the navigation menu.
|
||||||
{ label: "Start Here", slug: "ispmail-bookworm" },
|
{
|
||||||
],
|
label: "Start Here",
|
||||||
|
slug: "ispmail-bookworm",
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
label: "Reference",
|
label: "Whats' new",
|
||||||
autogenerate: { directory: "reference" },
|
slug: "ispmail-bookworm/whats-new",
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
label: "Migrating your old server",
|
||||||
|
slug: "ispmail-bookworm/migrating-from-a-bullseye-to-a-bookworm-server",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "The big picture",
|
||||||
|
slug: "ispmail-bookworm/big-picture",
|
||||||
|
},
|
||||||
|
{
|
||||||
|
label: "Types of email domains",
|
||||||
|
slug: "ispmail-bookworm/types-of-email-domains",
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
// {
|
||||||
|
// label: "Reference",
|
||||||
|
// autogenerate: { directory: "reference" },
|
||||||
|
// },
|
||||||
],
|
],
|
||||||
logo: {
|
logo: {
|
||||||
light: "./src/assets/logo.svg",
|
light: "./src/assets/logo.svg",
|
||||||
|
|
|
||||||
|
|
@ -6,7 +6,7 @@ import Default from "@astrojs/starlight/components/Footer.astro";
|
||||||
<footer>
|
<footer>
|
||||||
<Default {...Astro.props}><slot /></Default>
|
<Default {...Astro.props}><slot /></Default>
|
||||||
<div class="myfooter">
|
<div class="myfooter">
|
||||||
Copyright © 2024 Christoph Haas. All content on workaround.org can be used under the terms of the
|
Copyright © 2003-2024 Christoph Haas. All content on workaround.org can be used under the terms of the
|
||||||
<a href="https://creativecommons.org/licenses/by-nc-sa/4.0/" target="_blank">Creative Commons BY-NC-SA license</a>. Penguin images
|
<a href="https://creativecommons.org/licenses/by-nc-sa/4.0/" target="_blank">Creative Commons BY-NC-SA license</a>. Penguin images
|
||||||
based on AI art because I suck at drawing.
|
based on AI art because I suck at drawing.
|
||||||
</div>
|
</div>
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,7 @@ hero:
|
||||||
|
|
||||||
import { Card, CardGrid } from '@astrojs/starlight/components';
|
import { Card, CardGrid } from '@astrojs/starlight/components';
|
||||||
|
|
||||||
## Next steps
|
## Features
|
||||||
|
|
||||||
<CardGrid stagger>
|
<CardGrid stagger>
|
||||||
<Card title="Educational" icon="open-book">
|
<Card title="Educational" icon="open-book">
|
||||||
|
|
@ -23,10 +23,95 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
|
||||||
<Card title="Free" icon="heart">
|
<Card title="Free" icon="heart">
|
||||||
This guide is a not-for-profit fun project. You only need to get an internet domain and a cheap virtual server (~5€/$ per month). Powered by the desire to make the internet a bit more decentralized.
|
This guide is a not-for-profit fun project. You only need to get an internet domain and a cheap virtual server (~5€/$ per month). Powered by the desire to make the internet a bit more decentralized.
|
||||||
</Card>
|
</Card>
|
||||||
<Card title="Configure your site" icon="setting">
|
<Card title="Since 2003" icon="seti:clock">
|
||||||
Edit your `sidebar` and other config in `astro.config.mjs`.
|
This guide has been maintained for over 20 years. Made for nerds who want a boring stable mail server that just works with little maintenance. But with all the features that make it fun.
|
||||||
</Card>
|
</Card>
|
||||||
<Card title="Read the docs" icon="open-book">
|
<Card title="You’re not alone" icon="comment">
|
||||||
Learn more in [the Starlight Docs](https://starlight.astro.build/).
|
You won’t get stuck. Every page of this guide has a comment section to ask questions and discuss the topic. For real-time help you can join our [support chat on Matrix](https://riot.im/app/#/room/#ispmail:matrix.org).
|
||||||
|
</Card>
|
||||||
|
<Card title="Open source" icon="linux">
|
||||||
|
All software that is used is completely open-source. No costs. Your new friends are Debian, Postfix, Dovecot, Roundcube, MariaDB, Apache and rspamd.
|
||||||
|
</Card>
|
||||||
|
<Card title="Standards" icon="star">
|
||||||
|
Only standard protocols are used. IMAP, POP3, SMTP and HTTPS. No proprietary protocols. No vendor lock-in. No public cloud.
|
||||||
</Card>
|
</Card>
|
||||||
</CardGrid>
|
</CardGrid>
|
||||||
|
|
||||||
|
## What readers say
|
||||||
|
|
||||||
|
- Kostja:
|
||||||
|
|
||||||
|
I have been using the workaround.org ISPMAIL tutorials for many years and still do it every time I upgrade my mailserver. It is a neat and straightforward approach and saves me a lot of time I otherwise would have to spend reading manuals, finding new packages and trying things out. Everything is on the point and I get the information I need, that’s perfect. Thank you very much for you great work.
|
||||||
|
|
||||||
|
- David:
|
||||||
|
|
||||||
|
I just finished setting up my ~fifth ispmail server (squeeze, 2x stretch, now bullseye) and this time I didn’t even bother to do the recommended checks after each step because I knew that after following (and unterstanding) your tutorial, the server would go like a Swiss watch. I wasn’t disappointed. Everything works and again I learned a lot. Thank you for putting that much effort into the tutorials!
|
||||||
|
|
||||||
|
- Yannis:
|
||||||
|
|
||||||
|
Just wanted to say thanks for your amazing work. Not only proved up to date and accurate technically, but it is also presented in a very educational way. It really is high-quality learning material.
|
||||||
|
|
||||||
|
- Ezerotszaz:
|
||||||
|
|
||||||
|
I’m finally done setting up two of these mail servers – for myself and also for a friend.
|
||||||
|
I struggled a lot when I was doing it for the first time, but after days of work it is done, it is working properly, I can send(and receive..) from four different addresses and I could not be happier!
|
||||||
|
Thank you so much for the insane amount of work that you put into this awesome guide.
|
||||||
|
|
||||||
|
- Impli:
|
||||||
|
|
||||||
|
It had been a long time since I had installed a mail server and the few tutorials I could find were not explicit.
|
||||||
|
But your guide is very well done. Complete and very detailed. With even some technical information as a bonus for the curious.
|
||||||
|
|
||||||
|
- Niko:
|
||||||
|
|
||||||
|
I really like this guide. I was able to learn some new stuff and setup a nice configured server. I now have a server running 2 domains and several user accounts. It took me a few evenings of my spare time and i think it was worth it. Thank you very much for your guidance!
|
||||||
|
|
||||||
|
- Michael:
|
||||||
|
|
||||||
|
Great guide! Thanks! Very structured and clear! It took me about 2 hours to have a fully funktional email server including ISPmail on a Raspberry Pi 3 Model B Rev 1.2 with Raspbian GNU/Linux 11.
|
||||||
|
|
||||||
|
- David:
|
||||||
|
|
||||||
|
Thank you so very much Christoph. I now have a successful mail server running on Linode, and it has all the pieces you have detailed here. It works very well. Best of all, I understand how the pieces hang together.
|
||||||
|
|
||||||
|
- Shukuru:
|
||||||
|
|
||||||
|
This guide is pure gold. As a professional developer with some sysadmin skills I was able to set up my first email server in a week.
|
||||||
|
I learn a lot about how emails works and I can now take control on my privacy. Thanks.
|
||||||
|
|
||||||
|
- Panos:
|
||||||
|
|
||||||
|
I am proud to be able to thank the author of this series of Guides publicly, for all the unbelievable work he has done, all these years. To anyone wishing to truly understand what running a mail server is about, this is the proper place to be.
|
||||||
|
|
||||||
|
- Cody:
|
||||||
|
|
||||||
|
Seen this guide a few times before and found it to be the most comprehensive one available.
|
||||||
|
|
||||||
|
- Anthony:
|
||||||
|
|
||||||
|
Thanks again for such a comprehensive guide. I’ve been using it for several years and I appreciate the updates for the new versions.
|
||||||
|
I just did a “speed run” on a test mail server/domain and it took about 2 hours. TLS/DKIM/SPF are all passing too! I’ve gotten a lot of practice with your guide over the last few versions, so I would hope that I can complete it quickly.
|
||||||
|
|
||||||
|
- James:
|
||||||
|
|
||||||
|
Thanks Christoph, For your work running this site and the ISPmail guides. I’ve been following them for each Debian release since Wheezy.
|
||||||
|
I use my mail server primarily for my personal email address and also have a handful of friends using it. Works great.
|
||||||
|
|
||||||
|
- Robbert:
|
||||||
|
|
||||||
|
I have been using this guide for 10 years now with great success. I truly appreciate how you explain each step you do. This makes it very easy to follow, and also easy to deviate from the guide if desired. Thanks a lot.
|
||||||
|
|
||||||
|
- Nicole:
|
||||||
|
|
||||||
|
I used this guide already with my first mail servers I set up 15 years ago (round about, I’m not quite sure).
|
||||||
|
It always worked fine and is a very big help!
|
||||||
|
I have Debian servers with 5 – 30 users only, including one community project where also newsletters (i.e. many mails) are sent.
|
||||||
|
Today I set up my newest mail server and all works fine.
|
||||||
|
I want to thank Christoph for his great work and support and hope the guide will never end 🙂
|
||||||
|
|
||||||
|
- Francisco:
|
||||||
|
|
||||||
|
Thank you Christoph.
|
||||||
|
I’ve just setup my mail server and i’m very happy with it. I’ve learned a lot.
|
||||||
|
|
||||||
|
|
||||||
100
src/content/docs/ispmail-bookworm/big-picture.md
Normal file
100
src/content/docs/ispmail-bookworm/big-picture.md
Normal file
|
|
@ -0,0 +1,100 @@
|
||||||
|
---
|
||||||
|
title: The big picture
|
||||||
|
---
|
||||||
|
|
||||||
|
The mail server that you are about to set up uses several software components. Let me first explain briefly what the purpose of each software is:
|
||||||
|
|
||||||
|
- **[Debian](https://www.debian.org/)** “Bookworm” – the operating system
|
||||||
|
- **[Postfix](http://www.postfix.org/)** receives incoming emails from the internet and sends out outgoing emails to other mail servers. It is the software that speaks SMTP.
|
||||||
|
- **[rspamd](https://rspamd.com/)** runs sanity checks on an incoming email to determine whether it is spam.
|
||||||
|
- **[Dovecot](https://www.dovecot.org/)** stores emails on your hard disk, applies filters and lets your users fetch their emails using the POP3 and IMAP protocols
|
||||||
|
- **[Roundcube](https://roundcube.net/)** is a webmail interface so users can read their emails using a web browser, manage their email rules and change their password
|
||||||
|
- **[MariaDB](https://mariadb.org/)** (formerly known as _MySQL_) is a database that stores information about your domains, email aliases and email accounts
|
||||||
|
|
||||||
|
## What happens when someone sends you an email?
|
||||||
|
|
||||||
|
Let us assume that you are responsible for the email domain _example.org_ and someone on the internet sends an email to `john@example.org`. This is what happens step by step:
|
||||||
|
|
||||||
|
1. **REMOTE:** Hey, DNS server. I have an email for someone in the _example.org_ domain. Can you tell me the name of the responsible mail server?
|
||||||
|
**DNS:** According to the DNS zone of _example.org_ it is _mx.example.org_.
|
||||||
|
2. **REMOTE**: Nice. Do you have an an IP address for _mx.example.org_?
|
||||||
|
**DNS:** I have an IPv4 address here. It is _85.25.72.76_.
|
||||||
|
3. _REMOTE connects to that IP address on TCP port 25 which is by definition used for SMTP – the [simple mail transport protocol](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)._
|
||||||
|
**POSTFIX:** Welcome. I am Postfix. Who is there? (“220 mx.example.org ESMTP Postfix”)
|
||||||
|
**REMOTE:** Hi, I am remote server. (“EHLO remoteserver”)
|
||||||
|
**POSTFIX:** Nice to meet you. I can offer a few features like pipelining and encryption by the way. (“STARTTLS, PIPELINING, SIZE 4000000, …”)
|
||||||
|
**REMOTE:** Let’s switch to an encrypted connection. (“STARTTLS”)
|
||||||
|
_(The connection is now using TLS encryption.)_
|
||||||
|
**REMOTE:** I have an email from `donald@duck.com` here. (“MAIL FROM:<`donald@duck.com`>”)
|
||||||
|
**POSTFIX:** I see. (“Ok”)
|
||||||
|
**REMOTE:** The email is meant for `john@example.org`. (“RCPT TO:<`john@example.org`>”)
|
||||||
|
4. **POSTFIX:** Hey database. _(Connects to TCP port 3306 on the local host to talk to MariaDB.)_ Could you check if _example.org_ is one of our mail domains? (“SELECT … from virtual_domains …”)
|
||||||
|
**MariaDB:** Yes, I have a domain like that.
|
||||||
|
**POSTFIX:** Oh, good. And do you have a mailbox or forwarding for someone called `john@example.org`? (“SELECT … from virtual\_aliases/virtual\_users …”)
|
||||||
|
**MariaDB:** Yes, there is a mailbox for that address.
|
||||||
|
**POSTIFX:** Hey, remote server. The recipient looks good. (“Ok”)
|
||||||
|
**REMOTE:** Roger. Then here’s the actual email. (“DATA”)
|
||||||
|
_(The remote server sends the email header and body.)_
|
||||||
|
5. _(POSTFIX connects to port 11332 on the local host to reach the rspamd.)_
|
||||||
|
**POSTFIX**: Hey, rspamd. I have a new email here. Could you give it a look for, you know, spam and stuff?
|
||||||
|
**RSPAMD:** Sure. Well, there are a few minor issues. But generally the mail looks good. I suggest you accept it.
|
||||||
|
**POSTFIX:** Hey, remote server. Your email is fine.
|
||||||
|
6. _(Postfix uses a socket file at /var/spool/postfix/private/dovecot-lmtp to talk to Dovecot.)_
|
||||||
|
**POSTFIX:** Hey, Dovecot. Here is a new email for `john@example.org`.
|
||||||
|
**DOVECOT:** Got it.
|
||||||
|
7. _(Dovecot checks for additional Sieve rules and then stores the email on disk at /var/vmail/example.org/john/Maildir/INBOX)_
|
||||||
|
|
||||||
|
Phew, that was a lot. I hope it helps to understand though how the different components are involved until an email gets delivered.
|
||||||
|
|
||||||
|
The next situation I would like to explain is…
|
||||||
|
|
||||||
|
## What happens if a user fetches their email using IMAP/POP3?
|
||||||
|
|
||||||
|
This process is way simpler. It looks like this:
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
User connects through IMAP
|
||||||
|
|
||||||
|
1. The user usually has a mail client (also called a _[mail user agent](https://en.wikipedia.org/wiki/Email_client)_) that can use the POP3 or IMAP protocol to fetch emails from the mail server. I prefer Thunderbird for example. That mail client connects to the POP3 (TCP 110) or IMAP (TCP 143) port, sends the STARTTLS command that initiates an encrypted connection and sends the user’s username (which equals the email address in our case) and their password. The client may as well use the secure TLS-encrypted ports directly – 995 for POPs and 993 for IMAPs. If possible users should use IMAP. POP3 is pretty much deprecated nowadays and lacks support for multiple folders on the server.
|
||||||
|
2. Dovecot sends a query to the MySQL database and verifies that the username and password belong to a known user. The password is not stored in plain text in the database. Instead it computes the password [hash](https://en.wikipedia.org/wiki/Hash_function) and compares it to the hash in the database. If the password is wrong then Dovecot will refuse the login.
|
||||||
|
3. We have a fixed scheme how emails are stored on disk. So if the user is called `jane@example.org` then Dovecot will look for email files in _/var/vmail/example.org/jane/Maildir/…_ and send the user the requested emails.
|
||||||
|
|
||||||
|
Nowadays many users seem to prefer webmail to a mail client installed on their computers. As an email power user I honestly do not understand that trend. But who am I to judge. So let’s take a look how webmail works technically:
|
||||||
|
|
||||||
|
## What happens if a user reads their email using web mail?
|
||||||
|
|
||||||
|
The Roundcube software that provides the web mail interface is basically a PHP software that is a gateway between HTML pages and a built-in IMAP client. So when a user uses their browser to connect to the web mail interface…
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
User connects through webmail
|
||||||
|
|
||||||
|
1. The user points the browser to the HTTPS URL of the webmail interface. Apache web server receives the connection and runs the PHP scripts of Roundcube. Roundcube shows a login form for the username and password. The user enters the username (that equals the email address) and the password and submits the login form.
|
||||||
|
2. Roundcube connects to Dovecot using IMAP and forwards the username and password to check if they are valid.
|
||||||
|
3. Dovecot treats this connection similar to a mail client connection. It queries the MariaDB database to verify the username (=email address) and password.
|
||||||
|
4. If the authentication was successful Dovecot fetches the mail files from disk and sends them through IMAP to Roundcube. Roundcube then renders the emails as HTML and the user can read it.
|
||||||
|
|
||||||
|
So you see that the web mail access also works through IMAP. The user does not realize that though.
|
||||||
|
|
||||||
|
Okay, the final scenario I would like to explain is…
|
||||||
|
|
||||||
|
## What happens if the user wants to send an email to the internet?
|
||||||
|
|
||||||
|
Of course your users also want to send emails to other internet users. But they cannot send the email directly to the destination mail server. First their mail client does not know which destination server is responsible for the recipient (hint: DNS) – that functionality just is not built in. And second the user is likely assigned a _dynamic IP address_ which is blocked by most mail servers because they tend to get abused by infected Windows PCs that send out spam. So the correct way to send an email to the internet is through your mail server. This is called _relaying_ because your mail server acts as a relay. In this example your user wants to send an email to `fred@example.net`.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
Relaying/sending email via the mail server
|
||||||
|
|
||||||
|
1. The user writes the email in their mail client and clicks on “Send”. The mail client establishes an SMTP connection to Postfix. To make sure that the user is allowed to send email through your system it requires a username and password along with the email. This information is sent in an encrypted way.
|
||||||
|
2. Postfix could now check the password in the database directly. But as Dovecot already knows how to handle authentication it is easier to ask Dovecot to verify the username and password. (SMTP authentication in Postfix is surprisingly ugly.)
|
||||||
|
3. Dovecot now sends a query to the MariaDB database to check if the username and password (hash) are correct and tells Postfix the result.
|
||||||
|
4. Postftix knows now that it is authorized to send the email on behalf of the user. It tells the user that it successfully accepted the email. The email is put into Postfix’s mail queue for further processing. Postfix will now query a DNS (name server) to determine the responsible destination mail server. As the recipient has an “…@example.net” address it checks the MX record of the “example.net” domain and then gets the respective IP address.
|
||||||
|
5. Postfix now knows which mail server to send the email to. It opens an SMTP connection and delivers the email.
|
||||||
|
|
@ -1,11 +1,42 @@
|
||||||
---
|
---
|
||||||
title: Example Guide
|
title: ISPmail guide for Debian 12 “Bookworm”
|
||||||
description: A guide in my new Starlight docs site.
|
lastUpdated: 2023-09-24
|
||||||
---
|
---
|
||||||
|
|
||||||
Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
|
Once upon a time there were many mail servers on the internet. If your organisation wanted to receive and send emails then you would have your system administrator set up a mail server. He would add a DNS record and create a cryptic Sendmail configuration file. Fast forward a few decades and suddenly we have arrived in the cloud ages. The world of internet services is dominated by a few monopolistic companies. Having worked in IT for 25 years I feel frustrated about the ignorance and laziness of decision makers. Cloud providers rip obscene profits while IT staff is evolving into dumb customers instead of doing their actual job.
|
||||||
Writing a good guide requires thinking about what your users are trying to do.
|
|
||||||
|
|
||||||
## Further reading
|
If you are like me then you want to stay as independent as possible. And that includes being in charge of your own email service. Maybe not for your employer but at least for yourself, your friends and family. Become your own internet service provider (ISP) for email. Hence the name: ISPmail.
|
||||||
|
|
||||||
- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework
|
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 5€ server. And you will have learned all about the various components, protocols and technologies. This guide has been battle-tested by thousands of other sysadmins and constantly evolved over the last 20 years. I am publishing this guide without any commercial motives, so all you would have to invest is your time.
|
||||||
|
|
||||||
|
## 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](https://en.wikipedia.org/wiki/DomainKeys)**) 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. 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 2 days.
|
||||||
|
- A **server** that runs Debian Bookworm. 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.
|
||||||
|
- The provider providing you with the server 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.
|
||||||
|
- 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.
|
||||||
|
- **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](https://riot.im/app/#/room/#ispmail:matrix.org).
|
||||||
|
|
||||||
|
## 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](https://mailinabox.email/) or [iRedMail](http://www.iredmail.org/). 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 supposedly easy route.
|
||||||
|
|
||||||
|
## Ready?
|
||||||
|
|
||||||
|
The entire tutorial is split into several pages. You can find the different chapters on the left. The navigation within a chapter can be found on the right. Let’s go.
|
||||||
|
|
@ -0,0 +1,125 @@
|
||||||
|
---
|
||||||
|
title: Migrating from your old (Bullseye) server
|
||||||
|
---
|
||||||
|
|
||||||
|
## Upgrade or fresh installation?
|
||||||
|
|
||||||
|
I recommend that you set up a new server and make sure that the new mail server is working correctly before you start migrating existing email users to it. You may argue that Debian can be upgraded easily using “apt-get dist-upgrade” but that is very dangerous on a live mail server. Automatic configuration changes may have evil side effects and you risk losing emails. At least you are causing a downtime for your users.
|
||||||
|
|
||||||
|
If you follow my advice then get a new server and install Debian Bookworm on it. Once the user mailboxes are migrated and all works well you can tear down the old server.
|
||||||
|
|
||||||
|
Once your new server is installed come back here.
|
||||||
|
|
||||||
|
## Read before you type
|
||||||
|
|
||||||
|
Follow this guide to the end. Only then start attempting a migration. Inform your users about the migration and set a time when you intend to move email accounts to the new server. The change will require a DNS change which takes a while to be visible worldwide so your users will have a period when incoming email is delayed. If you proceed careful though not a single email will be lost.
|
||||||
|
|
||||||
|
So you have your new server up and running and did everything to make it a working mail server? You really read all the pages in this guide and did what they told you? Okay, then let’s start.
|
||||||
|
|
||||||
|
## Turn down the TTL of your MX record
|
||||||
|
|
||||||
|
The DNS “MX” record for your domain contains the hostname of your mail server. When switching to the new server you need to change the MX record. Every DNS record has a TTL (time-to-live) that defines the period of time that a record will stay valid even after you change it. Usually that TTL is rather high like 86400 seconds (=1 day). This information is used by caching name servers that they can use the cached values for a day. Turn that TTL down temporarily to 60 seconds so that the rest of the internet will pick up your change quicker. However it will take a day until everyone else on the internet picks up your TTL change.
|
||||||
|
|
||||||
|
## Migrate the mailserver database
|
||||||
|
|
||||||
|
You need to copy the database that contains the control data about your email domains and accounts. Log into the old (Bullseye) server as root and back up the _mailserver_ database. That is as easy as running…
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mysqldump mailserver > mailserver.sql
|
||||||
|
```
|
||||||
|
Copy that file to the new server (using _scp_) and import it there:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mysql mailserver < mailserver.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
Obviously any database changes on the old server from now on will have to be done on the new server as well until the migration is done.
|
||||||
|
|
||||||
|
## Roundcube contacts
|
||||||
|
|
||||||
|
If your users are using Roundcube as a webmail interface then you should migrate their data like their contact lists. Dump the SQL from the old server:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mysqldump roundcube > roundcube.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
Copy that file to the new server and import it:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
mysql roundcube < roundcube.sql
|
||||||
|
```
|
||||||
|
|
||||||
|
One caveat though. To distinguish multiple mail servers Roundcube stores the server’s name in the mail_host column of the users table. So as a last step change that column if your new mail server has a new FQDN/hostname by running this SQL query on the new roundcube database:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
UPDATE users SET mail_host='new.mail.server';
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migrate rspamd spam training data
|
||||||
|
|
||||||
|
If you have been using rspamd with the Redis backend then copy over the Redis database from your previous server. 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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
rsync -va oldserver:/var/vmail/ /var/vmail/
|
||||||
|
```
|
||||||
|
|
||||||
|
(Note the trailing slashes. Type them exactly as shown above or your files will end up in wrong places.)
|
||||||
|
|
||||||
|
There is no need to shut down Dovecot on your production Bullseye server. Copying the files while Dovecot is running 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
|
||||||
|
|
||||||
|
Copy over everything in /etc/letsencrypt and /var/lib/rspamd/dkim from your old to the new server.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
rsync -va oldserver:/etc/letsencrypt/ /etc/letsencrypt/
|
||||||
|
rsync -va oldserver:/var/lib/rspamd/dkim/ /var/lib/rspamd/dkim/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Downtime
|
||||||
|
|
||||||
|
You told your users about the downtime, right? The time has come? Okay. Shut down Dovecot on both servers.
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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.)
|
||||||
|
|
||||||
|
The new Dovecot version uses a slightly different indexing mechanism. So force rebuilding the users’ indices:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
doveadm force-resync -A '*'
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
## Enable soft_bounce
|
||||||
|
|
||||||
|
Accidents happen. And you don’t want to lose emails. So run this command to enable your safety net on the new server:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
postconf soft_bounce=yes
|
||||||
|
```
|
||||||
|
|
||||||
|
This makes Postfix always keep emails in the queue that it would otherwise reject. So you can fix any errors and the queue will empty. Start Postfix and Dovecot on the new server. Watch your /var/log/mail.log and run “mailq” from time to time to see what emails get stuck in the queue. If you are certain that emails can be removed from the queue then use “postsuper -d QUEUE-ID” (as shown in the “mailq” output).
|
||||||
|
|
||||||
|
Once you are certain that emails are properly received and sent you can switch off the _soft_bounce_ mode again:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
postconf soft_bounce=no
|
||||||
|
```
|
||||||
|
|
||||||
|
## Shut down the old server
|
||||||
|
|
||||||
|
If possible do a final backup of the old server. If users are not complaining then dismiss the old system after a week.
|
||||||
92
src/content/docs/ispmail-bookworm/types-of-email-domains.mdx
Normal file
92
src/content/docs/ispmail-bookworm/types-of-email-domains.mdx
Normal file
|
|
@ -0,0 +1,92 @@
|
||||||
|
---
|
||||||
|
title: Types of email domains
|
||||||
|
---
|
||||||
|
|
||||||
|
import { Aside } from "@astrojs/starlight/components";
|
||||||
|
|
||||||
|
This is the pretty boring but at the same time very important part of the tutorial. Do not skip it. Most problems that
|
||||||
|
readers have with their mail servers are caused by a misunderstanding of the different types of email domains. There is
|
||||||
|
nothing you need to do on your server right now. Just lean back and relax and make sure that you read and fully
|
||||||
|
understand this page. It will spare you frustration.
|
||||||
|
|
||||||
|
As explained on the previous page Postfix is the software component that speaks SMTP. It receives emails from other
|
||||||
|
server and sends email out. Of course you will only want to receive emails for your domains only.
|
||||||
|
|
||||||
|
Postfix will accept emails for any of these [classes of domains](http://www.postfix.org/ADDRESS_CLASS_README.html):
|
||||||
|
|
||||||
|
1. Canonical domains (also called _local domains_)
|
||||||
|
2. Hosted domains
|
||||||
|
- Virtual mailbox domains
|
||||||
|
- Virtual alias domains
|
||||||
|
3. Relay domains
|
||||||
|
|
||||||
|
Let us look at the first two in detail. The third one – relay domains – is not needed in this context.
|
||||||
|
|
||||||
|
## Canonical domains
|
||||||
|
|
||||||
|
Once upon a time users logged into servers using [Telnet](https://en.wikipedia.org/wiki/Telnet) or
|
||||||
|
[SSH](https://en.wikipedia.org/wiki/Secure_Shell) to read their email in basic text-based mail clients. Their email
|
||||||
|
addresses were often just a combination of their login name and the server name. Something like
|
||||||
|
_mpauls@server17.biology.example.net_.
|
||||||
|
|
||||||
|
At least that made things pretty simple for the server administrator. He just accepted emails for any valid login user
|
||||||
|
on that server. The mail server knew what to do. It checked if “mpauls” is found in /etc/passwd and then stored emails
|
||||||
|
in “/var/mail/mpauls”.
|
||||||
|
|
||||||
|
If you wanted to do it that way…
|
||||||
|
|
||||||
|
1. You would need to create system accounts for all users who want to receive email. Every system user is a potential
|
||||||
|
security risk because they can login to the server using a shell. If the user chooses a weak password you are
|
||||||
|
essentially inviting attackers to harm your server.
|
||||||
|
2. If you want to host many email accounts this becomes impractical.
|
||||||
|
3. Postfix cannot distinguish the local domains. If you have three local domains “example.org”, “example.com” and
|
||||||
|
“example.net” then all these email addresses would lead to the same mailbox: john@example.org, john@example.com and
|
||||||
|
john@example.net. So you cannot use different domains for different purposes.
|
||||||
|
|
||||||
|
To tell Postfix which domain you consider local you list them in the “mydestination” configuration setting in your
|
||||||
|
main.cf configuration file. Example:
|
||||||
|
|
||||||
|
```
|
||||||
|
mydestination = example.org, example.com, example.net
|
||||||
|
```
|
||||||
|
|
||||||
|
<Aside type="caution">
|
||||||
|
A domain never belongs to more than one class. You would get a warning in your log file and Postfix will start
|
||||||
|
behaving strangely. One domain can only have one purpose. This is a frequent mistake.
|
||||||
|
</Aside>
|
||||||
|
|
||||||
|
It is common however to use the server’s hostname as a local domain. If your server is called “scully.example.com” you
|
||||||
|
could set “mydestination = scully.example.com”. Or you just set it to “mydestination = localhost” if you rather want to
|
||||||
|
use “scully.example.com” as a virtual domain. Some parts of your system may send emails to root@localhost so this is a
|
||||||
|
sane setting.
|
||||||
|
|
||||||
|
## Virtual domains
|
||||||
|
|
||||||
|
This is the class of domains that will be our workhorse. Postfix allows us to add an unlimited number of domains that
|
||||||
|
can receive emails. That’s what an ISP does and so will we.
|
||||||
|
|
||||||
|
Where do we put the list of domains? Postfix is pretty flexible. We could put it in a huge text file. We might use LDAP
|
||||||
|
if we have some kind of user directory in our organization. But in this guide we will store that information in a simple
|
||||||
|
MariaDB database.
|
||||||
|
|
||||||
|
Postfix handles hosted email addresses by checking two _mappings_:
|
||||||
|
|
||||||
|
- Virtual Aliases (“redirect this email address to another address”)
|
||||||
|
- Virtual Mailboxes (“accept email for this email address”)
|
||||||
|
|
||||||
|
So much terminology. Time for an example, isn’t it? Let’s tell Postfix we want to have three email addresses:
|
||||||
|
|
||||||
|
- john@example.org
|
||||||
|
- jack@example.org
|
||||||
|
- jack@example.com (_note that this is another domain than example.org_)
|
||||||
|
|
||||||
|
Postfix only understands _mappings_. They are much easier than they sound. A mapping is just a table that has a left and
|
||||||
|
a right column. Postfix always looks for stuff in the left column (_key_) to find more information in the right column
|
||||||
|
(_value_). Like this:
|
||||||
|
|
||||||
|
| Virtual mailbox (key) | Virtual mailbox location on disk (value) |
|
||||||
|
| --------------------- | ---------------------------------------- |
|
||||||
|
| john@example.org | /var/vmail/example.org/john/Maildir |
|
||||||
|
| jack@example.org | /var/vmail/example.org/jack/Maildir |
|
||||||
|
| jack@example.com | /var/vmail/example.com/jack/Maildir |
|
||||||
|
|
||||||
24
src/content/docs/ispmail-bookworm/whats-new.md
Normal file
24
src/content/docs/ispmail-bookworm/whats-new.md
Normal file
|
|
@ -0,0 +1,24 @@
|
||||||
|
---
|
||||||
|
title: What's new
|
||||||
|
lastUpdated: 2023-09-24
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
I try to keep as many parts of the setup unchanged. Many of us are happy with their mail servers and want to change as little as possible. Email is a boring matter anyway and we do our jobs best if our users don’t even realize that we are there.
|
||||||
|
|
||||||
|
A few things though that are new in this version of the ISPmail guide:
|
||||||
|
|
||||||
|
- **Newer software versions** – it is a new Debian release after all. There are no breaking changes. Just business as usual. If you want to check the changelogs here are the version changes:
|
||||||
|
- Postfix 3.5.18 -> 3.7.6
|
||||||
|
- Dovecot 2.3.13 -> 2.3.19
|
||||||
|
- PHP 7.4 -> 8.2
|
||||||
|
- rspamd 2.7.1 -> 3.4.1
|
||||||
|
- Apache 2.4.56 -> 2.4.57
|
||||||
|
- Roundcube 1.4.13 -> 1.6.1
|
||||||
|
- MariaDB 1.21 -> 1.22
|
||||||
|
- Adminer 4.7.9 -> 4.8.1
|
||||||
|
- An improved **Ansible** playbook to help you automate all the steps of this guide if you want to set up multiple servers without repeating all steps manually.
|
||||||
|
- Clearer explanations. I have reworded complex parts of the configuration.
|
||||||
|
- Fixed links. The Dovecot wiki has moved around quote a lot of pages and I didn’t notice earlier because it did not lead to a 404 or a redirect.
|
||||||
|
- Dovecot now uses the “count” backend to compute a user’s quota. Previous guides still used “maildir”.
|
||||||
|
- Two chapters are currently not published: the part about Thunderbird auto-configuration because there seem to be problems with the newest versions of Thunderbird. And the part about firewalling and fail2ban because there seems to be a bug with firewalld and fail2ban. These pages deal with optional features and are not a showstopper.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue