diff --git a/README.md b/README.md index b4c182f..26e60e8 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,30 @@ # ISPmail guide -This repository holds the ISPmail guide as found on workaround.org. +This repository contains the ISPmail guide as found on workaround.org. -It was built using the static site generator [Starlight](https://starlight.astro.build). +The web site is built the static site generator [Starlight](https://starlight.astro.build) which creates beautiful +documentation with table of contents, a search function and customizable widgets. -More information on how to contribute will follow. +The illustrations were created using DrawIO. The flip-book-style diagrams on the _big picture_ page were created using: -# Software used - -Static site generator: https://starlight.astro.build/ - -Diagrams/Illustrations: - -- DrawIO - https://github.com/pascal-brand38/astro-splide - https://pascal-brand38.github.io/astro-dev/packages/astro-splide/ - https://splidejs.com/guides/options/ + +## Contributing + +Feel free to clone this repository (the _prod_ branch) and make changes. You will need NodeJS to create the HTML from +the sources: + +```sh +apt install nodejs +npm i +npm run dev +``` + +Merge requests are always welcome. Typo fixes and rephrasing are always welcome because I am not a native english +speaker. If you want to contribute or change larger sections please talk to me first. + +Or just create an _issue_ here on Github so that I know what needs fixing. + +…[Christoph](mailto:ispmail@christoph-haas.de) diff --git a/astro.config.mjs b/astro.config.mjs index 8e4eaac..6f9568f 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -10,6 +10,17 @@ export default defineConfig({ site: "https://workaround.org", integrations: [ starlight({ + head: [ + { + tag: "script", + attrs: { + src: "https://rybbit.workaround.org/api/script.js", + "data-site-id": "1", + async: true, + defer: true, + }, + }, + ], expressiveCode: { frames: { removeCommentsWhenCopyingTerminalFrames: false, // keep the commented lines when copying shell snippets @@ -55,17 +66,17 @@ export default defineConfig({ }, }), // https://github.com/felix-berlin/astro-matomo - matomo({ - enabled: import.meta.env.PROD, // Only load in production - host: "https://matomo.workaround.org/", - setCookieDomain: "*.workaround.org", - trackerUrl: "js/", // defaults to matomo.php - srcUrl: "js/", // defaults to matomo.js - siteId: 1, - heartBeatTimer: 5, - disableCookies: true, - debug: false, - }), + // matomo({ + // enabled: import.meta.env.PROD, // Only load in production + // host: "https://matomo.workaround.org/", + // setCookieDomain: "*.workaround.org", + // trackerUrl: "js/", // defaults to matomo.php + // srcUrl: "js/", // defaults to matomo.js + // siteId: 1, + // heartBeatTimer: 5, + // disableCookies: true, + // debug: false, + // }), sitemap(), ], diff --git a/drawio/big-picture.drawio b/drawio/big-picture.drawio index e73dbe9..6800b7e 100644 --- a/drawio/big-picture.drawio +++ b/drawio/big-picture.drawio @@ -1,34 +1,34 @@ - + - + - + - + - + - + - + - + - + - + - + @@ -37,40 +37,40 @@ - + - + - + - + - + - + - + - + - + - + - + - + @@ -78,25 +78,25 @@ - + - + - + - + - + - + @@ -104,16 +104,16 @@ - + - + - + - + @@ -122,16 +122,16 @@ - + - + - + - + @@ -140,19 +140,19 @@ - + - + - + - + - + @@ -161,19 +161,19 @@ - + - + - + - + - + @@ -182,19 +182,19 @@ - + - + - + - + - + @@ -203,22 +203,22 @@ - + - + - + - + - + - + @@ -227,19 +227,19 @@ - + - + - + - + - + @@ -248,25 +248,25 @@ - + - + - + - + - + - + - + @@ -278,22 +278,22 @@ - + - + - + - + - + - + @@ -307,25 +307,25 @@ - + - + - + - + - + - + - + @@ -337,25 +337,25 @@ - + - + - + - + - + - + - + @@ -369,46 +369,46 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + @@ -416,22 +416,22 @@ - + - + - + - + - + - + @@ -443,25 +443,25 @@ - + - + - + - + - + - + - + @@ -475,25 +475,25 @@ - + - + - + - + - + - + @@ -502,61 +502,61 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/public/big-picture-receive/01.svg b/public/big-picture-receive/01.svg index 8f8ccbe..b81ca4c 100644 --- a/public/big-picture-receive/01.svg +++ b/public/big-picture-receive/01.svg @@ -1,3 +1,3 @@ -
Other
mail server
Other...
I would like to send an email to john@example.com
I would like to send an email to j...
\ No newline at end of file +
Other
mail server
Other...
I would like to send an email to john@example.com
I would like to send an email to j...
\ No newline at end of file diff --git a/public/big-picture-receive/02.svg b/public/big-picture-receive/02.svg index ac055cd..6831ec9 100644 --- a/public/big-picture-receive/02.svg +++ b/public/big-picture-receive/02.svg @@ -1,3 +1,3 @@ -
Name server
(DNS)
Name server...
Other
mail server
Other...
What is the MX record for the domain example.com?
What is the MX re...
\ No newline at end of file +
Name server
(DNS)
Name server...
Other
mail server
Other...
What is the MX record for the domain example.com?
What is the MX re...
\ No newline at end of file diff --git a/public/big-picture-receive/03.svg b/public/big-picture-receive/03.svg index c480263..b4c8b40 100644 --- a/public/big-picture-receive/03.svg +++ b/public/big-picture-receive/03.svg @@ -1,3 +1,3 @@ -
Name server
(DNS)
Name server...
Other
mail server
Other...
smtp01.example.net
smtp01.example.net
\ No newline at end of file +
Name server
(DNS)
Name server...
Other
mail server
Other...
smtp01.example.net
smtp01.example.net
\ No newline at end of file diff --git a/public/big-picture-receive/04.svg b/public/big-picture-receive/04.svg index 19589eb..203357b 100644 --- a/public/big-picture-receive/04.svg +++ b/public/big-picture-receive/04.svg @@ -1,3 +1,3 @@ -
Name server
(DNS)
Name server...
Other
mail server
Other...
What are the A and AAAAA records for smtp01.example.net?
What are the A and AA...
\ No newline at end of file +
Name server
(DNS)
Name server...
Other
mail server
Other...
What are the A and AAAAA records for smtp01.example.net?
What are the A and AA...
\ No newline at end of file diff --git a/public/big-picture-receive/05.svg b/public/big-picture-receive/05.svg index 767508a..d04d3e4 100644 --- a/public/big-picture-receive/05.svg +++ b/public/big-picture-receive/05.svg @@ -1,3 +1,3 @@ -
Name server
(DNS)
Name server...
Other
mail server
Other...
A: 100.17.195.84
AAAA: 2001:876:18:5::ce
A: 100.17.195.84...
\ No newline at end of file +
Name server
(DNS)
Name server...
Other
mail server
Other...
A: 100.17.195.84
AAAA: 2001:876:18:5::ce
A: 100.17.195.84...
\ No newline at end of file diff --git a/public/big-picture-receive/06.svg b/public/big-picture-receive/06.svg index 3eba5f0..af43a7e 100644 --- a/public/big-picture-receive/06.svg +++ b/public/big-picture-receive/06.svg @@ -1,3 +1,3 @@ -
SMTP
(TCP port 25)
SMTP...
Postfix
mail server
Postfix...
Other
mail server
Other...
\ No newline at end of file +
SMTP
(TCP port 25)
SMTP...
Postfix
mail server
Postfix...
Other
mail server
Other...
\ No newline at end of file diff --git a/public/big-picture-receive/07.svg b/public/big-picture-receive/07.svg index b789615..e248e60 100644 --- a/public/big-picture-receive/07.svg +++ b/public/big-picture-receive/07.svg @@ -1,3 +1,3 @@ -
220 smtp01.example.net
ESMTP Postfix
220 smtp01.example.net...
Postfix
mail server
Postfix...
Other
mail server
Other...
Nice to see you.
Nice to see you.
\ No newline at end of file +
220 smtp01.example.net
ESMTP Postfix
220 smtp01.example.net...
Postfix
mail server
Postfix...
Other
mail server
Other...
Nice to see you.
Nice to see you.
\ No newline at end of file diff --git a/public/big-picture-receive/08.svg b/public/big-picture-receive/08.svg index 3c7531e..4eb096c 100644 --- a/public/big-picture-receive/08.svg +++ b/public/big-picture-receive/08.svg @@ -1,3 +1,3 @@ -
EHLO remoteserver
EHLO remoteserver
Postfix
mail server
Postfix...
Other
mail server
Other...
Hi, my name is "remoteserver"
Hi, my name is "remot...
\ No newline at end of file +
EHLO remoteserver
EHLO remoteserver
Postfix
mail server
Postfix...
Other
mail server
Other...
Hi, my name is "remoteserver"
Hi, my name is "remot...
\ No newline at end of file diff --git a/public/big-picture-receive/09.svg b/public/big-picture-receive/09.svg index 3eb2182..6c79fc9 100644 --- a/public/big-picture-receive/09.svg +++ b/public/big-picture-receive/09.svg @@ -1,3 +1,3 @@ -
250-smtp01.example.com
250-SIZE 40000000
250-STARTTLS
250-ENHANCEDSTATUSCODES
250-8BITMIME
250-smtp01.example.com...
Postfix
mail server
Postfix...
Other
mail server
Other...
These are the features that I support.
These are the features...
\ No newline at end of file +
250-smtp01.example.com
250-SIZE 40000000
250-STARTTLS
250-ENHANCEDSTATUSCODES
250-8BITMIME
250-smtp01.example.com...
Postfix
mail server
Postfix...
Other
mail server
Other...
These are the features that I support.
These are the features...
\ No newline at end of file diff --git a/public/big-picture-receive/10.svg b/public/big-picture-receive/10.svg index 21fc955..a5fc61f 100644 --- a/public/big-picture-receive/10.svg +++ b/public/big-picture-receive/10.svg @@ -1,3 +1,3 @@ -
STARTTLS
STARTTLS
Postfix
mail server
Postfix...
Other
mail server
Other...
Let us switch to encrypted communication
Let us switch to encr...
\ No newline at end of file +
STARTTLS
STARTTLS
Postfix
mail server
Postfix...
Other
mail server
Other...
Let us switch to encrypted communication
Let us switch to encr...
\ No newline at end of file diff --git a/public/big-picture-receive/11.svg b/public/big-picture-receive/11.svg index 2a4441a..96e7d27 100644 --- a/public/big-picture-receive/11.svg +++ b/public/big-picture-receive/11.svg @@ -1,3 +1,3 @@ -
MAIL FROM: <someone@else.com>
MAIL FROM: <someone@else.com>
Postfix
mail server
Postfix...
Other
mail server
Other...
I have an email from someone@else.com
I have an email from...
\ No newline at end of file +
MAIL FROM: <someone@else.com>
MAIL FROM: <someone@else.com>
Postfix
mail server
Postfix...
Other
mail server
Other...
I have an email from someone@else.com
I have an email from...
\ No newline at end of file diff --git a/public/big-picture-receive/12.svg b/public/big-picture-receive/12.svg index 4da2ab0..5f4a28a 100644 --- a/public/big-picture-receive/12.svg +++ b/public/big-picture-receive/12.svg @@ -1,3 +1,3 @@ -
Ok
Ok
Postfix
mail server
Postfix...
Other
mail server
Other...
\ No newline at end of file +
Ok
Ok
Postfix
mail server
Postfix...
Other
mail server
Other...
\ No newline at end of file diff --git a/public/big-picture-receive/13.svg b/public/big-picture-receive/13.svg index b19a405..4ea1440 100644 --- a/public/big-picture-receive/13.svg +++ b/public/big-picture-receive/13.svg @@ -1,3 +1,3 @@ -
RCPT TO: <john@example.org>
RCPT TO: <john@example.org>
Postfix
mail server
Postfix...
Other
mail server
Other...
That email is meant for john@example.org
That email is meant f...
\ No newline at end of file +
RCPT TO: <john@example.org>
RCPT TO: <john@example.org>
Postfix
mail server
Postfix...
Other
mail server
Other...
That email is meant for john@example.org
That email is meant f...
\ No newline at end of file diff --git a/public/big-picture-receive/14.svg b/public/big-picture-receive/14.svg index 8eec544..3d44682 100644 --- a/public/big-picture-receive/14.svg +++ b/public/big-picture-receive/14.svg @@ -1,3 +1,3 @@ -
Postfix
mail server
Postfix...
Other
mail server
Other...
MariaDB
database
MariaDB...
Is example.org our domain?
Is example.org o...
\ No newline at end of file +
Postfix
mail server
Postfix...
Other
mail server
Other...
MariaDB
database
MariaDB...
Is example.org our domain?
Is example.org o...
\ No newline at end of file diff --git a/public/big-picture-receive/15.svg b/public/big-picture-receive/15.svg index e64758b..4c93635 100644 --- a/public/big-picture-receive/15.svg +++ b/public/big-picture-receive/15.svg @@ -1,3 +1,3 @@ -
Postfix
mail server
Postfix...
Other
mail server
Other...
MariaDB
database
MariaDB...
Yes, I found it in my virtual_domains table
Yes, I found it in...
\ No newline at end of file +
Postfix
mail server
Postfix...
Other
mail server
Other...
MariaDB
database
MariaDB...
Yes, I found it in my virtual_domains table
Yes, I found it in...
\ No newline at end of file diff --git a/public/big-picture-receive/16.svg b/public/big-picture-receive/16.svg index 163078f..470b01b 100644 --- a/public/big-picture-receive/16.svg +++ b/public/big-picture-receive/16.svg @@ -1,3 +1,3 @@ -
Postfix
mail server
Postfix...
Other
mail server
Other...
MariaDB
database
MariaDB...
And is john@example.org a known user?
And is john@example.or...
\ No newline at end of file +
Postfix
mail server
Postfix...
Other
mail server
Other...
MariaDB
database
MariaDB...
And is john@example.org a known user?
And is john@example.or...
\ No newline at end of file diff --git a/public/big-picture-receive/17.svg b/public/big-picture-receive/17.svg index 886c091..33bca2a 100644 --- a/public/big-picture-receive/17.svg +++ b/public/big-picture-receive/17.svg @@ -1,4 +1,3 @@ - -
Postfix
mail server
Other
mail server
MariaDB
database
Yes, I found it in my virtual_users table
\ No newline at end of file +
Postfix
mail server
Postfix...
Other
mail server
Other...
MariaDB
database
MariaDB...
Yes, I found it in my virtual_users table
Yes, I found it in my...
\ No newline at end of file diff --git a/public/big-picture-receive/18.svg b/public/big-picture-receive/18.svg index c30a144..74d239b 100644 --- a/public/big-picture-receive/18.svg +++ b/public/big-picture-receive/18.svg @@ -1,3 +1,3 @@ -
Ok
Ok
Postfix
mail server
Postfix...
Other
mail server
Other...
Looks good.
Looks good.
\ No newline at end of file +
Ok
Ok
Postfix
mail server
Postfix...
Other
mail server
Other...
Looks good.
Looks good.
\ No newline at end of file diff --git a/public/big-picture-receive/19.svg b/public/big-picture-receive/19.svg index cb513b5..a91c7ab 100644 --- a/public/big-picture-receive/19.svg +++ b/public/big-picture-receive/19.svg @@ -1,3 +1,3 @@ -
DATA
DATA
Postfix
mail server
Postfix...
Other
mail server
Other...
Let me send you the email now
Let me send you t...
\ No newline at end of file +
DATA
DATA
Postfix
mail server
Postfix...
Other
mail server
Other...
Let me send you the email now
Let me send you t...
\ No newline at end of file diff --git a/public/big-picture-receive/20.svg b/public/big-picture-receive/20.svg index 8645424..fd0f66f 100644 --- a/public/big-picture-receive/20.svg +++ b/public/big-picture-receive/20.svg @@ -1,3 +1,3 @@ -
TCP port 11332
TCP port 11332
Postfix
mail server
Postfix...
Other
mail server
Other...
rspamd
Spam check
rspamd...
Do you think this email is spam?
Do you think this...
\ No newline at end of file +
TCP port 11332
TCP port 11332
Postfix
mail server
Postfix...
Other
mail server
Other...
rspamd
Spam check
rspamd...
Do you think this email is spam?
Do you think this...
\ No newline at end of file diff --git a/public/big-picture-receive/21.svg b/public/big-picture-receive/21.svg index 9375170..4316f8d 100644 --- a/public/big-picture-receive/21.svg +++ b/public/big-picture-receive/21.svg @@ -1,3 +1,3 @@ -
Postfix
mail server
Postfix...
Other
mail server
Other...
rspamd
Spam check
rspamd...
A few minor issues but the email seems legit
A few minor issues...
\ No newline at end of file +
Postfix
mail server
Postfix...
Other
mail server
Other...
rspamd
Spam check
rspamd...
A few minor issues but the email seems legit
A few minor issues...
\ No newline at end of file diff --git a/public/big-picture-receive/22.svg b/public/big-picture-receive/22.svg index 3543078..1302dd3 100644 --- a/public/big-picture-receive/22.svg +++ b/public/big-picture-receive/22.svg @@ -1,3 +1,3 @@ -
250 2.0.0 Ok: queued as 7855B7FD86
250 2.0.0 Ok: queued as 7855B7FD86
Postfix
mail server
Postfix...
Other
mail server
Other...
Thanks. I will deliver it.
Thanks. I will d...
\ No newline at end of file +
250 2.0.0 Ok: queued as 7855B7FD86
250 2.0.0 Ok: queued as 7855B7FD86
Postfix
mail server
Postfix...
Other
mail server
Other...
Thanks. I will deliver it.
Thanks. I will d...
\ No newline at end of file diff --git a/public/big-picture-receive/23.svg b/public/big-picture-receive/23.svg index 609be6e..07935e8 100644 --- a/public/big-picture-receive/23.svg +++ b/public/big-picture-receive/23.svg @@ -1,4 +1,3 @@ - -
LMTP
Postfix
mail server
Please save this new email for john@example.org
Dovecot
IMAP server
\ No newline at end of file +
LMTP
LMTP
Postfix
mail server
Postfix...
Please save this new email for john@example.org
Please save this new e...
Dovecot
IMAP server
Dovecot...
\ No newline at end of file diff --git a/public/big-picture-receive/24.svg b/public/big-picture-receive/24.svg index 49fcf86..8a5c994 100644 --- a/public/big-picture-receive/24.svg +++ b/public/big-picture-receive/24.svg @@ -1,3 +1,3 @@ -
Postfix
mail server
Postfix...
Dovecot
IMAP server
Dovecot...
/var/vmail
/var/vmail
Alright. Saving to disk.
Alright. Saving...
\ No newline at end of file +
Postfix
mail server
Postfix...
Dovecot
IMAP server
Dovecot...
/var/vmail
/var/vmail
Alright. Saving to disk.
Alright. Saving...
\ No newline at end of file diff --git a/src/content/docs/ispmail-trixie/110-upgrading.mdx b/src/content/docs/ispmail-trixie/110-upgrading.mdx index ac4d7d1..4f0732f 100644 --- a/src/content/docs/ispmail-trixie/110-upgrading.mdx +++ b/src/content/docs/ispmail-trixie/110-upgrading.mdx @@ -77,18 +77,32 @@ mariadb 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. +## Weak password schemes + +Please check if any of your users have hashed passwords that are considered +[weak](https://doc.dovecot.org/2.4.2/core/config/auth/schemes.html) by Dovecot. Those passwords using a `PLAIN-MD5` +scheme are not accepted by Dovecot by default. But you can enable them again using: + +```sh +cat > 99-ispmail-weak-schemes.conf << EOF +auth_allow_weak_schemes = yes +EOF +``` + +Your users should change their passwords using Roundcube. That way a new hash with a more secure schema is created. + ## 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 mariadb-dump roundcube > roundcube.sql ``` Copy that file to the new server and import it: -``` +```sh mariadb roundcube < roundcube.sql ``` @@ -103,7 +117,15 @@ 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. + +Stop rspamd on both the old and the new server. Then: + +```sh +rsync -va oldserver:/var/lib/redis/ /var/lib/redis/ +``` + +Once the redis database is started again on the new server, `rspamc stat` should show you that the training data is +found. ## Migrate the Maildirs hot @@ -129,9 +151,10 @@ need to copy emails from another server where you only have IMAP access but cann Copy over everything in /etc/letsencrypt and /var/lib/rspamd/dkim from your old to the new server. -``` -rsync -va oldserver:/etc/letsencrypt/ /etc/letsencrypt/ +```sh +rsync -va oldserver:/etc/letsencrypt/archive/ /etc/letsencrypt/archive/ rsync -va oldserver:/var/lib/rspamd/dkim/ /var/lib/rspamd/dkim/ +rsync -v oldserver:/etc/rspamd/dkim_selectors.map /etc/rspamd ``` ## Downtime @@ -144,7 +167,7 @@ You told your users about the downtime, right? The time has come? Okay. Shut dow 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: -``` +```sh rsync -va --delete oldserver:/var/vmail/ /var/vmail/ ``` @@ -177,3 +200,13 @@ 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. + +## Further issues + +You may see error messages like: + +``` +Error: sieve: binary /var/vmail/example.org/user/.dovecot.svbin: read: binary stored with different major version 2.0 (!= 3.0; automatically fixed when re-compiled) +``` + +You may need to run `sievec` on those files. diff --git a/src/content/docs/ispmail-trixie/158-certbot.mdx b/src/content/docs/ispmail-trixie/158-certbot.mdx index 59081d3..6a06987 100644 --- a/src/content/docs/ispmail-trixie/158-certbot.mdx +++ b/src/content/docs/ispmail-trixie/158-certbot.mdx @@ -109,7 +109,17 @@ It is important that services that use the certificate load the new certificate 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" +cat > /etc/letsencrypt/cli.ini << 'EOF' +# Restart services after renewing a certificate +post-hook = systemctl reload postfix dovecot apache2 + +# Because we are using logrotate for greater flexibility, disable the +# internal certbot logrotation. +max-log-backups = 0 + +# Adjust interactive output regarding automated renewal +preconfigured-renewal = True +EOF ``` Perfect. You won't have to worry about the certificate again. diff --git a/src/content/docs/ispmail-trixie/165-dovecot.mdx b/src/content/docs/ispmail-trixie/165-dovecot.mdx index 8f99d78..15aefe0 100644 --- a/src/content/docs/ispmail-trixie/165-dovecot.mdx +++ b/src/content/docs/ispmail-trixie/165-dovecot.mdx @@ -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. Please comment all all include statements: +we want to use the MariaDB database backend. Please comment out all include statements: ```text title="Edit your /etc/dovecot/conf.d/10-auth.conf" #!include auth-system.conf.ext @@ -113,7 +113,7 @@ to authenticate your users which is relevant later when we set up _relaying_. Earlier in this guide you created both a key and a certificate file to encrypt the communication with IMAPS and HTTPS between the users and your mail server. You need to tell Dovecot where to find these files. Also set [ssl=required](https://doc.dovecot.org/2.4.1/core/config/ssl.html#how-to-specify-when-ssl-tls-is-required) to prevent -that someone sends their password without encryption. Again we will create a new file `99-ispmail-master.conf` to +that someone sends their password without encryption. Again we will create a new file `99-ispmail-ssl.conf` to override the defaults.