Merge branch 'master' into rc-login

.github/renovate.json

@@ -0,0 +1,11 @@
+{
+  "enabled": true,
+  "timezone": "Europe/Berlin",
+  "dependencyDashboard": true,
+  "dependencyDashboardTitle": "Renovate Dashboard",
+  "commitBody": "Signed-off-by: Peter <magic@kthx.at>",
+  "rebaseWhen": "auto",
+  "assignees": [
+    "@magiccc"
+  ]
+}

.github/workflows/gh-pages.yml

@@ -0,0 +1,32 @@
+name: Build and deploy to gh-pages
+on:
+   push:
+     branches:
+       - master
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 📥
+        uses: actions/checkout@v2.4.0
+        with:
+          token: '${{ secrets.GHPAGES_ACTION_CHECKOUT_TOKEN_PAT }}'
+
+      - name: Install dependencies 🐄
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install python3-pip
+          pip install -r requirements.txt
+
+      - name: Build site 🔧
+        run: |
+          mkdocs build --verbose --clean
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4.2.2
+        with:
+          token: '${{ secrets.GHPAGES_ACTION_DEPLOY_TOKEN_PAT }}'
+          git-config-name: '${{ secrets.GHPAGES_ACTION_DEPLOY_GITNAME_PAT }}'
+          git-config-email: '${{ secrets.GHPAGES_ACTION_DEPLOY_GITEMAIL_PAT }}'
+          branch: gh-pages # The branch the action should deploy to.
+          folder: site # The folder the action should deploy.

.github/workflows/renovate_check-build.yml

@@ -0,0 +1,23 @@
+name: Check build for renovate
+on:
+   push:
+     branches:
+       - 'renovate/**'
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 📥
+        uses: actions/checkout@v2.4.0
+        with:
+          token: '${{ secrets.GHPAGES_ACTION_CHECKOUT_TOKEN_PAT }}'
+
+      - name: Install dependencies 🐄
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install python3-pip
+          pip install -r requirements.txt
+
+      - name: Build site 🔧
+        run: |
+          mkdocs build --verbose --clean

.travis.yml

@@ -1,14 +0,0 @@
-language: python
-install:
-- pip install mkdocs-material pygments
-script:
-- mkdocs build --verbose --clean
-deploy:
- provider: pages
- skip_cleanup: true
- github_token: $GITHUB_TOKEN
- local_dir: site
- name: $BOT_NAME
- email: $BOT_EMAIL
- on:
-   branch: master

README.md

@@ -1,4 +1,4 @@
-![TRAVIS-CI](https://api.travis-ci.org/mailcow/mailcow-dockerized-docs.svg?branch=master)
+[![Build and deploy to gh-pages](https://img.shields.io/github/workflow/status/mailcow/mailcow-dockerized-docs/Build%20and%20deploy%20to%20gh-pages/master?label=Build%20and%20deploy%20to%20gh-pages)](https://github.com/mailcow/mailcow-dockerized-docs/actions/workflows/gh-pages.yml)
 
 # mailcow: dockerized documentation
 
@@ -9,6 +9,7 @@ https://mailcow.github.io/mailcow-dockerized-docs
 To build it locally, you need the [Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/), [MkDocs](https://www.mkdocs.org/) itself and [Pygments](http://pygments.org/). To install these with [pip](https://pip.pypa.io/en/stable/) and get it up and running, fire up your terminal and enter
 
 ```
-pip install mkdocs-material
+git clone https://github.com/mailcow/mailcow-dockerized-docs.git
+pip install -r requirements.txt
 mkdocs serve
 ```

docs/b_n_r-accidental_deletion.md

@@ -0,0 +1,40 @@
+So you deleted a mailbox and have no backups, he?
+
+If you noticed your mistake within a few hours, you can probably recover the users data.
+
+### SOGo
+
+We automatically create daily backups (24h interval starting from running up -d) in `/var/lib/docker/volumes/mailcowdockerized_sogo-userdata-backup-vol-1/_data/`.
+
+**Make sure the user you want to restore exists in your mailcow**. Re-create them if they are missing.
+
+Copy the file named after the user you want to restore to `__MAILCOW_DIRECTORY__/data/conf/sogo`.
+
+1\. Copy the backup: `cp /var/lib/docker/volumes/mailcowdockerized_sogo-userdata-backup-vol-1/_data/restoreme@example.org __MAILCOW_DIRECTORY__/data/conf/sogo`
+
+2\. Run `docker-compose exec -u sogo sogo-mailcow sogo-tool restore -F ALL /etc/sogo restoreme@example.org`
+
+Run `sogo-tool` without parameters to check for possible restore options.
+
+3\. Delete the copied backup by running `rm __MAILCOW_DIRECTORY__/data/conf/sogo`
+
+4\. Restart SOGo and Memcached: `docker-compose restart sogo-mailcow memcached-mailcow`
+
+### Mail
+
+In case of an accidental deletion of a mailbox, you will be able to recover for (by default) 5 days. This depends on the `MAILDIR_GC_TIME` parameter in `mailcow.conf`.
+
+A deleted mailbox is copied in its encrypted form to `/var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data/_garbage`.
+
+The folder inside `_garbage` follows the structure `[timestamp]_[domain_sanitized][user_sanitized]`, for example `1629109708_exampleorgtest` in case of test@example.org deleted on 1629109708.
+
+To restore make sure you are actually restoring to the same mailcow it was deleted from or you use the same encryption keys in `crypt-vol-1`.
+
+**Make sure the user you want to restore exists in your mailcow**. Re-create them if they are missing.
+
+Copy the folders from `/var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data/_garbage/[timestamp]_[domain_sanitized][user_sanitized]` back to `/var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data/[domain]/[user]` and resync the folder and recalc the quota:
+
+```
+docker-compose exec dovecot-mailcow doveadm force-resync -u restoreme@example.net '*'
+docker-compose exec dovecot-mailcow doveadm quota recalc -u restoreme@example.net
+```

docs/b_n_r-backup.md

@@ -0,0 +1,97 @@
+### Backup
+
+#### Manual
+
+You can use the provided script `helper-scripts/backup_and_restore.sh` to backup mailcow automatically.
+
+Please do not copy this script to another location.
+
+To run a backup, write "backup" as first parameter and either one or more components to backup as following parameters.
+You can also use "all" as second parameter to backup all components. Append `--delete-days n` to delete backups older than n days.
+
+```
+# Syntax:
+# ./helper-scripts/backup_and_restore.sh backup (vmail|crypt|redis|rspamd|postfix|mysql|all|--delete-days)
+
+# Backup all, delete backups older than 3 days
+./helper-scripts/backup_and_restore.sh backup all --delete-days 3
+
+# Backup vmail, crypt and mysql data, delete backups older than 30 days
+./helper-scripts/backup_and_restore.sh backup vmail crypt mysql --delete-days 30
+
+# Backup vmail
+./helper-scripts/backup_and_restore.sh backup vmail
+
+```
+
+The script will ask you for a backup location. Inside of this location it will create folders in the format "mailcow_DATE".
+You should not rename those folders to not break the restore process.
+
+To run a backup unattended, define MAILCOW_BACKUP_LOCATION as environment variable before starting the script:
+
+```
+MAILCOW_BACKUP_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
+```
+
+#### Cronjob
+
+You can run the backup script regularly via cronjob. Make sure `BACKUP_LOCATION` exists:
+
+```
+5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/mnt/mailcow_backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup mysql crypt redis --delete-days 3
+```
+
+Per default cron sends the full result of each backup operation by email. If you want cron to only mail on error (non-zero exit code) you may want to use the following snippet. Pathes need to be modified according to your setup (this script is a user contribution).
+
+This following script may be placed in `/etc/cron.daily/mailcow-backup` - do not forget to mark it as executable via `chmod +x`:
+
+```
+#!/bin/sh
+
+# Backup mailcow data
+# https://mailcow.github.io/mailcow-dockerized-docs/b_n_r_backup/
+
+set -e
+
+OUT="$(mktemp)"
+export MAILCOW_BACKUP_LOCATION="/opt/backup"
+SCRIPT="/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh"
+PARAMETERS="backup all"
+OPTIONS="--delete-days 30"
+
+# run command
+set +e
+"${SCRIPT}" ${PARAMETERS} ${OPTIONS} 2>&1 > "$OUT"
+RESULT=$?
+
+if [ $RESULT -ne 0 ]
+    then
+            echo "${SCRIPT} ${PARAMETERS} ${OPTIONS} encounters an error:"
+            echo "RESULT=$RESULT"
+            echo "STDOUT / STDERR:"
+            cat "$OUT"
+fi
+```
+
+# Backup strategy with rsync and mailcow backup script
+
+Create the destination directory for mailcows helper script:
+```
+mkdir -p /external_share/backups/backup_script
+```
+
+Create cronjobs:
+```
+25 1 * * * rsync -aH --delete /opt/mailcow-dockerized /external_share/backups/mailcow-dockerized
+40 2 * * * rsync -aH --delete /var/lib/docker/volumes /external_share/backups/var_lib_docker_volumes
+5 4 * * * cd /opt/mailcow-dockerized/; BACKUP_LOCATION=/external_share/backups/backup_script /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup mysql crypt redis --delete-days 3
+# If you want to, use the acl util to backup permissions of some/all folders/files: getfacl -Rn /path
+```
+
+On the destination (in this case `/external_share/backups`) you may want to have snapshot capabilities (ZFS, Btrfs etc.). Snapshot daily and keep for n days for a consistent backup.
+Do **not** rsync to a Samba share, you need to keep the correct permissions!
+
+To restore you'd simply need to run rsync the other way round and restart Docker to re-read the volumes. Run `docker-compose pull` and `docker-compose up -d`.
+
+If you are lucky Redis and MariaDB can automatically fix the inconsistent databases (if they _are_ inconsistent).
+In case of a corrupted database you'd need to use the helper script to restore the inconsistent elements. If a restore fails, try to extract the backups and copy the files back manually. Keep the file permissions!

docs/b_n_r-coldstandby.md

@@ -0,0 +1,98 @@
+# Cold-standby backup
+
+mailcow offers an easy way to create a consistent copy of itself to be rsync'ed to a remote location without downtime.
+
+This may also be used to transfer your mailcow to a new server.
+
+## You should know
+
+The provided script will work on default installations.
+
+It may break when you use unsupported volume overrides. We don't support that and we will not include hacks to support that. Please run and maintain a fork if you plan to keep your changes.
+
+The script will use **the same pathes** as your default mailcow installation. That is the mailcow base directory - for most users `/opt/mailcow-dockerized` - as well as the mountpoints.
+
+To find the pathes of your source volumes we use `docker inspect` and read the destination directory of every volume related to your mailcow compose project. This means we will also transfer volumes you may have added in a override file. Local bind mounts may or may not work.
+
+The use rsync with the `--delete` flag. The destination will be an exact copy of the source.
+
+`mariabackup` is used to create a consistent copy of the SQL data directory.
+
+After rsync'ing the data we will run `docker-compose pull` and remove old image tags from the destination.
+
+Your source will not be changed at any time.
+
+**You may want to make sure to use the same `/etc/docker/daemon.json` on the remote target.**
+
+You should not run disk snapshots (e.g. via ZFS, LVM etc.) on the target at the very same time as this script is run.
+
+Versioning is not part of this script, we rely on the destination (snapshots or backups). You may also want to use any other tool for that.
+
+## Prepare
+
+You will need a SSH-enabled destination and a keyfile to connect to said destination. The key should not be protected by a password for the script to work unattended.
+
+In your mailcow base directory, e.g. `/opt/mailcow-dockerized` you will find a file `create_cold_standby.sh`.
+
+Edit this file and change the exported variables:
+
+```
+export REMOTE_SSH_KEY=/path/to/keyfile
+export REMOTE_SSH_PORT=22
+export REMOTE_SSH_HOST=mailcow-backup.host.name
+```
+
+The key must be owned and readable by root only.
+
+Both the source and destination require `rsync` >= v3.1.0.
+The destination must have Docker and docker-compose **v1** available.
+
+The script will detect errors automatically and exit.
+
+You may want to test the connection by running `ssh mailcow-backup.host.name -p22 -i /path/to/keyfile`.
+
+## Backup and refresh the cold-standby
+
+Run the first backup, this may take a while depending on the connection:
+
+```
+bash /opt/mailcow-dockerized/create_cold_standby.sh
+```
+
+That was easy, wasn't it?
+
+Updating your cold-standby is just as easy:
+
+```
+bash /opt/mailcow-dockerized/create_cold_standby.sh
+```
+
+It's the same command.
+
+## Automated backups with cron
+
+First make sure that the `cron` service is enabled and running:
+
+```
+systemctl enable cron.service && systemctl start cron.service
+```
+
+To automate the backups to the cold-standby server you can use a cron job. To edit the cron jobs for the root user run:
+
+```
+crontab -e
+```
+
+Add the following lines to synchronize the cold standby server daily at 03:00. In this example errors of the last execution are logged into a file.
+
+```
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+
+0 3 * * * bash /opt/mailcow-dockerized/create_cold_standby.sh 2> /var/log/mailcow-coldstandby-sync.log
+```
+
+If saved correctly, the cron job should be shown by typing:
+
+```
+crontab -l
+```

docs/b_n_r_backup.md

@@ -1,32 +0,0 @@
-### Backup
-
-You can use the provided script `helper-scripts/backup_and_restore.sh` to backup mailcow automatically.
-
-Please do not copy this script to another location.
-
-To run a backup, write "backup" as first parameter and either one or more components to backup as following parameters.
-You can also use "all" as second parameter to backup all components. Append `--delete-days n` to delete backups older than n days.
-
-```
-# Syntax:
-# ./helper-scripts/backup_and_restore.sh backup (vmail|crypt|redis|rspamd|postfix|mysql|all|--delete-days)
-
-# Backup all, delete backups older than 3 days
-./helper-scripts/backup_and_restore.sh backup all --delete-days 3
-
-# Backup vmail, crypt and mysql data, delete backups older than 30 days
-./helper-scripts/backup_and_restore.sh backup vmail crypt mysql --delete-days 30
-
-# Backup vmail
-./helper-scripts/backup_and_restore.sh backup vmail
-
-```
-
-The script will ask you for a backup location. Inside of this location it will create folders in the format "mailcow_DATE".
-You should not rename those folders to not break the restore process.
-
-To run a backup unattended, define MAILCOW_BACKUP_LOCATION as environment variable before starting the script:
-
-```
-MAILCOW_BACKUP_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
-```

docs/client/client-thunderbird.md

@@ -6,76 +6,22 @@
   If this is the first time you launched Thunderbird, it asks you whether you would like a new email address. Click <i>Skip this and use my existing email</i> and proceed to step 4.
 </li>
 <li>
-  Go to the <i>Tools</i> menu and select <i>Account Settings</i>.
+  Go to the <i>File</i> menu and select <i>New</i>, <i>Existing Mail Account...</i>.
-</li>
-<li>
-  Click the <i>Account Actions</i> dropdown menu at the bottom left and select <i>Add Mail Account</i>.
 </li>
 <li>
   Enter your name<span class="client_variables_available"> (<code><span class="client_var_name"></span></code>)</span>, email address<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> and your password. Make sure the <i>Remember password</i> checkbox is selected and click <i>Continue</i>.
 </li>
 <li>
-  Once the configuration has been automatically detected, click <i>Done</i>.
+  Once the configuration has been automatically detected, make sure <i>IMAP</i> is selected and click <i>Done</i>.
 </li>
 <li>
-  If you already had other accounts configured in Thunderbird, select the new one<span class="client_variables_available"> (<code><span class="client_var_email"></span></code>)</span> on the left, click the <i>Account Actions</i> dropdown and select Set as <i>Default</i>.
+  To use your contacts from the server, click on the arrow next to "Address Books" and click the <i>Connect</i> button on each address book you would like to use.
 </li>
 <li>
-  Close the account settings window with the <i>OK</i> button.
+  To use your calendars from the server, click on the arrow next to "Calendars" and click the <i>Connect</i> button on each calendar you would like to use.
 </li>
-<li class="client_connector_enabled">
+<li>
-  In your web browser, download <span class="client_variables_unavailable">SOGo Connector</span><span class="client_variables_available"><a class="client_var_connector_link client_var_link" href="/thunderbird-plugins/sogo-connector-__VERSION__-__DOMAIN__.xpi">SOGo Connector</a></span>.
+  Click <i>Finish to close the Account Setup window.
-</li>
-<li class="client_connector_enabled">
-  Back in Thunderbird, go to the <i>Tools</i> menu and select <i>Add-ons</i>.
-</li>
-<li class="client_connector_enabled">
-  Click <i>Extensions</i> on the left and ensure that the <i>Lightning</i> add-on is already installed. It is installed by default in the Windows and macOS versions of Thunderbird, but if you are running Linux and installed Thunderbird through your distribution's package manager, <i>Lightning</i> might be available as a separate package (e.g. xul-ext-lightning on Ubuntu).
-</li>
-<li class="client_connector_enabled">
-  Click <i>Extensions</i> on the left, click the little gear icon at the top and select <i>Install Add-on From File</i>. Select the file you downloaded in step 9, click <i>Open</i> and, after waiting for a few seconds, <i>Install Now</i>.
-</li>
-<li class="client_connector_enabled">
-  Click the <i>Restart Now</i> button at the top that appears.
-</li>
-<li class="client_connector_enabled">
-  Thunderbird briefly shows a message that it is updating extensions, then restarts automatically once more.
-</li>
-<li class="client_connector_enabled">
-  When you are prompted to authenticate<span class="client_variables_available"> for <code><span class="client_var_host"></span><span class="client_var_port"></span></code></span>, enter your email address and password, check <i>Use Password Manager</i> and click <i>OK</i>.
 </li>
 </ol>
 
-<div class="client_connector_disabled client_variables_available" markdown="1">
-Automatic configuration of calendars and address books in Thunderbird is not currently supported.
-      You can ask your server administrator to enable SOGo Connector if you need it.
-</div>
-
-<div class="client_variables_unavailable" markdown="1">
-Automatic configuration of calendars and address books (from step 9 onward) in Thunderbird is only supported if your server administrator has enabled [SOGo Connector](https://mailcow.github.io/mailcow-dockerized-docs/third_party-thunderbird).
-</div>
-
-## Different method of connecting Cal-/CardDAV in Thunderbird with automatic detection of address books and calendars
-
-Instead of using SOGo Connector you can use a combination of
-
-- https://addons.thunderbird.net/de/thunderbird/addon/tbsync/ and
-- https://addons.thunderbird.net/de/thunderbird/addon/dav-4-tbsync/
-
-1. To add your Cal-/CardDAV accounts go to `Tools` and find TbSync
-
-![TbSync](../images/thunderbird-tbsync.png)
-
-2. You can add new accounts via the CalDAV & CardDAV provider:
-
-![TbSync - CalDAV & CardDAV Provider](../images/thunderbird-tbsync-caldav.png)
-
-3. Choose "Automatic Configuration". Use your mail address as account and username. Use your mail password as DAV password. The server URL is your MAILCOW_HOSTNAME (specifying any protocol is not necessary, just enter the full domain).
-
-4. Now tick the checkbox for "Enable and synchronize this account" in the synchronization status tab:
-
-![TbSync - Enable](../images/thunderbird-tbsync-enable.png)
-
-5. Several available resources should appear in the same window area now. Tick all checkboxes of the resources (address books and calendars) that you want to sync. Choose a synchronization period (in minutes) in the same window area before clicking on "Synchronize now". If you leave the sync at "0" it will only sync manually so choose at least 30 minutes for periodic synchronization.
-
-If you want to manually synchronize you can find this option under "Account actions" - the dropdown-menu where you added the Cal-/CardDAV account (step 2).

docs/clients.js

@@ -1,7 +1,7 @@
 if (window.location.href.indexOf('/client/') >= 0) {
     window.window.addEventListener('load', function () {
         function setCookie(name, value) {
-            document.cookie = encodeURIComponent(name) + "=" + encodeURIComponent(value) + "; path=/";
+            sessionStorage.setItem(name, value);
         }
 
         function getParameterByName(name) {
@@ -39,18 +39,7 @@ if (window.location.href.indexOf('/client/') >= 0) {
 if (window.location.href.indexOf('/client') >= 0) {
     window.window.addEventListener('load', function () {
         function getCookie(cn) {
-            var fixedcn = encodeURIComponent(cn);
+            return sessionStorage.getItem(cn);
-            var cs = document.cookie.split(';');
-            for (var i = 0; i < cs.length; i++) {
-                var c = cs[i];
-                while (c.charAt(0) == ' ') {
-                    c = c.substring(1);
-                }
-                if (c.indexOf(fixedcn + "=") == 0) {
-                    return decodeURIComponent(c.substring(cn.length + 1, c.length));
-                }
-            }
-            return "";
         }
 
         /* Hide variable fields if no values are available */

docs/debug-asan_rspamd.md

@@ -0,0 +1,27 @@
+A quick guide to deeply analyze a malfunctioning Rspamd.
+
+```
+docker-compose exec rspamd-mailcow bash
+
+if ! grep -qi 'apt-stable-asan' /etc/apt/sources.list.d/rspamd.list; then
+  sed -i 's/apt-stable/apt-stable-asan/i' /etc/apt/sources.list.d/rspamd.list
+fi
+
+apt-get update ; apt-get upgrade rspamd
+
+nano /docker-entrypoint.sh
+
+# Before "exec "$@"" add the following lines:
+
+export G_SLICE=always-malloc
+export ASAN_OPTIONS=new_delete_type_mismatch=0:detect_leaks=1:detect_odr_violation=0:log_path=/tmp/rspamd-asan:quarantine_size_mb=2048:malloc_context_size=8:fast_unwind_on_malloc=0
+
+```
+
+Restart Rspamd: `docker-compose restart rspamd-mailcow`
+
+Your memory consumption will increase by a lot, it will also steadily grow, which is not related to a possible memory leak you are looking for.
+
+Leave the container running for a few minutes, hours or days (it should match the time you usually wait for the leak to "happen") and restart it: `docker-compose restart rspamd-mailcow`.
+
+Now enter the container by running `docker-compose exec rspamd-mailcow bash`, change the directory to /tmp and copy the asan Files to your desired location or upload them via termbin.com (`cat /tmp/rspamd-asan.* | nc termbin.com 9999`).

docs/debug-common_problems.md

@@ -60,7 +60,7 @@ Docker and iptables-based firewalls sometimes create conflicting rules, so disab
 
 If you experience connection problems from home, please check your ISP router's firewall too, some of them block mail traffic on the *SMTP* (587) or *SMTPS* (465) ports. It could also be, that your ISP is blocking the ports for *SUBMISSION* (25).
 
-While Linux users can chose from a variety of tools[^1] to check if a port is open, the Windows user has only the command `telnet host port` available by default (and it has to be activated since Windows Vista).
+While Linux users can chose from a variety of tools[^1] to check if a port is open, the Windows user has only the PowerShell command `Test-NetConnection -ComputerName host -Port port` available by default.
 
 To enable telnet on a Windows after Vista please check this [guide](https://social.technet.microsoft.com/wiki/contents/articles/910.windows-7-enabling-telnet-client.aspx) or enter the following command in an terminal **with administrator privileges**:
 

docs/debug-mysql_aria.md

@@ -0,0 +1,22 @@
+## MariaDB: Aria recovery after crash
+
+If your server crashed and MariaDB logs an error similar to `[ERROR] mysqld: Aria recovery failed. Please run aria_chk -r on all Aria tables (*.MAI) and delete all aria_log.######## files` you may want to try the following to recover the database to a healthy state:
+
+Start the stack and wait until mysql-mailcow begins to report a restarting state. Check by running `docker-compose ps`.
+
+Now run the following commands:
+
+```
+# Stop the stack, don't run "down"
+docker-compose stop
+# Run a bash in the stopped container as user mysql
+docker-compose run --rm --entrypoint '/bin/sh -c "gosu mysql bash"' mysql-mailcow
+# cd to the SQL data directory
+cd /var/lib/mysql
+# Run aria_chk
+aria_chk --check --force */*.MAI
+# Delete aria log files
+rm aria_log.*
+```
+
+Now run `docker-compose down` followed by `docker-compose up -d`.

docs/debug-reset_pw.md

@@ -1,6 +1,6 @@
 ## mailcow Admin Account
 
-Reset mailcow admin to `admin:moohoo`. Older mailcow: dockerized installations may find `mailcow-reset-admin.sh` in their mailcow root directory (mailcow_path).
+Resets the mailcow admin account to a random password. Older mailcow: dockerized installations may find the `mailcow-reset-admin.sh` script in their mailcow root directory (mailcow_path).
 
 ```
 cd mailcow_path
@@ -77,9 +77,17 @@ MariaDB [(none)]> FLUSH PRIVILEGES;
 
 ## Remove Two-Factor Authentication
 
+### For mailcow WebUI:
+
 This works similar to resetting a MySQL password, now we do it from the host without connecting to the MySQL CLI:
 
 ```
 source mailcow.conf
 docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DELETE FROM tfa WHERE username='YOUR_USERNAME';"
 ```
+
+### For SOGo:
+
+```
+docker-compose exec -u sogo sogo-mailcow sogo-tool user-preferences set defaults user@example.com SOGoGoogleAuthenticatorEnabled '{"SOGoGoogleAuthenticatorEnabled":0}'
+```

docs/debug-reset_tls.md

@@ -0,0 +1,17 @@
+In case you encounter problems with your certificate, key or Let's Encrypt account, please try to reset the TLS assets:
+
+```
+source mailcow.conf
+docker-compose down
+rm -rf data/assets/ssl
+mkdir data/assets/ssl
+openssl req -x509 -newkey rsa:4096 -keyout data/assets/ssl-example/key.pem -out data/assets/ssl-example/cert.pem -days 365 -subj "/C=DE/ST=NRW/L=Willich/O=mailcow/OU=mailcow/CN=${MAILCOW_HOSTNAME}" -sha256 -nodes
+cp -n -d data/assets/ssl-example/*.pem data/assets/ssl/
+docker-compose up -d
+```
+
+This will stop mailcow, source the variables we need, create a self-signed certificate and start mailcow.
+
+If you use Let's Encrypt you should be careful as you will create a new account and a new set of certificates. You will run into a ratelimit sooner or later.
+
+Please also note that previous TLSA records will be invalid.

docs/debug-rm_volumes.md

@@ -1,6 +1,6 @@
 You may want to remove a set of persistent data to resolve a conflict or to start over.
 
-`mailcowdockerized` can vary and depends on your compose project name (if it's unchanged, `mailcowdockerized` is the correct value). If you are unsure about volume names, run `docker volumes ls` for a full list.
+`mailcowdockerized` can vary and depends on your compose project name (if it's unchanged, `mailcowdockerized` is the correct value). If you are unsure about volume names, run `docker volume ls` for a full list.
 
 Delete a single volume:
 

docs/download/build-thunderbird-plugins.sh

@@ -1,60 +0,0 @@
-#!/bin/bash
-
-set -e
-
-MAILHOST=$1
-if [ "$MAILHOST" = "" ]; then
-	echo "Usage: echo example.com example.org | $0 mailcow.example.com"
-	exit 1
-fi
-
-cd $(dirname $0)
-
-wget -O connector.tar.gz https://github.com/inverse-inc/sogo-connector/archive/sogo-connector-68.0.1.tar.gz
-
-mkdir -p connector
-tar --strip-components=1 -C connector -xf connector.tar.gz
-
-# build custom connector
-while read DOMAINS; do
-	for DOMAIN in $DOMAINS; do
-		echo "Building SOGo Connector for $DOMAIN hosted on $MAILHOST"
-		cd connector
-		mkdir -p custom/${DOMAIN}
-		cp -r custom/sogo-demo/* custom/${DOMAIN}/
-		sed -i "s/http:\/\/sogo-demo\.inverse\.ca/https:\/\/${MAILHOST}/g" custom/${DOMAIN}/chrome/content/sogo-connector/global/extensions.rdf
-		sed -i "s/plugins\/updates\.php[?]/thunderbird-plugins.php?domain=${DOMAIN}\&/g" custom/${DOMAIN}/chrome/content/sogo-connector/global/extensions.rdf
-		echo > custom/${DOMAIN}/defaults/preferences/site.js
-		echo 'pref("sogo-connector.autocomplete.server.urlid", "'${DOMAIN}'");' > custom/${DOMAIN}/defaults/preferences/site.js
-		echo 'pref("mail.collect_email_address_outgoing", false);' >> custom/${DOMAIN}/defaults/preferences/site.js
-		#sed -i 's/<\/Seq>/<li><Description em:id="sieve@mozdev.org" em:name="Sieve"\/><\/li><li><Description em:id="imap-acl@sirphreak.com" em:name="Imap-ACL-Extension"\/><\/li><\/Seq>/g' custom/${DOMAIN}/chrome/content/sogo-connector/global/extensions.rdf
-		make build=${DOMAIN}
-		CONNECTOR_VER=$(grep em:version install.rdf | awk -F '"' '{print $2}')
-		CONNECTOR_MIN_VER=$(grep em:minVersion install.rdf | grep -Eo '[0-9\.]+' | head -n 1)
-		mv sogo-connector-*.xpi ../sogo-connector-${CONNECTOR_VER}-${DOMAIN}.xpi
-		cd ..
-	done
-done
-
-# if you add any other plugins below, you need to add them into extensions.rdf as in the line commented out above
-
-# # download Sieve plugin
-# SIEVE_RELEASES=$(wget --header="Accept: application/vnd.github.v3+json" -qO - https://api.github.com/repos/thsmi/sieve/releases)
-# SIEVE_VER=$(echo "$SIEVE_RELEASES" | grep -o '"tag_name": *"[^"]*"' | head -n 1 | awk -F '"' '{print $4}')
-# SIEVE_URL=$(echo "$SIEVE_RELEASES" | grep -o '"browser_download_url": *"[^"]*"' | head -n 1 | awk -F '"' '{print $4}')
-# wget -O sieve-${SIEVE_VER}.xpi ${SIEVE_URL}
-# unset SIEVE_RELEASES
-#
-# # download ACL plugin
-# IMAP_ACL_RELEASES=$(wget -qO - 'https://addons.thunderbird.net/en-US/thunderbird/addon/imap-acl-extension/')
-# IMAP_ACL_VER=$(echo "$IMAP_ACL_RELEASES" | grep version-number | awk -F '[<>]' '{print $3}' | head -n 1)
-# IMAP_ACL_URL=$(echo "$IMAP_ACL_RELEASES" | grep -o 'https://.*\.xpi' | head -n 1)
-# wget -O imap_acl_extension-${IMAP_ACL_VER}-tb.xpi ${IMAP_ACL_URL}
-# unset IMAP_ACL_RELEASES
-
-# update version file
-echo "sogo-connector@inverse.ca;${CONNECTOR_VER};sogo-connector-${CONNECTOR_VER}-__DOMAIN__.xpi;${CONNECTOR_MIN_VER}" > version.csv
-# echo "sieve@mozdev.org;${SIEVE_VER};sieve-${SIEVE_VER}.xpi" >> version.csv
-# echo "imap-acl@sirphreak.com;${IMAP_ACL_VER};imap_acl_extension-${IMAP_ACL_VER}-tb.xpi" >> version.csv
-
-rm -rf connector *.tar.gz

docs/download/thunderbird-plugins.php

@@ -1,118 +0,0 @@
-<?php
-/* updates.php - this file is part of SOGo
- *
- *  Copyright (C) 2006-2014 Inverse inc.
- *
- * This file is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2, or (at your option)
- * any later version.
- *
- * This file is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; see the file COPYING.  If not, write to
- * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
- */
-
-/* This script handles the automatic propagation of extensions pertaining to a
-   SOGo site. It requires PHP 4.1.0 or later. */
-$plugin_dir = 'thunderbird-plugins';
-chdir($plugin_dir);
-$plugins = array();
-
-if (file_exists('version.csv'))
-{
-  $fh = fopen('version.csv', 'r');
-  if ($fh)
-  {
-    while (($row = fgetcsv($fh, 1000, ';')) !== FALSE)
-    {
-      $plugins[$row[0]] = array(
-        'application' => 'thunderbird',
-        'version' => $row[1],
-        'filename' => str_replace('__DOMAIN__', $_GET["domain"], $row[2]),
-      );
-      if (count($row) > 3)
-      {
-          $plugins[$row[0]]['min_version'] = $row[3];
-      }
-      else
-      {
-          $plugins[$row[0]]['min_version'] = '30.0';
-      }
-    }
-    fclose($fh);
-  }
-}
-
-$applications
-= array( "thunderbird" => "<em:id>{3550f703-e582-4d05-9a08-453d09bdfdc6}</em:id>
-                <em:minVersion>__MIN_VERSION__</em:minVersion>
-                <em:maxVersion>99.*</em:maxVersion>" );
-
-$pluginname = $_GET["plugin"];
-$plugin =& $plugins[$pluginname];
-$application =& $applications[$plugin["application"]];
-
-if ( $plugin ) {
-  $platform = $_GET["platform"];
-  if ( $platform
-       && file_exists( $platform . "/" . $plugin["filename"] ) ) {
-    $plugin["filename"] = $platform . "/" . $plugin["filename"];
-  }
-  elseif ( !file_exists( $plugin["filename"] ) ) {
-    $plugin = false;
-  }
-}
-
-if (preg_match('/Thunderbird\/([0-9\.]+)/', $_SERVER['HTTP_USER_AGENT'], $client_ver))
-{
-	$client_ver = $client_ver[1];
-}
-else
-{
-	$client_ver = $plugin['min_version'];
-}
-
-if ( $plugin ) {
-  if (version_compare($client_ver, $plugin['min_version'], '<')) {
-    header("Content-type: text/plain; charset=utf-8", true, 404);
-    echo( 'Plugin not compatible with client version' );
-    exit;
-  }
-  header("Content-type: text/xml; charset=utf-8");
-  echo ('<?xml version="1.0"?>' . "\n");
-?>
-<!DOCTYPE RDF>
-<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-  xmlns:em="http://www.mozilla.org/2004/em-rdf#">
-  <Description about="urn:mozilla:extension:<?php echo $pluginname ?>">
-    <em:updates>
-      <Seq>
-        <li>
-          <Description>
-            <em:version><?php echo $plugin["version"] ?></em:version>
-            <em:targetApplication>
-              <Description>
-                <?php echo str_replace('__MIN_VERSION__', $plugin['min_version'], $applications[$plugin["application"]]); ?>
-                
-                <em:updateLink><?php echo 'https://' . $_SERVER['HTTP_HOST'] . dirname($_SERVER['PHP_SELF']) . '/' .  $plugin_dir . '/' . $plugin["filename"] ?></em:updateLink>
-              </Description>
-            </em:targetApplication>
-          </Description>
-        </li>
-      </Seq>
-    </em:updates>
-  </Description>
-</RDF>
-<?php
-} else {
-  header("Content-type: text/plain; charset=utf-8", true, 404);
-  echo( 'Plugin not found' );
-}
-?>

docs/firststeps-disable_ipv6.md

@@ -38,6 +38,7 @@ version: '2.1'
 services:
 
     ipv6nat-mailcow:
+      image: bash:latest
       restart: "no"
       entrypoint: ["echo", "ipv6nat disabled in compose.override.yml"]
 ```
@@ -72,6 +73,7 @@ Create `data/conf/postfix/extra.cf` and set `smtp_address_preference` to `ipv4`:
 
 ```
 smtp_address_preference = ipv4
+inet_protocols = ipv4
 ```
 
 Restart Postfix:

docs/firststeps-dmarc_reporting.md

@@ -0,0 +1,125 @@
+DMARC Reporting done via Rspamd DMARC Module.
+
+Rspamd documentation can be found here: https://rspamd.com/doc/modules/dmarc.html
+
+**Important:**
+
+1. Change `example.com`, `mail.example.com` and `Example` to reflect your setup
+
+2. DMARC reporting requires additional attention, especially over the first few days
+
+3. All receiving domains hosted on mailcow send from one reporting domain. It is recommended to use the parent domain of your `MAILCOW_HOSTNAME`:
+    - If your `MAILCOW_HOSTNAME` is `mail.example.com` change the following config to `domain = "example.com";`
+    - Set `email` equally, e.g. `email = "noreply-dmarc@example.com";`
+
+4. It is optional but recommended to create an email user `noreply-dmarc` in mailcow to handle bounces.
+
+## Enable DMARC reporting
+
+Create the file `data/conf/rspamd/local.d/dmarc.conf` and set the following content:
+
+```
+reporting {
+    enabled = true;
+    email = 'noreply-dmarc@example.com';
+    domain = 'example.com';
+    org_name = 'Example';
+    helo = 'rspamd';
+    smtp = 'postfix';
+    smtp_port = 25;
+    from_name = 'Example DMARC Report';
+    msgid_from = 'rspamd.mail.example.com';
+    max_entries = 2k;
+    keys_expire = 2d;
+}
+```
+
+Create or modify `docker-compose.override.yml` in the mailcow-dockerized base directory:
+
+```
+version: '2.1'
+
+services:
+  rspamd-mailcow:
+    environment:
+      - MASTER=${MASTER:-y}
+    labels:
+      ofelia.enabled: "true"
+      ofelia.job-exec.rspamd_dmarc_reporting.schedule: "@every 24h"
+      ofelia.job-exec.rspamd_dmarc_reporting.command: "/bin/bash -c \"[[ $${MASTER} == y ]] && /usr/bin/rspamadm dmarc_report > /var/lib/rspamd/dmarc_reports_last_log 2>&1 || exit 0\""
+  ofelia-mailcow:
+    depends_on:
+      - rspamd-mailcow
+```
+
+Run `docker-compose up -d`
+
+## Send a copy reports to yourself
+
+To receive a hidden copy of reports generated by Rspamd you can set a `bcc_addrs` list in the `reporting` config section of `data/conf/rspamd/local.d/dmarc.conf`:
+
+```
+reporting {
+    enabled = true;
+    email = 'noreply-dmarc@example.com';
+    bcc_addrs = ["noreply-dmarc@example.com","parsedmarc@example.com"];
+[...]
+```
+
+Rspamd will load changes in real time, so you won't need to restart the container at this point.
+
+This can be useful if you...
+
+- ...want to check that your DMARC reports are sent correctly and authenticated.
+- ...want to analyze your own reports to get statistics, i.e. to use with ParseDMARC or other analytic systems.
+
+## Troubleshooting
+
+Check when the report schedule last ran:
+
+```
+docker-compose exec rspamd-mailcow date -r /var/lib/rspamd/dmarc_reports_last_log
+```
+
+See the latest report output:
+
+```
+docker-compose exec rspamd-mailcow cat /var/lib/rspamd/dmarc_reports_last_log
+```
+
+Manually trigger a DMARC report:
+
+```
+docker-compose exec rspamd-mailcow rspamadm dmarc_report
+```
+
+Validate that Rspamd has recorded data in Redis:
+
+```
+docker-compose exec redis-mailcow redis-cli KEYS 'dmarc;*'
+docker-compose exec redis-mailcow redis-cli HGETALL "dmarc;example.com;20211231"
+```
+
+## Change DMARC reporting frequency
+
+In the example above reports are sent once every 24 hours.
+
+Olefia schedule has same implementation as `cron` in Go, supported syntax described at [cron Documentation](https://pkg.go.dev/github.com/robfig/cron)
+
+To change schedule:
+
+1. Edit `docker-compose.override.yml` and a djust `ofelia.job-exec.rspamd_dmarc_reporting.schedule: "@every 24h"` to a desired value, for example to `"@midnight"`
+
+2. Run `docker-compose up -d`
+
+3. Run `docker-compose restart ofelia-mailcow`
+
+## Disable DMARC Reporting
+
+To disable reporting:
+
+1. Set `enabled` to `false` in `data/conf/rspamd/local.d/dmarc.conf`
+
+2. Revert changes done in `docker-compose.override.yml` to `rspamd-mailcow` and `ofelia-mailcow`
+
+3. Run `docker-compose up -d`

docs/firststeps-ip_bindings.md

@@ -8,15 +8,16 @@ To adjust one or multiple IPv4 bindings, open `mailcow.conf` and edit one, multi
 ```
 # For technical reasons, http bindings are a bit different from other service bindings.
 # You will find the following variables, separated by a bind address and its port:
+# Example: HTTP_BIND=1.2.3.4
 
 HTTP_PORT=80
-HTTP_BIND=0.0.0.0
+HTTP_BIND=
 HTTPS_PORT=443
-HTTPS_BIND=0.0.0.0
+HTTPS_BIND=
 
 # Other services are bound by using the following format:
-# SMTP_PORT=25 equals to SMTP_PORT=0.0.0.0:25
 # SMTP_PORT=1.2.3.4:25 will bind SMTP to the IP 1.2.3.4 on port 25
+# Important! Specifying an IPv4 address will skip all IPv6 bindings since Docker 20.x.
 # doveadm, SQL as well as Solr are bound to local ports only, please do not change that, unless you know what you are doing.
 
 SMTP_PORT=25

docs/firststeps-logging.md

@@ -26,6 +26,8 @@ Redis keys will only hold logs from applications and filter out system messages
 
 ### Logging drivers
 
+#### Via docker-compose.override.yml
+
 Here is the good news: Since Docker has some great logging drivers, you can integrate mailcow: dockerized into your existing logging environment with ease.
 
 Create a `docker-compose.override.yml` and add, for example, this block to use the "gelf" logging plugin for `postfix-mailcow`:
@@ -40,7 +42,46 @@ services:
         gelf-address: "udp://graylog:12201"
 ```
 
-If you want to change the logging driver globally, edit Dockers daemon configuration file `/etc/docker/daemon.json` and restart the Docker service:
+Another example for **Syslog**:
+
+```
+version: '2.1'
+services:
+
+  postfix-mailcow: # or any other
+    logging:
+      driver: "syslog"
+      options:
+        syslog-address: "udp://127.0.0.1:514"
+        syslog-facility: "local3"
+
+  dovecot-mailcow: # or any other
+    logging:
+      driver: "syslog"
+      options:
+        syslog-address: "udp://127.0.0.1:514"
+        syslog-facility: "local3"
+
+  rspamd-mailcow: # or any other
+    logging:
+      driver: "syslog"
+      options:
+        syslog-address: "udp://127.0.0.1:514"
+        syslog-facility: "local3"
+
+# For Rsyslog only:
+# To move local3 input to /var/log/mailcow.log and stop processing, create a file "/etc/rsyslog.d/docker.conf":
+
+local3.*        /var/log/mailcow.logs
+& ~
+
+# Restart rsyslog afterwards.
+
+```
+
+#### via daemon.json (globally)
+
+If you want to **change the logging driver globally**, edit Dockers daemon configuration file `/etc/docker/daemon.json` and restart the Docker service:
 
 ```
 {

docs/firststeps-rfc-1918.md

@@ -1,11 +0,0 @@
-Per default, mailcow considers all private RFC1918 networks (i.e. 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) as trusted. Though it is reasonable in most cases, you may want to restrict this setting under certain circumstances. In particular, if you are using some kind of reverse proxy for SMTP TCP ports. If your reverse proxy host is located in a private net, mailcow will consider all traffic from it as trusted, which may result in an open relay. 
-
-To change this behaviour override the default value of `mynetworks` parameter through the `data/conf/postfix/extra.cf` configuration file.
-
-**Important**: Do **not** remove the networks listed as `IPV4_NETWORK` and `IPV6_NETWORK` in your mailcow.conf. You should also keep local addresses.
-
-The default values for those variables - `172.22.1.0/24` and `fd4d:6169:6c63:6f77::/64` - would result in the following, minimal configuration:
-
-```
-mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 [fe80::]/10 172.22.1.0/24 [fd4d:6169:6c63:6f77::]/64
-```

docs/firststeps-rp.md

@@ -15,6 +15,11 @@ This will also change the bindings inside the Nginx container! This is important
 
 Recreate affected containers by running `docker-compose up -d`.
 
+**Important information, please read them carefully!**
+
+!!! info
+    If you plan to use a reverse proxy and want to use another server name that is **not** MAILCOW_HOSTNAME, you need to read **Adding additional server names for mailcow UI** at the bottom of this page.
+
 !!! warning
     Make sure you run `generate_config.sh` before you enable any site configuration examples below.
     The script `generate_config.sh` copies snake-oil certificates to the correct location, so the services will not fail to start due to missing files.
@@ -50,7 +55,7 @@ Let's Encrypt will follow our rewrite, certificate requests in mailcow will work
   ServerAlias autoconfig.*
   RewriteEngine on
 
-  RewriteCond %{HTTPS} !=on
+  RewriteCond %{HTTPS} off
   RewriteRule ^/?(.*) https://%{HTTP_HOST}/$1 [R=301,L]
 
   ProxyPass / http://127.0.0.1:8080/
@@ -176,7 +181,7 @@ For this we'll have to set `SKIP_LETS_ENCRYPT=y` on our `mailcow.conf`, and run
 
 Then we'll create a `docker-compose.override.yml` file in order to override the main `docker-compose.yml` found in your mailcow root folder. 
 
-```
+```yaml
 version: '2.1'
 
 services:
@@ -195,10 +200,10 @@ services:
         - traefik.http.routers.moo.tls.certresolver=le
         # Creates a service called "moo" for the container, and specifies which internal port of the container
         #   should traefik route the incoming data to.
-        - traefik.http.services.moo.loadbalancer.server.port=80
+        - traefik.http.services.moo.loadbalancer.server.port=${HTTP_PORT}
         # Specifies which entrypoint (external port) should traefik listen to, for this container.
         #   websecure being port 443, check the traefik.toml file liked above.
-        - traefik.http.routers.moo.entrypoints=secure
+        - traefik.http.routers.moo.entrypoints=websecure
         # Make sure traefik uses the web network, not the mailcowdockerized_mailcow-network
         - traefik.docker.network=web
 
@@ -248,3 +253,13 @@ dovecot_c=$(docker ps -qaf name=dovecot-mailcow)
 nginx_c=$(docker ps -qaf name=nginx-mailcow)
 docker restart ${postfix_c} ${dovecot_c} ${nginx_c}
 ```
+
+### Adding additional server names for mailcow UI
+
+If you plan to use a server name that is not `MAILCOW_HOSTNAME` in your reverse proxy, make sure to populate that name in mailcow.conf via `ADDITIONAL_SERVER_NAMES` first. Names must be separated by commas and **must not** contain spaces. If you skip this step, mailcow may respond to your reverse proxy with an incorrect site.
+
+```
+ADDITIONAL_SERVER_NAMES=webmail.domain.tld,other.example.tld
+```
+
+Run `docker-compose up -d` to apply.

docs/firststeps-rspamd_ui.md

@@ -1,7 +1,7 @@
 [Rspamd](https://rspamd.com/) is an easy to use spam filtering tool presently installed with mailcow.
 
 1. Go to the mailcow web admin interface
-2. Navigate to the Access tab. (Configuration > Administration > Access)
+2. Navigate to the Access tab. (Configuration > Configuration & Details > Access)
 3. Modify the Rspamd UI password
 4. Go to https://${MAILCOW_HOSTNAME}/rspamd in a browser and log in!
 

docs/firststeps-ssl.md

@@ -31,6 +31,17 @@ A wildcard name like `smtp.*` will try to obtain a smtp.DOMAIN_NAME SAN for each
 
 Run `docker-compose up -d` to recreate affected containers automatically.
 
+!!! info
+    Using names other name `MAILCOW_HOSTNAME` to access the mailcow UI may need further configuration.
+
+If you plan to use a server name that is not `MAILCOW_HOSTNAME` to access the mailcow UI (for example by adding `mail.*` to `ADDITIONAL_SAN` make sure to populate that name in mailcow.conf via `ADDITIONAL_SERVER_NAMES`. Names must be separated by commas and **must not** contain spaces. If you skip this step, mailcow may respond with an incorrect site.
+
+```
+ADDITIONAL_SERVER_NAMES=webmail.domain.tld,other.example.tld
+```
+
+Run `docker-compose up -d` to apply.
+
 ### Force renewal
 
 To force a renewal, you need to create a file named `force_renew` and restart the `acme-mailcow` container:

docs/i_u_m_install.md

@@ -1,9 +1,4 @@
-!!! warning
+You need Docker (a version >= `20.10.2` is required) and Docker Compose (a version `<= 2.0` is required).
-    Make sure you've read ["Prepare Your System"](https://mailcow.github.io/mailcow-dockerized-docs/prerequisite-system) before proceeding!
-    **Do not** use CentOS 8 with Centos 7 Docker packages. You may create an open relay.
-
-
-You need Docker and Docker Compose.
 
 **1\.** Learn how to install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/).
 
@@ -13,14 +8,13 @@ Quick installation for most operation systems:
 ```
 curl -sSL https://get.docker.com/ | CHANNEL=stable sh
 # After the installation process is finished, you may need to enable the service and make sure it is started (e.g. CentOS 7)
-systemctl enable docker.service
+systemctl enable --now docker
-systemctl start docker.service
 ```
 
 - Docker-Compose
 
 !!! warning
-    **mailcow requires the latest version of docker-compose.** It is highly recommended to use the commands below to install `docker-compose`. Package managers (e.g. `apt`, `yum`) **likely won't** give you the latest version.
+    **mailcow requires the latest version of docker-compose v1.** It is highly recommended to use the commands below to install `docker-compose`. Package managers (e.g. `apt`, `yum`) **likely won't** give you the correct version.
     _Note: This command downloads docker-compose from the official Docker Github repository and is a safe method. The snippet will determine the latest supported version by mailcow. In almost all cases this is the latest version available (exceptions are broken releases or major changes not yet supported by mailcow)._
 
 ```

docs/i_u_m_update.md

@@ -52,7 +52,7 @@ dacd4fb9b51e9e1c8a37d84485b92ffaf6c59353 Before update on 2020-08-07_13_31_31
 
 Run `git diff 22cd00b5e28893ef9ddef3c2b5436453cc5223ab` to see what changed.
 
-### Can I role back?
+### Can I roll back?
 
 Yes.
 
@@ -66,6 +66,10 @@ docker-compose pull
 docker-compose up -d
 ```
 
+### Hooks
+
+You can hook into the update mechanism by adding scripts called `pre_commit_hook.sh` and `post_commit_hook.sh` to your mailcows root directory. See [this](./u_e-update-hooks.md) for more details.
+
 ## Footnotes
 
 - There is no release cycle regarding updates.

docs/index.md

@@ -64,29 +64,33 @@ The integrated **mailcow UI** allows administrative work on your mail server ins
 mailcow: dockerized comes with multiple containers linked in one bridged network.
 Each container represents a single application.
 
-- [Dovecot](https://www.dovecot.org/)
+- [ACME](https://letsencrypt.org/)
 - [ClamAV](https://www.clamav.net/) (optional)
-- [Solr](http://lucene.apache.org/solr/) (optional)
+- [Dovecot](https://www.dovecot.org/)
-- [Oletools](https://github.com/decalage2/oletools) via [Olefy](https://github.com/HeinleinSupport/olefy)
-- [Memcached](https://www.memcached.org/)
-- [Redis](https://redis.io/)
 - [MariaDB](https://mariadb.org/)
-- [Unbound](https://unbound.net/)
+- [Memcached](https://www.memcached.org/)
+- [Netfilter](https://www.netfilter.org/) (Fail2ban-like integration by [@mkuron](https://github.com/mkuron))
+- [Nginx](https://nginx.org/)
+- [Oletools](https://github.com/decalage2/oletools) via [Olefy](https://github.com/HeinleinSupport/olefy)
 - [PHP](https://php.net/)
 - [Postfix](http://www.postfix.org/)
-- [ACME](https://letsencrypt.org/)
+- [Redis](https://redis.io/)
-- [Nginx](https://nginx.org/)
 - [Rspamd](https://www.rspamd.com/)
 - [SOGo](https://sogo.nu/)
-- [Netfilter](https://www.netfilter.org/) (Fail2ban-like integration by [@mkuron](https://github.com/mkuron))
+- [Solr](https://solr.apache.org/) (optional)
+- [Unbound](https://unbound.net/)
 - A Watchdog to provide basic monitoring
 
 **Docker volumes** to keep dynamic data - take care of them!
 
-- vmail-vol-1
-- solr-vol-1
-- redis-vol-1
-- mysql-vol-1
-- rspamd-vol-1
-- postfix-vol-1
 - crypt-vol-1
+- mysql-socket-vol-1
+- mysql-vol-1
+- postfix-vol-1
+- redis-vol-1
+- rspamd-vol-1
+- sogo-userdata-backup-vol-1
+- sogo-web-vol-1
+- solr-vol-1
+- vmail-index-vol-1
+- vmail-vol-1

docs/model-passwd.md

@@ -0,0 +1,49 @@
+## Fully supported hashing methods
+
+The most current mailcow fully supports the following hashing methods.
+The default hashing method is written in bold:
+
+- **BLF-CRYPT**
+- SSHA
+- SSHA256
+- SSHA512
+
+The methods above can be used in `mailcow.conf` as `MAILCOW_PASS_SCHEME` value.
+
+## Read-only hashing methods
+
+The following methods are supported **read only**.
+If you plan to use SOGo (as per default), you need a SOGo compatible hashing method. Please see the note at the bottom of this page how to update the view if necessary.
+With SOGo disabled, all hashing methods below will be able to be read by mailcow and Dovecot.
+
+- ARGON2I (SOGo compatible)
+- ARGON2ID (SOGo compatible)
+- CLEAR
+- CLEARTEXT
+- CRYPT (SOGo compatible)
+- DES-CRYPT
+- LDAP-MD5 (SOGo compatible)
+- MD5 (SOGo compatible)
+- MD5-CRYPT (SOGo compatible)
+- PBKDF2 (SOGo compatible)
+- PLAIN (SOGo compatible)
+- PLAIN-MD4
+- PLAIN-MD5
+- PLAIN-TRUNC
+- SHA (SOGo compatible)
+- SHA1 (SOGo compatible)
+- SHA256 (SOGo compatible)
+- SHA256-CRYPT (SOGo compatible)
+- SHA512 (SOGo compatible)
+- SHA512-CRYPT (SOGo compatible)
+- SMD5 (SOGo compatible)
+
+That means mailcow is able to verify users with a hash like `{MD5}1a1dc91c907325c69271ddf0c944bc72` from the database.
+
+The value of `MAILCOW_PASS_SCHEME` will _always_ be used to encrypt new passwords.
+
+---
+
+> I changed the password hashes in the "mailbox" SQL table and cannot login.
+
+A "view" needs to be updated. You can trigger this by restarting sogo-mailcow: `docker-compose restart sogo-mailcow`

docs/prerequisite-dns.md

@@ -23,10 +23,9 @@ This example shows you a set of records for one domain managed by mailcow. Each
 ```
 # Name              Type       Value
 mail                IN A       1.2.3.4
-autodiscover        IN CNAME   mail
+autodiscover        IN CNAME   mail.example.org. (your ${MAILCOW_HOSTNAME})
-autoconfig          IN CNAME   mail
+autoconfig          IN CNAME   mail.example.org. (your ${MAILCOW_HOSTNAME})
-
+@                   IN MX 10   mail.example.org. (your ${MAILCOW_HOSTNAME})
-@                   IN MX 10   mail
 ```
 
 ## DKIM, SPF and DMARC
@@ -35,7 +34,7 @@ In the example DNS zone file snippet below, a simple **SPF** TXT record is used
 
 ```
 # Name              Type       Value
-@                   IN TXT     "v=spf1 mx -all"
+@                   IN TXT     "v=spf1 mx a -all"
 ```
 
 It is highly recommended to create a **DKIM** TXT record in your mailcow UI and set the corresponding TXT record in your DNS records. Please refer to [OpenDKIM](http://www.opendkim.org) for further reading.
@@ -58,18 +57,18 @@ _dmarc              IN TXT     "v=DMARC1; p=reject; rua=mailto:mailauth-reports@
 
 ```
 # Name              Type       Priority Weight Port    Value
-_imap._tcp          IN SRV     0        1      143      mail.example.org.
+_autodiscover._tcp  IN SRV     0        1      443      mail.example.org. (your ${MAILCOW_HOSTNAME})
-_imaps._tcp         IN SRV     0        1      993      mail.example.org.
+_caldavs._tcp       IN SRV     0        1      443      mail.example.org. (your ${MAILCOW_HOSTNAME})
-_pop3._tcp          IN SRV     0        1      110      mail.example.org.
-_pop3s._tcp         IN SRV     0        1      995      mail.example.org.
-_submission._tcp    IN SRV     0        1      587      mail.example.org.
-_smtps._tcp         IN SRV     0        1      465      mail.example.org.
-_sieve._tcp         IN SRV     0        1      4190     mail.example.org.
-_autodiscover._tcp  IN SRV     0        1      443      mail.example.org.
-_carddavs._tcp      IN SRV     0        1      443      Mail.example.org.
-_carddavs._tcp      IN TXT                              "path=/SOGo/dav/"
-_caldavs._tcp       IN SRV     0        1      443      mail.example.org.
 _caldavs._tcp       IN TXT                              "path=/SOGo/dav/"
+_carddavs._tcp      IN SRV     0        1      443      mail.example.org. (your ${MAILCOW_HOSTNAME})
+_carddavs._tcp      IN TXT                              "path=/SOGo/dav/"
+_imap._tcp          IN SRV     0        1      143      mail.example.org. (your ${MAILCOW_HOSTNAME})
+_imaps._tcp         IN SRV     0        1      993      mail.example.org. (your ${MAILCOW_HOSTNAME})
+_pop3._tcp          IN SRV     0        1      110      mail.example.org. (your ${MAILCOW_HOSTNAME})
+_pop3s._tcp         IN SRV     0        1      995      mail.example.org. (your ${MAILCOW_HOSTNAME})
+_sieve._tcp         IN SRV     0        1      4190     mail.example.org. (your ${MAILCOW_HOSTNAME})
+_smtps._tcp         IN SRV     0        1      465      mail.example.org. (your ${MAILCOW_HOSTNAME})
+_submission._tcp    IN SRV     0        1      587      mail.example.org. (your ${MAILCOW_HOSTNAME})
 ```
 
 ## Testing
@@ -85,11 +84,13 @@ Here are some tools you can use to verify your DNS configuration:
 ## Misc
 
 ### Optional DMARC Statistics
-If you are interested in statistics, you can additionally register with some of the many below DMARC statistic services, or self-host your own.
 
-**NOTE:** It is worth considering that if you request DMARC statistic reports to your mailcow server, if there are issues with that domain you may not get accurate results. You can consider using an alternative email domain for recieving DMARC reports.
+If you are interested in statistics, you can additionally register with some of the many below DMARC statistic services - or self-host your own.
 
-It is worth mentioning, that the following suggestions are not a comprehensive list of all services and tools avaialble, but only a small few of the many choices.
+!!! Tip
+It is worth considering that if you request DMARC statistic reports to your mailcow server and your mailcow server is not configured correctly to receive these reports, you may not get accurate and complete results. Please consider using an alternative email domain for receiving DMARC reports.
+
+It is worth mentioning, that the following suggestions are not a comprehensive list of all services and tools available, but only a small few of the many choices.
 
 - [Postmaster Tool](https://gmail.com/postmaster)
 - [parsedmarc](https://github.com/domainaware/parsedmarc) (self-hosted)
@@ -97,18 +98,15 @@ It is worth mentioning, that the following suggestions are not a comprehensive l
 - [Postmark](https://dmarc.postmarkapp.com)
 - [Dmarcian](https://dmarcian.com/)
 
-**NOTE:** The services may provide you with a TXT record, which you would insert into your DNS records as the provider specifies. This record will give you details about spam-classified mails by your domain. However, please ensure to read the providers documentation from the service you choose, as this process may vary and not all providers may use a TXT record.
+!!! Tip
 
-### Email Test for SPF, DKIM and DMARC:
+These services may provide you with a TXT record you need to insert into your DNS records as the provider specifies. Please ensure you read the provider's documentation from the service you choose as this process may vary.
 
-To test send an email to the email below and wait for a reply:
+### Email test for SPF, DKIM and DMARC:
 
-check-auth@verifier.port25.com
+To run a rudimentary email authentication check, send a mail to `check-auth at verifier.port25.com` and wait for a reply. You will find a report similar to the following:
-
-You will get a report back that looks like the following:
 
 ```
-
 ==========================================================
 Summary of Results
 ==========================================================
@@ -123,8 +121,10 @@ Details:
 ==========================================================
 ....
 ```
-The full report will contain more technical details this is just the first section, we found this to be quite usful for testing both outgoing mail and spam scores.
+
+The full report will contain more technical details.
 
 
 ### Fully Qualified Domain Name (FQDN)
-[^1]: A **Fully Qualified Domain Name** (**FQDN**) is the complete (absolute) domain name for a specific computer or host, on the Internet. The FQDN consists of at least three parts divided by a dot: the hostname (myhost), the domain name (mydomain) and the top level domain in short **tld** (com). In the example of `mx.mailcow.email` the hostname would be `mx`, the domain name `mailcow` and the tld `email`.
+
+[^1]: A **Fully Qualified Domain Name** (**FQDN**) is the complete (absolute) domain name for a specific computer or host, on the Internet. The FQDN consists of at least three parts divided by a dot: the hostname, the domain name, and the Top Level Domain (**TLD** for short). In the example of `mx.mailcow.email` the hostname would be `mx`, the domain name `mailcow` and the TLD `email`.

docs/prerequisite-system.md

@@ -2,7 +2,6 @@ Before you run **mailcow: dockerized**, there are a few requirements that you sh
 
 !!! warning
     Do **not** try to install mailcow on a Synology/QNAP device (any NAS), OpenVZ, LXC or other container platforms. KVM, ESX, Hyper-V and other full virtualization platforms are supported.
-    Do **not** use CentOS 8 with Centos 7 Docker packages. You may create an open relay.
 
 !!! info
     - mailcow: dockerized requires [some ports](#default-ports) to be open for incoming connections, so make sure that your firewall is not blocking these.
@@ -12,59 +11,114 @@ Before you run **mailcow: dockerized**, there are a few requirements that you sh
 
 ## Minimum System Resources
 
-**Do not** use OpenVZ or LXC as guests for mailcow.
+**OpenVZ, Virtuozzo and LXC are not supported**.
 
 Please make sure that your system has at least the following resources:
 
-| Resource                | mailcow: dockerized                          |
+| Resource                | mailcow: dockerized                              |
-| ----------------------- | -------------------------------------------- |
+| ----------------------- | ------------------------------------------------ |
-| CPU                     | 1 GHz                                        |
+| CPU                     | 1 GHz                                            |
-| RAM                     | Minimum 4 GiB + Swap                         |
+| RAM                     | **Minimum** 6 GiB + 1 GiB swap (default config)  |
-| Disk                    | 20 GiB (without emails)                      |
+| Disk                    | 20 GiB (without emails)                          |
-| System Type             | x86_64                                       |
+| System Type             | x86_64                                           |
 
-As of today (29th Dec 2019), we recommend using any distribution listed as supported by Docker CE (check https://docs.docker.com/install/). We test on CentOS 7, Debian 9/10 and Ubuntu 18.04.
+We recommend using any distribution listed as supported by Docker CE (check https://docs.docker.com/install/). We test on CentOS 7, Debian 10/11 and Ubuntu 18.04/20.04.
 
-ClamAV and Solr are greedy RAM munchers. You can disable them in `mailcow.conf` by settings SKIP_CLAMD=y and SKIP_SOLR=y.
+ClamAV and Solr can be greedy with RAM. You may disable them in `mailcow.conf` by settings `SKIP_CLAMD=y` and `SKIP_SOLR=y`.
+
+**Info**: We are aware that a pure MTA can run on 128 MiB RAM. mailcow is a full-grown and ready-to-use groupware with many extras making life easier. mailcow comes with a webserver, webmailer, ActiveSync (MS), antivirus, antispam, indexing (Solr), document scanner (Oletools), SQL (MariaDB), Cache (Redis), MDA, MTA, various web services etc.
+
+A single SOGo worker **can** acquire ~350 MiB RAM before it gets purged. The more ActiveSync connections you plan to use, the more RAM you will need. A default configuration spawns 20 workers.
+
+#### Usage examples
+
+A company with 15 phones (EAS enabled) and about 50 concurrent IMAP connections should plan 16 GiB RAM.
+
+6 GiB RAM + 1 GiB swap are fine for most private installations while 8 GiB RAM are recommended for ~5 to 10 users.
+
+We can help to correctly plan your setup as part of our support.
 
 ## Firewall & Ports
 
 Please check if any of mailcow's standard ports are open and not in use by other applications:
 
 ```
-ss -tlpn | grep -E -w '25|80|110|143|443|465|587|993|995|4190'
+ss -tlpn | grep -E -w '25|80|110|143|443|465|587|993|995|4190|5222|5269|5443'
 # or:
-netstat -tulpn | grep -E -w '25|80|110|143|443|465|587|993|995|4190'
+netstat -tulpn | grep -E -w '25|80|110|143|443|465|587|993|995|4190|5222|5269|5443'
 ```
 
 !!! warning
-    There are several problems with running mailcow on a firewalld/ufw enabled system. You should disable it (if possible) and move your ruleset to the DOCKER-USER chain, which is not cleared by a Docker service restart, instead. See [this blog post](https://blog.donnex.net/docker-and-iptables-filtering/) for information about how to use iptables-persistent with the DOCKER-USER chain.
+    There are several problems with running mailcow on a firewalld/ufw enabled system. You should disable it (if possible) and move your ruleset to the DOCKER-USER chain, which is not cleared by a Docker service restart, instead. See [this (blog.donnex.net)](https://blog.donnex.net/docker-and-iptables-filtering/) or [this (unrouted.io)](https://unrouted.io/2017/08/15/docker-firewall/) guide for information about how to use iptables-persistent with the DOCKER-USER chain.
     As mailcow runs dockerized, INPUT rules have no effect on restricting access to mailcow. Use the FORWARD chain instead.
 
-**
-
 If this command returns any results please remove or stop the application running on that port. You may also adjust mailcows ports via the `mailcow.conf` configuration file.
 
 ### Default Ports
 
 If you have a firewall in front of mailcow, please make sure that these ports are open for incoming connections:
 
-| Service             | Protocol | Port   | Container       | Variable                         |
+| Service             | Protocol | Port   | Container         | Variable                         |
-| --------------------|:--------:|:-------|:----------------|----------------------------------|
+| --------------------|:--------:|:-------|:------------------|----------------------------------|
-| Postfix SMTP        | TCP      | 25     | postfix-mailcow | `${SMTP_PORT}`                   |
+| Postfix SMTP        | TCP      | 25     | postfix-mailcow   | `${SMTP_PORT}`                   |
-| Postfix SMTPS       | TCP      | 465    | postfix-mailcow | `${SMTPS_PORT}`                  |
+| Postfix SMTPS       | TCP      | 465    | postfix-mailcow   | `${SMTPS_PORT}`                  |
-| Postfix Submission  | TCP      | 587    | postfix-mailcow | `${SUBMISSION_PORT}`             |
+| Postfix Submission  | TCP      | 587    | postfix-mailcow   | `${SUBMISSION_PORT}`             |
-| Dovecot IMAP        | TCP      | 143    | dovecot-mailcow | `${IMAP_PORT}`                   |
+| Dovecot IMAP        | TCP      | 143    | dovecot-mailcow   | `${IMAP_PORT}`                   |
-| Dovecot IMAPS       | TCP      | 993    | dovecot-mailcow | `${IMAPS_PORT}`                  |
+| Dovecot IMAPS       | TCP      | 993    | dovecot-mailcow   | `${IMAPS_PORT}`                  |
-| Dovecot POP3        | TCP      | 110    | dovecot-mailcow | `${POP_PORT}`                    |
+| Dovecot POP3        | TCP      | 110    | dovecot-mailcow   | `${POP_PORT}`                    |
-| Dovecot POP3S       | TCP      | 995    | dovecot-mailcow | `${POPS_PORT}`                   |
+| Dovecot POP3S       | TCP      | 995    | dovecot-mailcow   | `${POPS_PORT}`                   |
-| Dovecot ManageSieve | TCP      | 4190   | dovecot-mailcow | `${SIEVE_PORT}`                  |
+| Dovecot ManageSieve | TCP      | 4190   | dovecot-mailcow   | `${SIEVE_PORT}`                  |
-| HTTP(S)             | TCP      | 80/443 | nginx-mailcow   | `${HTTP_PORT}` / `${HTTPS_PORT}` |
+| HTTP(S)             | TCP      | 80/443 | nginx-mailcow     | `${HTTP_PORT}` / `${HTTPS_PORT}` |
 
 To bind a service to an IP address, you can prepend the IP like this: `SMTP_PORT=1.2.3.4:25`
 
 **Important**: You cannot use IP:PORT bindings in HTTP_PORT and HTTPS_PORT. Please use `HTTP_PORT=1234` and `HTTP_BIND=1.2.3.4` instead.
 
+### Important for Hetzner firewalls
+
+Quoting https://github.com/chermsen via https://github.com/mailcow/mailcow-dockerized/issues/497#issuecomment-469847380 (THANK YOU!):
+
+For all who are struggling with the Hetzner firewall:
+
+Port 53 unimportant for the firewall configuration in this case. According to the documentation unbound uses the port range 1024-65535 for outgoing requests.
+Since the Hetzner Robot Firewall is a static firewall (each incoming packet is checked isolated) - the following rules must be applied:
+
+**For TCP**
+```
+SRC-IP:       ---
+DST IP:       ---
+SRC Port:    ---
+DST Port:    1024-65535
+Protocol:    tcp
+TCP flags:   ack
+Action:      Accept
+```
+
+**For UDP**
+```
+SRC-IP:       ---
+DST IP:       ---
+SRC Port:    ---
+DST Port:    1024-65535
+Protocol:    udp
+Action:      Accept
+```
+
+If you want to apply a more restrictive port range you have to change the config of unbound first (after installation):
+
+{mailcow-dockerized}/data/conf/unbound/unbound.conf:
+```
+outgoing-port-avoid: 0-32767
+```
+
+Now the firewall rules can be adjusted as follows:
+
+```
+[...]
+DST Port:  32768-65535
+[...]
+```
+
 ## Date and Time
 
 To ensure that you have the correct date and time setup on your system, please check the output of `timedatectl status`:

docs/third_party-borgmatic.md

@@ -0,0 +1,261 @@
+# Borgmatic Backup
+
+## Introduction
+
+Borgmatic is a great way to run backups on your Mailcow setup as it securely encrypts your data and is extremely easy to
+set up.
+
+Due to it's deduplication capabilities you can store a great number of backups without wasting large amounts of disk
+space. This allows you to run backups in very short intervals to ensure minimal data loss when the need arises to
+recover data from a backup.
+
+This document guides you through the process to enable continuous backups for mailcow with borgmatic. The borgmatic
+functionality is provided by the [borgmatic Docker image by b3vis](https://github.com/b3vis/docker-borgmatic). Check out
+the `README` in that repository to find out about the other options (such as push notifications) that are available.
+This guide only covers the basics.
+
+## Setting up borgmatic
+
+### Create or amend `docker-compose.override.yml`
+
+In the mailcow-dockerized root folder create or edit `docker-compose.override.yml` and insert the following
+configuration:
+
+```yaml
+version: '2.1'
+
+services:
+  borgmatic-mailcow:
+    image: b3vis/borgmatic
+    hostname: mailcow
+    restart: always
+    dns: ${IPV4_NETWORK:-172.22.1}.254
+    volumes:
+      - vmail-vol-1:/mnt/source/vmail:ro
+      - crypt-vol-1:/mnt/source/crypt:ro
+      - redis-vol-1:/mnt/source/redis:ro,z
+      - rspamd-vol-1:/mnt/source/rspamd:ro,z
+      - postfix-vol-1:/mnt/source/postfix:ro,z
+      - mysql-socket-vol-1:/var/run/mysqld/:z
+      - borg-config-vol-1:/root/.config/borg:Z
+      - borg-cache-vol-1:/root/.cache/borg:Z
+      - ./data/conf/borgmatic/etc:/etc/borgmatic.d:Z
+      - ./data/conf/borgmatic/ssh:/root/.ssh:Z
+    environment:
+      - TZ=${TZ}
+      - BORG_PASSPHRASE=YouBetterPutSomethingRealGoodHere
+    networks:
+      mailcow-network:
+        aliases:
+          - borgmatic
+
+volumes:
+  borg-cache-vol-1:
+  borg-config-vol-1:
+```
+
+Ensure that you change the `BORG_PASSPHRASE` to a secure passphrase of your choosing.
+
+For security reasons we mount the maildir as read-only. If you later want to restore data you will need to remove
+the `ro` flag prior to restoring the data. This is described in the section on restoring backups.
+
+### Create `data/conf/borgmatic/etc/config.yaml`
+
+Next, we need to create the borgmatic configuration.
+
+```shell
+source mailcow.conf
+cat <<EOF > data/conf/borgmatic/etc/config.yaml
+location:
+    source_directories:
+        - /mnt/source
+    repositories:
+        - user@rsync.net:mailcow
+    exclude_patterns:
+        - '/mnt/source/postfix/public/'
+        - '/mnt/source/postfix/private/'
+        - '/mnt/source/rspamd/rspamd.sock'
+
+retention:
+    keep_hourly: 24
+    keep_daily: 7
+    keep_weekly: 4
+    keep_monthly: 6
+
+hooks:
+    mysql_databases:
+        - name: ${DBNAME}
+          username: ${DBUSER}
+          password: ${DBPASS}
+          options: --default-character-set=utf8mb4
+EOF
+```
+
+Creating the file in this way ensures the correct MySQL credentials are pulled in from `mailcow.conf`.
+
+This file is a minimal example for using borgmatic with an account `user` on the cloud storage provider `rsync.net` for
+a repository called `mailcow` (see `repositories` setting). It will backup both the maildir and MySQL database, which is
+all you should need to restore your mailcow setup after an incident. The retention settings will keep one archive for
+each hour of the past 24 hours, one per day of the week, one per week of the month and one per month of the past half
+year.
+
+Check the [borgmatic documentation](https://torsion.org/borgmatic/) on how to use other types of repositories or
+configuration options. If you choose to use a local filesystem as a backup destination make sure to mount it into the
+container. The container defines a volume called `/mnt/borg-repository` for this purpose.
+
+!!! note
+    If you do not use rsync.net you can most likely drop the `remote_path` element from your config.
+
+### Create a crontab
+
+Create a new text file in `data/conf/borgmatic/etc/crontab.txt` with the following content:
+
+```
+14 * * * * PATH=$PATH:/usr/bin /usr/bin/borgmatic --stats -v 0 2>&1
+```
+
+This file expects crontab syntax. The example shown here will trigger the backup to run every hour at 14 minutes past
+the hour and log some nice stats at the end.
+
+### Place SSH keys in folder
+
+Place the SSH keys you intend to use for remote repository connections in `data/conf/borgmatic/ssh`. OpenSSH expects the
+usual `id_rsa`, `id_ed25519` or similar to be in this directory. Ensure the file is `chmod 600` and not world readable
+or OpenSSH will refuse to use the SSH key.
+
+### Bring up the container
+
+For the next step we need the container to be up and running in a configured state. To do that run:
+
+```shell
+docker-compose up -d
+```
+
+### Initialize the repository
+
+By now your borgmatic container is up and running, but the backups will currently fail due to the repository not being
+initialized.
+
+To initialize the repository run:
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic init --encryption repokey-blake2
+```
+
+You will be asked you to authenticate the SSH host key of your remote repository server. See if it matches and confirm
+the prompt by entering `yes`. The repository will be initialized with the passphrase you set in the `BORG_PASSPHRASE`
+environment variable earlier.
+
+When using any of the `repokey` encryption methods the encryption key will be stored in the repository itself and not on
+the client, so there is no further action required in this regard. If you decide to use a `keyfile` instead of
+a `repokey` make sure you export the key and back it up separately. Check the [Exporting Keys](#exporting-keys) section
+for how to retrieve the key.
+
+### Restart container
+
+Now that we finished configuring and initializing the repository restart the container to ensure it is in a defined
+state:
+
+```shell
+docker-compose restart borgmatic-mailcow
+```
+
+## Restoring from a backup
+
+Restoring a backup assumes you are starting off with a fresh installation of mailcow, and you currently do not have
+any custom data in your maildir or your mailcow database.
+
+### Restore maildir
+
+!!! warning
+    Doing this will overwrite files in your maildir! Do not run this unless you actually intend to recover mail
+    files from a backup.
+
+!!! note "If you use SELinux in Enforcing mode"
+    If you are using mailcow on a host with SELinux in Enforcing mode you will have to temporarily disable it during
+    extraction of the archive as the mailcow setup labels the vmail volume as private, belonging to the dovecot container
+    exclusively. SELinux will (rightfully) prevent any other container, such as the borgmatic container, from writing to
+    this volume.
+
+Before running a restore you must make the vmail volume writeable in `docker-compose.override.yml` by removing
+the `ro` flag from the volume.
+Then you can use the following command to restore the maildir from a backup:
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic extract --path mnt/source --archive latest
+```
+
+Alternatively you can specify any archive name from the list of archives (see
+[Listing all available archives](#listing-all-available-archives))
+
+### Restore MySQL
+
+!!! warning
+    Running this command will delete and recreate the mailcow database! Do not run this unless you actually
+    intend to recover the mailcow database from a backup.
+
+To restore the MySQL database from the latest archive use this command:
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic restore --archive latest
+```
+
+Alternatively you can specify any archive name from the list of archives (see
+[Listing all available archives](#listing-all-available-archives))
+
+### After restoring
+
+After restoring you need to restart mailcow. If you disabled SELinux enforcing mode now would be a good time to
+re-enable it.
+
+To restart mailcow use the follwing command:
+
+```shell
+docker-compose down && docker-compose up -d
+```
+
+If you use SELinux this will also trigger the re-labeling of all files in your vmail volume. Be patient, as this may
+take a while if you have lots of files.
+
+## Useful commands
+
+### Manual archiving run (with debugging output)
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic -v 2
+```
+
+### Listing all available archives
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic list
+```
+
+### Break lock
+
+When borg is interrupted during an archiving run it will leave behind a stale lock that needs to be cleared before any
+new operations can be performed:
+
+```shell
+docker-compose exec borgmatic-mailcow borg break-lock user@rsync.net:mailcow
+```
+
+Where `user@rsync.net:mailcow` is the URI to your repository.
+
+Now would be a good time to do a manual archiving run to ensure it can be successfully performed.
+
+### Exporting keys
+
+When using any of the `keyfile` methods for encryption you **MUST** take care of backing up the key files yourself. The
+key files are generated when you initialize the repository. The `repokey` methods store the key file within the
+repository, so a manual backup isn't as essential.
+
+Note that in either case you also must have the passphrase to decrypt any archives.
+
+To fetch the keyfile run:
+
+```shell
+docker-compose exec borgmatic-mailcow borg key export --paper user@rsync.net:mailcow
+```
+
+Where `user@rsync.net:mailcow` is the URI to your repository.

docs/third_party-exchange_onprem.md

@@ -16,7 +16,7 @@ This setup becomes very handy if you have enabled the [Office 365 security defau
 Your mailcow needs to relay all mails to your personalized Exchange Host. It is the same host address we already looked up for the mx Record.
 
 1. Add the domain to your mailcow
-2. [Add your personalized Exchange Host address as relayhost](/firststeps-relayhost)
+2. [Add your personalized Exchange Host address as relayhost](../u_e-postfix-relayhost)
 3. Add your personalized Exchange Host address as forwarding host to unconditionally accepted all relayed mails from Exchange. (Admin > Configuration & Details > Configuration Dropdown > Forwarding Hosts)
 4. Go to the domain settings and select the newly added host on the `Sender-dependent transports` dropdown. Enable relaying by ticking the `Relay this domain`, `Relay all recipients` and the `Relay non-existing mailboxes only.` checkboxes
 

docs/third_party-gitea.md

@@ -33,11 +33,13 @@ GITEA_SSH_PORT=127.0.0.1:4000
 
 5\. Run `docker-compose up -d` to bring up the gitea container and run `docker-compose restart nginx-mailcow` afterwards.
 
-6\. Open `http://${MAILCOW_HOSTNAME}/gitea/`, for example `http://mx.example.org/gitea/`. For database details set `mysql` as database host. Use the value of DBNAME found in mailcow.conf as database name, DBUSER as database user and DBPASS as database password.
+6\. If you forced mailcow to https, execute step 9 and restart gitea with `docker-compose restart gitea-mailcow` . Go head with step 7 (Remember to use https instead of http, `https://mx.example.org/gitea/` 
 
-7\. Once the installation is complete, login as admin and set "settings" -> "authorization" -> "enable SMTP". SMTP Host should be `postfix` with port `587`, set `Skip TLS Verify` as we are using an unlisted SAN ("postfix" is most likely not part of your certificate).
+7\. Open `http://${MAILCOW_HOSTNAME}/gitea/`, for example `http://mx.example.org/gitea/`. For database details set `mysql` as database host. Use the value of DBNAME found in mailcow.conf as database name, DBUSER as database user and DBPASS as database password.
 
-8\. Create `data/gitea/gitea/conf/app.ini` and set following values. You can consult [gitea cheat sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for their meaning and other possible values.
+8\. Once the installation is complete, login as admin and set "settings" -> "authorization" -> "enable SMTP". SMTP Host should be `postfix` with port `587`, set `Skip TLS Verify` as we are using an unlisted SAN ("postfix" is most likely not part of your certificate).
+
+9\. Create `data/gitea/gitea/conf/app.ini` and set following values. You can consult [gitea cheat sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for their meaning and other possible values.
 
 ```
 [server]
@@ -49,4 +51,4 @@ SSH_PORT = 4000
 ROOT_URL = https://mx.example.org/gitea/
 ```
 
-9\. Restart gitea with `docker-compose restart gitea-mailcow`. Your users should be able to login with mailcow managed accounts.
+10\. Restart gitea with `docker-compose restart gitea-mailcow`. Your users should be able to login with mailcow managed accounts.

docs/third_party-mailman3.md

@@ -0,0 +1,323 @@
+# Installing mailcow and Mailman 3 based on dockerized versions
+
+!!! info
+    This guide is a copy from [dockerized-mailcow-mailman](https://github.com/g4rf/dockerized-mailcow-mailman). Please post issues, questions and improvements in the [issue tracker](https://github.com/g4rf/dockerized-mailcow-mailman/issues) there.
+
+!!! warning
+    mailcow is not responsible for any data loss, hardware damage or broken keyboards. This guide comes without any warranty. Make backups before starting, 'coze: **No backup no pity!**
+
+## Introduction
+
+This guide aims to install and configure [mailcow-dockerized](https://github.com/mailcow/mailcow-dockerized) with [docker-mailman](https://github.com/maxking/docker-mailman) and to provide some useful scripts. An essential condition is, to preserve *mailcow* and *Mailman* in their own installations for independent updates.
+
+There are some guides and projects on the internet, but they are not up to date and/or incomplete in documentation or configuration. This guide is based on the work of:
+
+- [mailcow-mailman3-dockerized](https://github.com/Shadowghost/mailcow-mailman3-dockerized) by [Shadowghost](https://github.com/Shadowghost)
+- [mailman-mailcow-integration](https://gitbucket.pgollor.de/docker/mailman-mailcow-integration)
+
+After finishing this guide, [mailcow-dockerized](https://github.com/mailcow/mailcow-dockerized) and [docker-mailman](https://github.com/maxking/docker-mailman) will run and *Apache* as a reverse proxy will serve the web frontends.
+
+The operating system used is an *Ubuntu 20.04 LTS*.
+
+## Installation
+
+This guide is based on different steps:
+
+1. DNS setup
+1. Install *Apache* as a reverse proxy
+1. Obtain SSL certificates with *Let's Encrypt*
+1. Install *mailcow* with *Mailman* integration
+1. Install *Mailman*
+1. 🏃 Run
+
+### DNS setup
+
+Most of the configuration is covered by *mailcow*s [DNS setup](https://mailcow.github.io/mailcow-dockerized-docs/prerequisite-dns/). After finishing this setup add another subdomain for *Mailman*, e.g. `lists.example.org` that points to the same server:
+
+```
+# Name    Type       Value
+lists     IN A       1.2.3.4
+lists     IN AAAA    dead:beef
+```
+
+### Install *Apache* as a reverse proxy
+
+Install *Apache*, e.g. with this guide from *Digital Ocean*: [How To Install the Apache Web Server on Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-ubuntu-20-04).
+
+Activate certain *Apache* modules (as *root* or *sudo*):
+
+```
+a2enmod rewrite proxy proxy_http headers ssl wsgi proxy_uwsgi http2
+```
+
+Maybe you have to install further packages to get these modules. This [PPA](https://launchpad.net/~ondrej/+archive/ubuntu/apache2) by *Ondřej Surý* may help you.
+
+#### vHost configuration
+
+Copy the [mailcow.conf](https://github.com/g4rf/dockerized-mailcow-mailman/tree/master/apache/mailcow.conf) and the [mailman.conf](https://github.com/g4rf/dockerized-mailcow-mailman/tree/master/apache/mailman.conf) in the *Apache* conf folder `sites-available` (e.g. under `/etc/apache2/sites-available`).
+
+Change in `mailcow.conf`:
+- `MAILCOW_HOSTNAME` to your **MAILCOW_HOSTNAME**
+
+Change in `mailman.conf`:
+- `MAILMAN_DOMAIN` to your *Mailman* domain (e.g. `lists.example.org`)
+
+**Don't activate the configuration, as the ssl certificates and directories are missing yet.**
+
+
+### Obtain SSL certificates with *Let's Encrypt*
+
+Check if your DNS config is available over the internet and points to the right IP addresses, e.g. with [MXToolBox](https://mxtoolbox.com):
+
+- https://mxtoolbox.com/SuperTool.aspx?action=a%3aMAILCOW_HOSTNAME
+- https://mxtoolbox.com/SuperTool.aspx?action=aaaa%3aMAILCOW_HOSTNAME
+- https://mxtoolbox.com/SuperTool.aspx?action=a%3aMAILMAN_DOMAIN
+- https://mxtoolbox.com/SuperTool.aspx?action=aaaa%3aMAILMAN_DOMAIN
+
+Install [certbot](https://certbot.eff.org/) (as *root* or *sudo*):
+
+```
+apt install certbot
+```
+
+Get the desired certificates (as *root* or *sudo*):
+
+```
+certbot certonly -d mailcow_HOSTNAME
+certbot certonly -d MAILMAN_DOMAIN
+```
+
+### Install *mailcow* with *Mailman* integration
+
+#### Install mailcow
+
+Follow the [mailcow installation](https://mailcow.github.io/mailcow-dockerized-docs/i_u_m_install/). **Omit step 5 and do not pull and up with `docker-compose`!**
+
+#### Configure mailcow
+
+This is also **Step 4** in the official *mailcow installation* (`nano mailcow.conf`). So change to your needs and alter the following variables:
+
+```
+HTTP_PORT=18080            # don't use 8080 as mailman needs it
+HTTP_BIND=127.0.0.1        #
+HTTPS_PORT=18443           # you may use 8443
+HTTPS_BIND=127.0.0.1       #
+
+SKIP_LETS_ENCRYPT=y        # reverse proxy will do the SSL termination
+
+SNAT_TO_SOURCE=1.2.3.4     # change this to your IPv4
+SNAT6_TO_SOURCE=dead:beef  # change this to your global IPv6
+```
+
+#### Add Mailman integration
+
+Create the file `/opt/mailcow-dockerized/docker-compose.override.yml` (e.g. with `nano`) and add the following lines:
+
+```
+version: '2.1'
+
+services:
+  postfix-mailcow:
+    volumes:
+      - /opt/mailman:/opt/mailman
+    networks:
+      - docker-mailman_mailman
+
+networks:
+  docker-mailman_mailman:
+    external: true
+```
+The additional volume is used by *Mailman* to generate additional config files for *mailcow postfix*. The external network is build and used by *Mailman*. *mailcow* needs it to deliver incoming list mails to *Mailman*.
+
+
+Create the file `/opt/mailcow-dockerized/data/conf/postfix/extra.cf` (e.g. with `nano`) and add the following lines:
+
+```
+# mailman
+
+recipient_delimiter = +
+unknown_local_recipient_reject_code = 550
+owner_request_special = no
+
+local_recipient_maps =
+  regexp:/opt/mailman/core/var/data/postfix_lmtp,
+  proxy:unix:passwd.byname,
+  $alias_maps
+virtual_mailbox_maps =
+  proxy:mysql:/opt/postfix/conf/sql/mysql_virtual_mailbox_maps.cf,
+  regexp:/opt/mailman/core/var/data/postfix_lmtp
+transport_maps =
+  pcre:/opt/postfix/conf/custom_transport.pcre,
+  pcre:/opt/postfix/conf/local_transport,
+  proxy:mysql:/opt/postfix/conf/sql/mysql_relay_ne.cf,
+  proxy:mysql:/opt/postfix/conf/sql/mysql_transport_maps.cf,
+  regexp:/opt/mailman/core/var/data/postfix_lmtp
+relay_domains =
+  proxy:mysql:/opt/postfix/conf/sql/mysql_virtual_relay_domain_maps.cf,
+  regexp:/opt/mailman/core/var/data/postfix_domains
+relay_recipient_maps =
+  proxy:mysql:/opt/postfix/conf/sql/mysql_relay_recipient_maps.cf,
+  regexp:/opt/mailman/core/var/data/postfix_lmtp
+```
+As we overwrite *mailcow postfix* configuration here, this step may break your normal mail transports. Check the [original configuration files](https://github.com/mailcow/mailcow-dockerized/tree/master/data/conf/postfix) if anything changed.
+
+#### SSL certificates
+
+As we proxying *mailcow*, we need to copy the SSL certificates into the *mailcow* file structure. This task will do the script [renew-ssl.sh](https://github.com/g4rf/dockerized-mailcow-mailman/tree/master/scripts/renew-ssl.sh) for us:
+
+- Copy the file to `/opt/mailcow-dockerized`
+- Change **mailcow_HOSTNAME** to your *mailcow* hostname
+- Make it executable (`chmod a+x renew-ssl.sh`)
+- **Do not run it yet, as we first need Mailman**
+
+You have to create a *cronjob*, so that new certificates will be copied. Execute as *root* or *sudo*:
+
+```
+crontab -e
+```
+
+To run the script every day at 5am, add:
+
+```
+0   5  *   *   *     /opt/mailcow-dockerized/renew-ssl.sh
+```
+
+### Install *Mailman*
+
+Basicly follow the instructions at [docker-mailman](https://github.com/maxking/docker-mailman). As they are a lot, here is in a nuthshell what to do:
+
+As *root* or *sudo*:
+
+```
+cd /opt
+mkdir -p mailman/core
+mkdir -p mailman/web
+git clone https://github.com/maxking/docker-mailman
+cd docker-mailman
+```
+
+#### Configure Mailman
+
+Create a long key for *Hyperkitty*, e.g. with the linux command `cat /dev/urandom | tr -dc a-zA-Z0-9 | head -c30; echo`. Save this key for a moment as HYPERKITTY_KEY.
+
+Create a long password for the database, e.g. with the linux command `cat /dev/urandom | tr -dc a-zA-Z0-9 | head -c30; echo`. Save this password for a moment as DBPASS.
+
+Create a long key for *Django*, e.g. with the linux command `cat /dev/urandom | tr -dc a-zA-Z0-9 | head -c30; echo`. Save this key for a moment as DJANGO_KEY.
+
+Create the file `/opt/docker-mailman/docker-compose.override.yaml` and replace `HYPERKITTY_KEY`, `DBPASS` and `DJANGO_KEY` with the generated values:
+
+```
+version: '2'
+
+services:
+  mailman-core:
+    environment:
+    - DATABASE_URL=postgres://mailman:DBPASS@database/mailmandb
+    - HYPERKITTY_API_KEY=HYPERKITTY_KEY
+    - TZ=Europe/Berlin
+    - MTA=postfix
+    restart: always
+    networks:
+      - mailman
+
+  mailman-web:
+    environment:
+    - DATABASE_URL=postgres://mailman:DBPASS@database/mailmandb
+    - HYPERKITTY_API_KEY=HYPERKITTY_KEY
+    - TZ=Europe/Berlin
+    - SECRET_KEY=DJANGO_KEY
+    - SERVE_FROM_DOMAIN=MAILMAN_DOMAIN # e.g. lists.example.org
+    - MAILMAN_ADMIN_USER=admin # the admin user
+    - MAILMAN_ADMIN_EMAIL=admin@example.org # the admin mail address
+    - UWSGI_STATIC_MAP=/static=/opt/mailman-web-data/static
+    restart: always
+
+  database:
+    environment:
+    - POSTGRES_PASSWORD=DBPASS
+    restart: always
+```
+
+At `mailman-web` fill in correct values for `SERVE_FROM_DOMAIN` (e.g. `lists.example.org`), `MAILMAN_ADMIN_USER` and `MAILMAN_ADMIN_EMAIL`. You need the admin credentials to log into the web interface (*Pistorius*). For setting **the password for the first time** use the *Forgot password* function in the web interface.
+
+About other configuration options read [Mailman-web](https://github.com/maxking/docker-mailman#mailman-web-1) and [Mailman-core](https://github.com/maxking/docker-mailman#mailman-core-1) documentation.
+
+#### Configure Mailman core and Mailman web
+
+Create the file `/opt/mailman/core/mailman-extra.cfg` with the following content. `mailman@example.org` should be pointing to a valid mail box or redirection.
+
+```
+[mailman]
+default_language: de
+site_owner: mailman@example.org
+```
+
+Create the file `/opt/mailman/web/settings_local.py` with the following content. `mailman@example.org` should be pointing to a valid mail box or redirection.
+
+```
+# locale
+LANGUAGE_CODE = 'de-de'
+
+# disable social authentication
+SOCIALACCOUNT_PROVIDERS = {}
+
+# change it
+DEFAULT_FROM_EMAIL = 'mailman@example.org'
+
+DEBUG = False
+```
+You can change `LANGUAGE_CODE` and `SOCIALACCOUNT_PROVIDERS` to your needs. At the moment `SOCIALACCOUNT_PROVIDERS` has no effect, see [issue #2](https://github.com/g4rf/dockerized-mailcow-mailman/issues/2).
+
+
+### 🏃 Run
+
+Run (as *root* or *sudo*)
+
+```
+a2ensite mailcow.conf
+a2ensite mailman.conf
+systemctl restart apache2
+
+cd /opt/docker-mailman
+docker-compose pull
+docker-compose up -d
+
+cd /opt/mailcow-dockerized/
+docker-compose pull
+./renew-ssl.sh
+```
+
+**Wait a few minutes!** The containers have to create there databases and config files. This can last up to 1 minute and more.
+
+## Remarks
+
+### New lists aren't recognized by postfix instantly
+
+When you create a new list and try to immediately send an e-mail, *postfix* responses with `User doesn't exist`, because *postfix* won't deliver it to *Mailman* yet. The configuration at `/opt/mailman/core/var/data/postfix_lmtp` is not instantly updated. If you need the list instantly, restart *postifx* manually:
+
+```
+cd /opt/mailcow-dockerized
+docker-compose restart postfix-mailcow
+```
+
+## Update
+
+**mailcow** has it's own update script in `/opt/mailcow-dockerized/update.sh', [see the docs](https://mailcow.github.io/mailcow-dockerized-docs/i_u_m_update/).
+
+For **Mailman** just fetch the newest version from the [github repository](https://github.com/maxking/docker-mailman).
+
+## Backup
+
+**mailcow** has an own backup script. [Read the docs](https://mailcow.github.io/mailcow-dockerized-docs/b_n_r_backup/) for further informations.
+
+**Mailman** won't state backup instructions in the README.md. In the [gitbucket of pgollor](https://gitbucket.pgollor.de/docker/mailman-mailcow-integration/blob/master/mailman-backup.sh) is a script that may be helpful.
+
+## ToDo
+
+### install script
+
+Write a script like in [mailman-mailcow-integration/mailman-install.sh](https://gitbucket.pgollor.de/docker/mailman-mailcow-integration/blob/master/mailman-install.sh) as many of the steps are automatable.
+
+1. Ask for all the configuration variables and create passwords and keys.
+2. Do a (semi-)automatic installation.
+3. Have fun!

docs/third_party-mailpiler_integration.md

@@ -2,6 +2,9 @@ This is a simple integration of mailcow aliases and the mailbox name into mailpi
 
 **Disclaimer**: This is not officially maintained nor supported by the mailcow project nor its contributors. No warranty or support is being provided, however you're free to open issues on GitHub for filing a bug or provide further ideas. [GitHub repo can be found here](https://github.com/patschi/mailpiler-mailcow-integration).
 
+!!! info
+    Support for domain wildcards were implemented in Piler 1.3.10 which was released on 03.01.2021. Prior versions basically do work, but after logging in you won't see emails sent from or to the domain alias. (e.g. when @example.com is an alias for admin@example.com)
+
 ## The problem to solve
 
 mailpiler offers the authentication based on IMAP, for example:
@@ -30,7 +33,7 @@ Note: File paths might vary depending on your setup.
 ### Requirements
 
 - A working mailcow instance
-- A working mailpiler instance ([You can find an installation guide here](https://patrik.kernstock.net/2020/08/mailpiler-installation-guide/))
+- A working mailpiler instance ([You can find an installation guide here](https://patrik.kernstock.net/2020/08/mailpiler-installation-guide/), [check supported versions here](https://github.com/patschi/mailpiler-mailcow-integration#piler))
 - An mailcow API key (read-only works just fine): `Configuration & Details - Access - Read-Only Access`. Don't forget to allow API access from your mailpiler IP.
 
 !!! warning

docs/third_party-nextcloud.md

@@ -75,3 +75,31 @@ If you have previously used Nextcloud without mailcow authentication, but with t
 ```
 INSERT INTO nc_sociallogin_connect (uid, identifier) SELECT DISTINCT uid, CONCAT("Mailcow-", uid) FROM nc_users;
 ```
+
+---
+
+## Update
+
+The Nextcloud instance can be updated easily with the web update mechanism. In the case of larger updates, there may be further changes to be made after the update. After the Nextcloud instance has been checked, problems are shown. This can be e.g. missing indices in the DB or similar.
+It shows which commands have to be executed, these have to be placed in the php-fpm-mailcow container.
+
+As an an example run the following command to add the missing indices.
+`docker exec -it -u www-data $(docker ps -f name=php-fpm-mailcow -q) bash -c "php /web/nextcloud/occ db:add-missing-indices"`
+
+---
+
+## Debugging & Troubleshooting
+
+It may happen that you cannot reach the Nextcloud instance from your network. This may be due to the fact that the entry of your subnet in the array 'trusted_proxies' is missing. You can make changes in the Nextcloud config.php in `data/web/nextcloud/config/*`.
+
+```
+'trusted_proxies' =>
+  array (
+    0 => 'fd4d:6169:6c63:6f77::/64',
+    1 => '172.22.1.0/24',
+    2 => 'NewSubnet/24',
+  ),
+```
+
+After the changes have been made, the nginx container must be restarted.
+`docker-compose restart nginx-mailcow`

docs/third_party-portainer.md

@@ -5,7 +5,7 @@ In order to enable Portainer, the docker-compose.yml and site.conf for Nginx mus
 version: '2.1'
 services:
     portainer-mailcow:
-      image: portainer/portainer
+      image: portainer/portainer-ce
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
         - ./data/conf/portainer:/data

docs/third_party-roundcube.md

@@ -194,7 +194,6 @@ rm -rf roundcube*
 sed -i "s/\$prefix = '\.\/';/\$prefix = preg_replace\('\/\[\?\&]\.\*\$\/', '', \$_SERVER\['REQUEST_URI'] \?\? ''\) \?: '\.\/';/g" /web/rc/program/include/rcmail.php
 ```
 
-
 ### Let admins log into Roundcube without password
 
 First, install plugin [dovecot_impersonate](https://github.com/corbosman/dovecot_impersonate/) and add Roundcube as an app (see above).

docs/third_party-thunderbird.md

@@ -1,28 +0,0 @@
-# Build the SOGo Connector plugin
-
-Install GNU Make, tar, and ZIP if you don't already have them installed. On Debian/Ubuntu, this can be done using
-
-```
-apt-get install make tar zip
-```
-
-Next, go to `data/web` inside mailcow-dockerized.
-Place the file [thunderbird-plugins.php](download/thunderbird-plugins.php) into that directory.
-Create a new directory `thunderbird-plugins` and place the script [build-plugins.sh](download/build-thunderbird-plugins.sh) into it.
-Finally, execute the script with your hostname as an argument and piping it the names of all domains that mailcow handles.
-All of this can be done using the following commands:
-
-```
-cd data/web
-curl -LO https://github.com/mailcow/mailcow-dockerized-docs/raw/master/docs/download/thunderbird-plugins.php
-mkdir thunderbird-plugins
-cd thunderbird-plugins
-curl -Lo build-plugins.sh https://github.com/mailcow/mailcow-dockerized-docs/raw/master/docs/download/build-thunderbird-plugins.sh
-chmod +x build-plugins.sh
-echo example.com example.org | ./build-plugins.sh mailcow.example.com
-```
-
-# Install it in Thunderbird
-
-After you have set up your mailcow IMAP account in Thunderbird, download the SOGo Connector plugin for your domain, e.g. https://mailcow.example.com/thunderbird-plugins/sogo-connector-68.0.1-example.com.xpi (see `data/web/thunderbird-plugins`), and install it into Thunderbird.
-All your address books and calendars will be configured automatically.

docs/u_e-80_to_443.md

@@ -2,7 +2,7 @@ Since February the 28th 2017 mailcow does come with port 80 and 443 enabled.
 
 **Do not use the config below for reverse proxy setups**, please see our reverse proxy guide for this, which includes a redirect from HTTP to HTTPS.
 
-Open `mailcow.conf` and set `HTTP_BIND=0.0.0.0` - if not already set.
+Open `mailcow.conf` and set `HTTP_BIND=` - if not already set.
 
 Create a new file `data/conf/nginx/redirect.conf` and add the following server config to the file:
 

docs/u_e-change_config.md

@@ -1,68 +0,0 @@
-The most important configuration files are mounted from the host into the related containers:
-
-```
-data/conf
-├── unbound
-│   └── unbound.conf
-├── dovecot
-│   ├── dovecot.conf
-│   ├── dovecot-master.passwd
-│   ├── sieve_after
-│   └── sql
-│       ├── dovecot-dict-sql.conf
-│       └── dovecot-mysql.conf
-├── mysql
-│   └── my.cnf
-├── nginx
-│   ├── dynmaps.conf
-│   ├── site.conf
-│   └── templates
-│       ├── listen_plain.template
-│       ├── listen_ssl.template
-│       └── server_name.template
-├── postfix
-│   ├── main.cf
-│   ├── master.cf
-│   ├── postscreen_access.cidr
-│   ├── smtp_dsn_filter
-│   └── sql
-│       ├── mysql_relay_recipient_maps.cf
-│       ├── mysql_tls_enforce_in_policy.cf
-│       ├── mysql_tls_enforce_out_policy.cf
-│       ├── mysql_virtual_alias_domain_catchall_maps.cf
-│       ├── mysql_virtual_alias_domain_maps.cf
-│       ├── mysql_virtual_alias_maps.cf
-│       ├── mysql_virtual_domains_maps.cf
-│       ├── mysql_virtual_mailbox_maps.cf
-│       ├── mysql_virtual_relay_domain_maps.cf
-│       ├── mysql_virtual_sender_acl.cf
-│       └── mysql_virtual_spamalias_maps.cf
-├── rspamd
-│   ├── dynmaps
-│   │   ├── authoritative.php
-│   │   ├── settings.php
-│   │   ├── tags.php
-│   │   └── vars.inc.php -> ../../../web/inc/vars.inc.php
-│   ├── local.d
-│   │   ├── dkim.conf
-│   │   ├── metrics.conf
-│   │   ├── options.inc
-│   │   ├── redis.conf
-│   │   ├── rspamd.conf.local
-│   │   └── statistic.conf
-│   ├── lua
-│   │   └── rspamd.local.lua
-│   └── override.d
-│       ├── logging.inc
-│       ├── worker-controller.inc
-│       └── worker-normal.inc
-└── sogo
-    ├── sieve.creds
-    └── sogo.conf
-
-```
-
-Just change the according configuration file on the host and restart the related service:
-```
-docker-compose restart service-mailcow
-```

docs/u_e-dovecot-catchall_vacation.md

@@ -0,0 +1,4 @@
+The Dovecot parameter `sieve_vacation_dont_check_recipient` - which was by default set to `yes` in mailcow configurations pre 21st July - allows for vacation replies even when a mail is sent to non-existent mailboxes like a catch-all addresses.
+
+We decided to switch this parameter back to `no` and allow a user to specify which recipient address triggers a vacation reply. The triggering recipients can also be configured in SOGos autoresponder feature.
+

docs/u_e-dovecot-expunge.md

@@ -31,7 +31,9 @@ docker-compose exec dovecot-mailcow doveadm expunge -u 'mailbox@example.com' mai
 !!! info
     For possible [time spans](https://wiki.dovecot.org/Tools/Doveadm/SearchQuery#section_date_specification) or [search keys](https://wiki.dovecot.org/Tools/Doveadm/SearchQuery#section_search_keys) have a look at [man doveadm-search-query](https://wiki.dovecot.org/Tools/Doveadm/SearchQuery)
 
-## Make it automatic
+## Job scheduler
+
+### via the host system cron
 
 If you want to automate such a task you can create a cron job on your host that calls a script like the one below:
 
@@ -51,3 +53,41 @@ To create a cron job you may execute `crontab -e` and insert something like the
 # Execute everyday at 04:00 A.M.
 0 4 * * * /path/to/your/expunge_mailboxes.sh
 ```
+
+### via Docker job scheduler
+
+To archive this with a docker job scheduler use this docker-compose.override.yml with your mailcow: 
+
+```
+version: '2.1'
+
+services:
+  
+  ofelia:
+    image: mcuadros/ofelia:latest
+    restart: always
+    command: daemon --docker
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro   
+    network_mode: none
+
+  dovecot-mailcow:
+    labels:
+      - "ofelia.enabled=true"
+      - "ofelia.job-exec.dovecot-expunge-trash.schedule=0 4 * * *"
+      - "ofelia.job-exec.dovecot-expunge-trash.command=doveadm expunge -A mailbox 'Junk' savedbefore 2w"
+      - "ofelia.job-exec.dovecot-expunge-trash.tty=false"
+
+```
+
+The job controller just need access to the docker control socket to be able to emulate the behavior of "exec". Then we add a few label to our dovecot-container to activate the job scheduler and tell him in a cron compatible scheduling format when to run. If you struggle with that schedule string you can use [crontab guru](https://crontab.guru/). 
+This docker-compose.override.yml deletes all mails older then 2 weeks from the "Junk" folder every day at 4 am. To see if things ran proper, you can not only see in your mailbox but also check Ofelia's docker log if it looks something like this:
+
+```
+common.go:124 ▶ NOTICE [Job "dovecot-expunge-trash" (8759567efa66)] Started - doveadm expunge -A mailbox 'Junk' savedbefore 2w,
+common.go:124 ▶ NOTICE [Job "dovecot-expunge-trash" (8759567efa66)] Finished in "285.032291ms", failed: false, skipped: false, error: none,
+```
+
+If it failed it will say so and give you the output of the doveadm in the log to make it easy on you to debug.
+
+In case you want to add more jobs, ensure you change the "dovecot-expunge-trash" part after "ofelia.job-exec." to something else, it defines the name of the job. Syntax of the labels you find at [mcuadros/ofelia](https://github.com/mcuadros/ofelia).

docs/u_e-dovecot-vmail-volume.md

@@ -1,3 +1,20 @@
+## The "new" way
+
+**WARNING**: Newer Docker versions seem to complain about existing volumes. You can fix this temporarily by removing the existing volume and start mailcow with the override file. But it seems to be problematic after a reboot (needs to be confirmed).
+
+An easy, dirty, yet stable workaround is to stop mailcow (`docker-compose down`), remove `/var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data` and create a new link to your remote filesystem location, for example:
+
+```
+mv /var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data /var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data_backup
+ln -s /mnt/volume-xy/vmail_data /var/lib/docker/volumes/mailcowdockerized_vmail-vol-1/_data
+```
+
+Start mailcow afterwards.
+
+---
+
+## The "old" way
+
 If you want to use another folder for the vmail-volume, you can create a `docker-compose.override.yml` file and add the following content:
 
 ```

docs/u_e-fido2.md

@@ -0,0 +1,18 @@
+## How is UV handled in mailcow?
+
+The UV flag (as in "user verification") enforces WebAuthn to verify the user before it allows access to the key (think of a PIN). We don't enforce UV to allow logins via iOS and NFC (YubiKey).
+
+## Login and key processing
+
+mailcow uses **client-side key processing**. We ask the authenticator (i.e. YubiKey) to save the registration in its memory.
+
+A user does not need to enter a username. The available credentials - if any - will be shown to the user when selecting the "key login" via mailcow UI login.
+
+When calling the login process, the authenticator is not given any credential IDs. This will force it to lookup credentials in its own memory.
+
+## Who can use WebAuthn to login to mailcow?
+
+As of today, only administrators and domain administrators are able to setup WebAuthn/FIDO2.
+
+---
+**You want to use WebAuthn/Fido as 2FA? Check it out here: [Two-Factor Authentication](https://mailcow.github.io/mailcow-dockerized-docs/u_e-mailcow_ui-tfa/)**

docs/u_e-mailcow_ui-css.md

@@ -0,0 +1,3 @@
+For custom overrides of specific elements via CSS, use `data/web/css/build/0081-custom-mailcow.css`.
+
+The file is excluded from tracking and persists over updates.

docs/u_e-mailcow_ui-tagging.md

@@ -1,6 +1,9 @@
 Mailbox users can tag their mail address like in `me+facebook@example.org`. They can control the tag handling in the users **mailcow UI** panel.
 ![mailcow mail tagging settings](images/mailcow-tagging.png)
 
+*Tagging is also known as 'sub-addressing' (RFC 5233) or 'plus addressing'*
+
+
 ### Available Actions
 
 1\. Move this message to a sub folder "facebook" (will be created lower case if not existing)

docs/u_e-mailcow_ui-tfa.md

@@ -1,10 +1,10 @@
-So far three methods for *Two-Factor Authentication* are implemented: U2F, Yubi OTP, and TOTP
+So far three methods for _Two-Factor Authentication_ are implemented: WebAuthn (replacing U2F since February 2022), Yubi OTP, and TOTP
 
-- For U2F to work, you need an encrypted connection to the server (HTTPS) as well as a FIDO security key.
+-   For WebAuthn to work, you need an encrypted connection to the server (HTTPS) as well as a FIDO security key.
-- Both U2F and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com).
+-   Both WebAuthn and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com).
-- While Yubi OTP needs an active internet connection and an API ID + key, U2F will work with any FIDO U2F USB key out of the box, but can only be used when mailcow is accessed over HTTPS.
+-   While Yubi OTP needs an active internet connection and an API ID + key, WebAuthn will work with any Fido Security Key out of the box, but can only be used when mailcow is accessed over HTTPS.
-- U2F and Yubi OTP support multiple keys per user.
+-   WebAuthn and Yubi OTP support multiple keys per user.
-- As the third TFA method mailcow uses TOTP: time-based one-time passwords. Those passwords can be generated with apps like "Google Authenticator" after initially scanning a QR code or entering the given secret manually.
+-   As the third TFA method mailcow uses TOTP: time-based one-time passwords. Those passwords can be generated with apps like "Google Authenticator" after initially scanning a QR code or entering the given secret manually.
 
 As administrator you are able to temporary disable a domain administrators TFA login until they successfully logged in.
 
@@ -12,18 +12,110 @@ The key used to login will be displayed in green, while other keys remain grey.
 
 Information on how to remove 2FA can be found [here](https://mailcow.github.io/mailcow-dockerized-docs/debug-reset_pw/#remove-two-factor-authentication).
 
-### Yubi OTP
+## Yubi OTP
 
 The Yubi API ID and Key will be checked against the Yubico Cloud API. When setting up TFA you will be asked for your personal API account for this key.
 The API ID, API key and the first 12 characters (your YubiKeys ID in modhex) are stored in the MySQL table as secret.
 
-### U2F
+### Example setup
 
-Only Google Chrome (+derivatives) and Opera support U2F authentication to this day natively.
+First of all, the YubiKey must be configured for use as an OTP Generator. To do this, download the `YubiKey Manager` from the Yubico website: [here](https://www.yubico.com/support/download/)
-Since version 67 Mozilla Firefox can handle U2F natively. ([Source](https://support.yubico.com/support/solutions/articles/15000017511-enabling-u2f-support-in-mozilla-firefox))
 
-U2F works without an internet connection.
+In the following you configure the YubiKey for OTP.
+Via the menu item `Applications` -> `OTP` and a click on the `Configure` button. In the following menu select `Credential Type` -> `Yubico OTP` and click on `Next`.
 
-### TOTP
+Set a checkmark in the `Use serial` checkbox, generate a `Private ID` and a `Secret key` via the buttons. 
+So that the YubiKey can be validated later, the checkmark in the `Upload` checkbox must also be set and then click on `Finish`.
+
+Now a new browser window will open in which you have to enter an OTP of your YubiKey at the bottom of the form (click on the field and then tap on your YubiKey). Confirm the captcha and upload the information to the Yubico server by clicking 'Upload'. The processing of the data will take a moment.
+
+After the generation was successful, you will be shown a `Client ID` and a `Secret key`, make a note of this information in a safe place.
+
+Now you can select `Yubico OTP authentication` from the dropdown menu in the mailcow UI on the start page under `Access` -> `Two-factor authentication`. 
+In the dialog that opened now you can enter a name for this YubiKey and insert the `Client ID` you noted before as well as the `Secret key` into the fields provided.
+Finally, enter your current account password and, after selecting the `Touch Yubikey` field, touch your YubiKey button.
+
+Congratulations! You can now log in to the mailcow UI using your YubiKey!
+
+---
+
+## WebAuthn (U2F, replacement)
+> :warning: **Since February 2022 Google Chrome has discarded support for U2F and standardized the use of WebAuthn.<br>**
+> *The WebAuthn (U2F removal) is part of mailcow since 21th January 2022, so if you want to use the Key past February 2022 please consider a update with the `update.sh` script.*
+
+To use WebAuthn, the browser must support this standard.
+
+The following desktop browsers support this authentication type:
+
+-   Edge (>=18)
+-   Firefox (>=60)
+-   Chrome (>=67)
+-   Safari (>=13)
+-   Opera (>=54)
+
+The following mobile browsers support this authentication type:
+
+-   Safari on iOS (>=14.5)
+-   Android Browser (>=97)
+-   Opera Mobile (>=64)
+-   Chrome for Android (>=97)
+
+Sources: [caniuse.com](https://caniuse.com/webauthn), [blog.mozilla.org](https://blog.mozilla.org/security/2019/04/04/shipping-fido-u2f-api-support-in-firefox/)
+
+WebAuthn works without an internet connection.
+
+### What will happen to my registered Fido Security Key after the Update from U2F to WebAuthn?
+> :warning: With this new U2F replacement (WebAuthn) you have to re-register your Fido Security Key, thankfully WebAuthn is backwards compatible and supports the U2F protocol.
+
+Ideally, the next time you log in (with the key), you should get a text box saying that your Fido Security Key has been removed due to the update to WebAuthn and deleted as a 2-factor authenticator.
+
+But don't worry! You can simply re-register your existing key and use it as usual, you probably won't even notice a difference, except that your browser won't show the U2F deactivation message anymore.
+
+### Disable unofficial supported Fido Security Keys
+With WebAuthn there is the possibility to use only official Fido Security Keys (from the big brands like: Yubico, Apple, Nitro, Google, Huawei, Microsoft, etc.).
+
+This is primarily for security purposes, as it allows administrators to ensure that only official hardware can be used in their environment.
+
+To enable this feature, change the value `WEBAUTHN_ONLY_TRUSTED_VENDORS` in mailcow.conf from `n` to `y` and restart the affected containers with `docker-compose up -d`.
+
+The mailcow will now use the Vendor Certificates located in your mailcow directory under `data/web/inc/lib/WebAuthn/rootCertificates`. 
+
+##### Example:
+If you want to limit the official Vendor devices to Apple only you only need the Apple Vendor Certificate inside the `data/web/inc/lib/WebAuthn/rootCertificates`.
+After you deleted all other certs you now only can activate WebAuthn 2FA with Apple devices.
+
+That´s for every vendor the same, so choose what you like (if you want to).
+
+#### Use own certificates for WebAuthn
+If you have a valid certificate from the vendor of your key you can also add it to your mailcow!
+
+Just copy the certificate into the `data/web/inc/lib/WebAuthn/rootCertificates` folder and restart your mailcow.
+
+Now you should be able to register this device as well, even though the verification for the vendor certificates is enabled, since you just added the certificate manually. 
+
+#### Is it dangerous to keep the Vendor Check disabled?
+No, it isn´t!
+These vendor certificates are only used to verify original hardware, not to secure the registration process.
+
+As you can read in these articles, the deactivation is not software security related:
+- [https://developers.yubico.com/U2F/Attestation_and_Metadata/](https://developers.yubico.com/U2F/Attestation_and_Metadata/)
+- [https://medium.com/webauthnworks/webauthn-fido2-demystifying-attestation-and-mds-efc3b3cb3651](https://medium.com/webauthnworks/webauthn-fido2-demystifying-attestation-and-mds-efc3b3cb3651)
+- [https://medium.com/webauthnworks/sorting-fido-ctap-webauthn-terminology-7d32067c0b01](https://medium.com/webauthnworks/sorting-fido-ctap-webauthn-terminology-7d32067c0b01)
+
+In the end, however, it is of course your decision to leave this check disabled or enabled. 
+
+---
+
+## TOTP
 
 The best known TFA method mostly used with a smartphone.
+
+To setup the TOTP method login to the Admin UI and select `Time-based OTP (TOTP)` from the list.
+
+Now a modal will open in which you have to type in a name for your 2FA "device" (example: John Deer´s Smartphone) and the password of the affected Admin account (you are currently logged in with).
+
+You have two seperate methods to register TOTP to your account:
+1. Scan the QR-Code with your Authenticator App on a Smartphone or Tablet.
+2. Use the TOTP Code (under the QR Code) in your TOTP Program or App (if you can´t scan a QR Code).
+
+After you have registered the QR or TOTP code in the TOTP app/program of your choice you only need to enter the now generated TOTP token (in the app/program) as confirmation in the mailcow UI to finally activate the TOTP 2FA, otherwise it will not be activated even though the TOTP token is already generated in your app/program.

docs/u_e-nginx.md

@@ -1,25 +1,46 @@
+## SSL
+
+Please see [Advanced SSL](https://mailcow.github.io/mailcow-dockerized-docs/firststeps-ssl/) and explicitly check `ADDITIONAL_SERVER_NAMES` for SSL configuration.
+
+Please do not add ADDITIONAL_SERVER_NAMES when you plan to use a different web root.
+
+## New site
+
 To create persistent (over updates) sites hosted by mailcow: dockerized, a new site configuration must be placed inside `data/conf/nginx/`:
 
+A good template to begin with:
+
 ```
 nano data/conf/nginx/my_custom_site.conf
 ```
 
-A good template to begin with:
+``` hl_lines="16"
-
-``` hl_lines="9"
 server {
   ssl_certificate /etc/ssl/mail/cert.pem;
   ssl_certificate_key /etc/ssl/mail/key.pem;
+  ssl_protocols TLSv1.2 TLSv1.3;
+  ssl_prefer_server_ciphers on;
+  ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
+  ssl_ecdh_curve X25519:X448:secp384r1:secp256k1;
+  ssl_session_cache shared:SSL:50m;
+  ssl_session_timeout 1d;
+  ssl_session_tickets off;
   index index.php index.html;
   client_max_body_size 0;
+  # Location: data/web
   root /web;
+  # Location: data/web/mysite.com
+  #root /web/mysite.com
   include /etc/nginx/conf.d/listen_plain.active;
   include /etc/nginx/conf.d/listen_ssl.active;
   server_name mysite.example.org;
+  server_tokens off;
 
+  # This allows acme to be validated even with a different web root
   location ^~ /.well-known/acme-challenge/ {
-    allow all;
     default_type "text/plain";
+    rewrite /.well-known/acme-challenge/(.*) /$1 break;
+    root /web/.well-known/acme-challenge/;
   }
 
   if ($scheme = http) {
@@ -28,18 +49,32 @@ server {
 }
 ```
 
+## New site with proxy to a remote location
+
 Another example with a reverse proxy configuration:
 
-``` hl_lines="9 21"
+```
+nano data/conf/nginx/my_custom_site.conf
+```
+
+``` hl_lines="16 28"
 server {
   ssl_certificate /etc/ssl/mail/cert.pem;
   ssl_certificate_key /etc/ssl/mail/key.pem;
+  ssl_protocols TLSv1.2 TLSv1.3;
+  ssl_prefer_server_ciphers on;
+  ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
+  ssl_ecdh_curve X25519:X448:secp384r1:secp256k1;
+  ssl_session_cache shared:SSL:50m;
+  ssl_session_timeout 1d;
+  ssl_session_tickets off;
   index index.php index.html;
   client_max_body_size 0;
   root /web;
   include /etc/nginx/conf.d/listen_plain.active;
   include /etc/nginx/conf.d/listen_ssl.active;
   server_name example.domain.tld;
+  server_tokens off;
 
   location ^~ /.well-known/acme-challenge/ {
     allow all;
@@ -61,8 +96,9 @@ server {
 }
 ```
 
+## Config expansion in mailcows Nginx
 
-The filename is not important, as long as the filename carries a .conf extension.
+The filename used for a new site is not important, as long as the filename carries a .conf extension.
 
 It is also possible to extend the configuration of the default file `site.conf` file:
 
@@ -70,7 +106,7 @@ It is also possible to extend the configuration of the default file `site.conf`
 nano data/conf/nginx/site.my_content.custom
 ```
 
-This filename does not need to have a ".conf" extension, but follows the pattern `site.*.custom`, where `*` is a custom name.
+This filename does not need to have a ".conf" extension but follows the pattern `site.*.custom`, where `*` is a custom name.
 
 If PHP is to be included in a custom site, please use the PHP-FPM listener on phpfpm:9002 or create a new listener in `data/conf/phpfpm/php-fpm.d/pools.conf`.
 
@@ -80,3 +116,4 @@ Restart Nginx (and PHP-FPM, if a new listener was created):
 docker-compose restart nginx-mailcow
 docker-compose restart php-fpm-mailcow
 ```
+

docs/u_e-postfix-attachment_size.md

@@ -1,4 +1,4 @@
-Open `data/conf/postfix/main.cf` and set the `message_size_limit` accordingly in bytes.
+Open `data/conf/postfix/extra.cf` and set the `message_size_limit` accordingly in bytes. See `main.cf` for the default value.
 
 Restart Postfix:
 

docs/u_e-postfix-postscreen_whitelist.md

@@ -1,3 +1,20 @@
 IPs can be removed from Postscreen and therefore _also_ from RBL checks in `data/conf/postfix/custom_postscreen_whitelist.cidr`.
 
 Postscreen does multiple checks to identify malicious senders. In most cases you want to whitelist an IP to exclude it from blacklist lookups.
+
+The format of the file is as follows:
+
+`CIDR   ACTION`
+
+Where CIDR is a single IP address or IP range in CIDR notation, and action is either "permit" or "reject".
+
+Example:
+
+```
+# Rules are evaluated in the order as specified.
+# Blacklist 192.168.* except 192.168.0.1.
+192.168.0.1          permit
+192.168.0.0/16       reject
+```
+
+The file is reloaded on the fly, postfix restart is not required.

docs/u_e-postfix-trust_networks.md

@@ -0,0 +1,39 @@
+By default mailcow considers **all networks as untrusted** excluding its own IPV4_NETWORK and IPV6_NETWORK scopes. Though it is reasonable in most cases, there may be circumstances that you need to loosen this restriction.
+
+By default mailcow uses `mynetworks_style = subnet` to determine internal subnets and leaves `mynetworks` unconfigured.
+
+If you decide to set `mynetworks`, Postfix ignores the mynetworks_style setting. This means you **have to** add the IPV4_NETWORK and IPV6_NETWORK scopes as well as loopback subnets manually!
+
+## Unauthenticated relaying
+
+!!! Warning
+    Incorrect setup of `mynetworks` will allow your server to be used as an open relay. If abused, this **will** affect your ability to send emails and can take some time to be resolved.
+
+### IPv4 hosts/subnets
+
+To add the subnet `192.168.2.0/24` to the trusted networks you may use the following configuration, depending on your IPV4_NETWORK and IPV6_NETWORK scopes:
+
+Edit `data/conf/postfix/extra.cf`:
+
+```
+mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 [fe80::]/10 172.22.1.0/24 [fd4d:6169:6c63:6f77::]/64 192.168.2.0/24
+```
+
+Run `docker-compose restart postfix-mailcow` to apply your new settings.
+
+### IPv6 hosts/subnets
+
+Adding IPv6 hosts is done the same as IPv4, however the subnet needs to be placed in brackets `[]` with the netmask appended.
+
+To add the subnet 2001:db8::/32 to the trusted networks you may use the following configuration, depending on your IPV4_NETWORK and IPV6_NETWORK scopes:
+
+Edit `data/conf/postfix/extra.cf`:
+
+``` 
+mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 [fe80::]/10 172.22.1.0/24 [fd4d:6169:6c63:6f77::]/64 [2001:db8::]/32
+```
+
+Run `docker-compose restart postfix-mailcow` to apply your new settings.
+
+!!! Info
+    More information about mynetworks can be found in the [Postfix documentation](http://www.postfix.org/postconf.5.html#mynetworks).

docs/u_e-rspamd.md

@@ -224,3 +224,19 @@ redis-cli -h redis DEL Q_LAST_NOTIFIED
 quarantine_notify.py
 ```
 
+## Increase history retention
+
+By default Rspamd keeps 1000 elements in the history.
+
+The history is stored compressed.
+
+It is recommended not to use a disproportionate high value here, try something along 5000 or 10000 and see how your server handles it:
+
+Edit `data/conf/rspamd/local.d/history_redis.conf`:
+
+```
+nrows = 1000; # change this value
+```
+
+Restart Rspamd afterwards: `docker-compose restart rspamd-mailcow`
+

docs/u_e-sogo.md

@@ -1,11 +1,81 @@
 
 SOGo is used for accessing your mails via a webbrowser, adding and sharing your contacts or calendars. For a more in-depth documentation on SOGo please visit its [own documentation](http://wiki.sogo.nu/).
 
-## Change Theme
+## Apply custom SOGo theme
-As of December 21 2018 we removed our custom themes due to complains about missing colors in some address book and calendar sections. Some other problems were still existing and would not be fixed in the near future (switching colors on login screen, for example).
+mailcow builds after 28 January 2021 can change SOGo's theme by editing `data/conf/sogo/custom-theme.js`.
+Please check the AngularJS Material [intro](https://material.angularjs.org/latest/Theming/01_introduction) and [documentation](https://material.angularjs.org/latest/Theming/03_configuring_a_theme) as well as the [material style guideline](https://material.io/archive/guidelines/style/color.html#color-color-palette) to learn how this works. 
 
-## Change Logo
+You can use the provided `custom-theme.js` as an example starting point by removing the comments.
-mailcow builds after 21 December 2018 can change SOGo's logo by replacing `data/conf/sogo/sogo-full.svg`.
+After you modified `data/conf/sogo/custom-theme.js` and made changes to your new SOGo theme you need to 
+
+1. edit `data/conf/sogo/sogo.conf` and append/set `SOGoUIxDebugEnabled = YES;`
+2. restart SOGo and Memcached containers by executing `docker-compose restart memcached-mailcow sogo-mailcow`.
+3. open SOGo in browser
+4. open browser developer console, usually shortcut is F12
+5. only if you use Firefox: write by hands in dev console `allow pasting` and press enter
+6. paste java script snipet in dev console:
+```
+copy([].slice.call(document.styleSheets)
+  .map(e => e.ownerNode)
+  .filter(e => e.hasAttribute('md-theme-style'))
+  .map(e => e.textContent)
+  .join('\n')
+)
+```
+7. open text editor and paste data from clipboard (Ctrl+V), you should get minified CSS, save it
+8. copy CSS file to mailcow server `data/conf/sogo/custom-theme.css`
+9. edit `data/conf/sogo/sogo.conf` and set `SOGoUIxDebugEnabled = NO;`
+10. append/create `docker-compose.override.yml` with:
+```
+version: '2.1'
+
+services:
+  sogo-mailcow:
+    volumes:
+      - ./data/conf/sogo/custom-theme.css:/usr/lib/GNUstep/SOGo/WebServerResources/css/theme-default.css:z
+```
+11. run `docker-compose up -d`
+12. run `docker-compose restart memcached-mailcow`
+
+## Reset to SOGo default theme
+1. checkout `data/conf/sogo/custom-theme.js` by executing `git fetch ; git checkout origin/master data/conf/sogo/custom-theme.js data/conf/sogo/custom-theme.js`
+2. find in `data/conf/sogo/custom-theme.js`:
+```
+// Apply new palettes to the default theme, remap some of the hues
+    $mdThemingProvider.theme('default')
+      .primaryPalette('green-cow', {
+        'default': '400',  // background color of top toolbars
+        'hue-1': '400',
+        'hue-2': '600',    // background color of sidebar toolbar
+        'hue-3': 'A700'
+      })
+      .accentPalette('green', {
+        'default': '600',  // background color of fab buttons and login screen
+        'hue-1': '300',    // background color of center list toolbar
+        'hue-2': '300',    // highlight color for selected mail and current day calendar
+        'hue-3': 'A700'
+      })
+      .backgroundPalette('frost-grey');
+```
+and replace it with:
+```
+    $mdThemingProvider.theme('default');
+```
+3. remove from `docker-compose.override.yml` volume mount in `sogo-mailcow`:
+```
+- ./data/conf/sogo/custom-theme.css:/usr/lib/GNUstep/SOGo/WebServerResources/css/theme-default.css:z
+```
+4. run `docker-compose up -d`
+5. run `docker-compose restart memcached-mailcow`
+
+## Change favicon
+mailcow builds after 31 January 2021 can change SOGo's favicon by replacing `data/conf/sogo/custom-favicon.ico` for SOGo and `data/web/favicon.png` for mailcow UI.
+**Note**: You can use `.png` favicons for SOGo by renaming them to `custom-favicon.ico`.
+For both SOGo and mailcow UI favicons you need use one of the standard dimensions: 16x16, 32x32, 64x64, 128x128 and 256x256.
+After you replaced said file you need to restart SOGo and Memcached containers by executing `docker-compose restart memcached-mailcow sogo-mailcow`.
+
+## Change logo
+mailcow builds after 21 December 2018 can change SOGo's logo by replacing or creating (if missing) `data/conf/sogo/sogo-full.svg`.
 After you replaced said file you need to restart SOGo and Memcached containers by executing `docker-compose restart memcached-mailcow sogo-mailcow`.
 
 ## Connect domains
@@ -34,5 +104,8 @@ Restart SOGo: `docker-compose restart sogo-mailcow`
 
 Edit `data/conf/sogo/sogo.conf` and **change** `SOGoPasswordChangeEnabled` to `NO`. Please do not add a new parameter.
 
-Run `docker-compose restart sogo-mailcow memcached-mailcow` to activate the changes.
+Run `docker-compose restart memcached-mailcow sogo-mailcow` to activate the changes.
 
+## Reset TOTP / Disable TOTP
+
+Run `docker-compose exec -u sogo sogo-mailcow sogo-tool user-preferences set defaults user@domain.tld SOGoTOTPEnabled '{"SOGoTOTPEnabled":0}'` from within the mailcow directory.

docs/u_e-unbound-fwd.md

@@ -1,7 +1,7 @@
 If you want or have to use an external DNS service, you can either set a forwarder in Unbound or copy an override file to define external DNS servers:
 
    !!! warning
-   Please do not use a public resolver like we did in the example above. Many - if not all - blacklist lookups will fail with public resolvers.
+   Please do not use a public resolver like we did in the example above. Many - if not all - blacklist lookups will fail with public resolvers, because blacklist server has limits on how much requests can be done from one IP and public resolvers usually reach this limits.
    **Important**: Only DNSSEC validating DNS services will work.
 
 ## Method A, Unbound
@@ -11,8 +11,8 @@ Edit `data/conf/unbound/unbound.conf` and append the following parameters:
 ```
 forward-zone:
   name: "."
-  forward-addr: 8.8.8.8 # NO NOT USE PUBLIC DNS SERVERS - JUST AN EXAMPLE
+  forward-addr: 8.8.8.8 # DO NOT USE PUBLIC DNS SERVERS - JUST AN EXAMPLE
-  forward-addr: 8.8.4.4 # NO NOT USE PUBLIC DNS SERVERS - JUST AN EXAMPLE
+  forward-addr: 8.8.4.4 # DO NOT USE PUBLIC DNS SERVERS - JUST AN EXAMPLE
 ```
 
 Restart Unbound:

docs/u_e-update-hooks.md

@@ -0,0 +1,10 @@
+It is possible to add pre- and post-update-hooks to the `update.sh` script that upgrades your whole mailcow installation.
+
+To do so, just add the corresponding bash script into your mailcow root directory:  
+
+* `pre_update_hook.sh` for commands that should run before the update
+* `post_update_hook.sh` for commands that should run after the update is completed
+
+Keep in mind that `pre_update_hook.sh` runs every time you call `update.sh` and `post_update_hook.sh` will only run if the update was successful and the script doesn't have to be re-run.
+
+The scripts will be run by bash, an interpreter (e.g. `#!/bin/bash`) as well as an execute permission flag ("+x") are not required.

docs/u_e-watchdog-thresholds.md

@@ -0,0 +1,80 @@
+Watchdog uses default values for all thresholds defined in `docker-compose.yml`.
+
+The default values will work for most setups.
+Example:
+```
+- NGINX_THRESHOLD=${NGINX_THRESHOLD:-5}
+- UNBOUND_THRESHOLD=${UNBOUND_THRESHOLD:-5}
+- REDIS_THRESHOLD=${REDIS_THRESHOLD:-5}
+- MYSQL_THRESHOLD=${MYSQL_THRESHOLD:-5}
+- MYSQL_REPLICATION_THRESHOLD=${MYSQL_REPLICATION_THRESHOLD:-1}
+- SOGO_THRESHOLD=${SOGO_THRESHOLD:-3}
+- POSTFIX_THRESHOLD=${POSTFIX_THRESHOLD:-8}
+- CLAMD_THRESHOLD=${CLAMD_THRESHOLD:-15}
+- DOVECOT_THRESHOLD=${DOVECOT_THRESHOLD:-12}
+- DOVECOT_REPL_THRESHOLD=${DOVECOT_REPL_THRESHOLD:-20}
+- PHPFPM_THRESHOLD=${PHPFPM_THRESHOLD:-5}
+- RATELIMIT_THRESHOLD=${RATELIMIT_THRESHOLD:-1}
+- FAIL2BAN_THRESHOLD=${FAIL2BAN_THRESHOLD:-1}
+- ACME_THRESHOLD=${ACME_THRESHOLD:-1}
+- RSPAMD_THRESHOLD=${RSPAMD_THRESHOLD:-5}
+- OLEFY_THRESHOLD=${OLEFY_THRESHOLD:-5}
+- MAILQ_THRESHOLD=${MAILQ_THRESHOLD:-20}
+- MAILQ_CRIT=${MAILQ_CRIT:-30}
+```
+
+To adjust them just add necessary threshold variables (e.g. `MAILQ_THRESHOLD=10`) to `mailcow.conf` and run `docker-compose up -d`.
+
+
+### Thresholds descriptions
+
+#### NGINX_THRESHOLD
+Notifies administrators if watchdog can not establish a connection to Nginx on port 8081 and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### UNBOUND_THRESHOLD
+Notifies administrators if Unbound can not resolve/valide external domains/DNSSEC and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### REDIS_THRESHOLD
+Notifies administrators if watchdog can not establish a connection to Redis on port 6379 and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### MYSQL_THRESHOLD
+Notifies administrators if watchdog can not establish a connection to MySQL or can not query a table and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### MYSQL_REPLICATION_THRESHOLD
+Notifies administrators if the MySQL replication fails.
+
+#### SOGO_THRESHOLD
+Notifies administrators if watchdog can not establish a connection to SOGo on port 20000 and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### POSTFIX_THRESHOLD
+Notifies administrators if watchdog can not sent a test mail via port 589 and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### CLAMD_THRESHOLD
+Notifies administrators if watchdog can not establish a connection to Clamd and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### DOVECOT_THRESHOLD
+Notifies administrators if watchdog fails with various tests with Dovecot container and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### DOVECOT_REPL_THRESHOLD
+Notifies administrators if the Dovecot replication fails.
+
+#### PHPFPM_THRESHOLD
+Notifies administrators if watchdog can not establish a connection to PHP-FPM on port 9001/9002 and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### RATELIMIT_THRESHOLD
+Notifies administrators if a ratelimit got hit.
+
+#### FAIL2BAN_THRESHOLD
+Notifies administrators if a fail2ban banned an IP.
+
+#### ACME_THRESHOLD
+Notifies administrators if something is wrong with the acme-mailcow container. You may check its logs.
+
+#### RSPAMD_THRESHOLD
+Notifies administrators if watchdog fails with various tests with Rspamd container and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### OLEFY_THRESHOLD
+Notifies administrators if watchdog can not establish a connection to olefy on port 10005 and it will restart the container automatically when issues were found and the threshold has been reached.
+
+#### MAILQ_CRIT and MAILQ_THRESHOLD
+Notifies administrators if number of emails in the postfix queue is greater then `MAILQ_CRIT` for period of `MAILQ_THRESHOLD * (60±30)` seconds.

docs/u_e-webmail-site.md

@@ -1,4 +1,4 @@
-**Edit**: TODO: This guide only applies to non SNI enabled configurations. The certificate path needs to be adjusted if SNI is enabled. Something like `ssl_certificate,key /etc/ssl/mail/webmail.example.org/cert.pem,key.pem;` will do. **But**: The certificate should be acquired **first** and only after the certificate exists a site config should be created. Nginx will fail to start if it cannot find the certificate and key.
+**IMPORTANT**: This guide only applies to non SNI enabled configurations. The certificate path needs to be adjusted if SNI is enabled. Something like `ssl_certificate,key /etc/ssl/mail/webmail.example.org/cert.pem,key.pem;` will do. **But**: The certificate should be acquired **first** and only after the certificate exists a site config should be created. Nginx will fail to start if it cannot find the certificate and key.
 
 To create a subdomain `webmail.example.org` and redirect it to SOGo, you need to create a **new** Nginx site. Take care of "CHANGE_TO_MAILCOW_HOSTNAME"!
 
@@ -14,7 +14,7 @@ server {
   include /etc/nginx/conf.d/listen_plain.active;
   include /etc/nginx/conf.d/listen_ssl.active;
   server_name webmail.example.org;
-
+  server_tokens off;
   location ^~ /.well-known/acme-challenge/ {
     allow all;
     default_type "text/plain";

mkdocs.yml

@@ -1,11 +1,17 @@
-site_name: 'mailcow: dockerized documentation'
+site_name: "mailcow: dockerized documentation"
 site_url: https://mailcow.github.io/mailcow-dockerized-docs/
-copyright: 'Copyright © 2020 André Peters'
+copyright: "Copyright © 2022 André Peters & Community"
 repo_name: mailcow/mailcow-dockerized
 repo_url: https://github.com/mailcow/mailcow-dockerized
 edit_uri: ../mailcow-dockerized-docs/edit/master/docs/
 remote_branch: gh-pages
-theme: material
+theme:
+  name: material
+  logo: images/logo.svg
+  favicon: images/favicon.png
+  features:
+    - navigation.top
+    - navigation.tracking
 markdown_extensions:
   - codehilite:
       guess_lang: true
@@ -20,119 +26,141 @@ markdown_extensions:
   - pymdownx.extra
   - footnotes
 nav:
-- 'Information & Support': 'index.md'
+  - 'Information & Support': 'index.md'
-- 'Prerequisites':
+  - 'Prerequisites':
-  - 'Prepare your system': 'prerequisite-system.md'
+    - 'Prepare your system': 'prerequisite-system.md'
-  - 'DNS setup': 'prerequisite-dns.md'
+    - 'DNS setup': 'prerequisite-dns.md'
-- 'Installation, Update & Migration':
+  - 'Installation, Update & Migration':
-  - 'Installation': 'i_u_m_install.md'
+    - 'Installation': 'i_u_m_install.md'
-  - 'Update': 'i_u_m_update.md'
+    - 'Update': 'i_u_m_update.md'
-  - 'Migration': 'i_u_m_migration.md'
+    - 'Migration': 'i_u_m_migration.md'
-- 'First Steps (optional)':
+    - 'Deinstallation': 'i_u_m_deinstall.md'
-  - 'Untrust RFC 1918': 'firststeps-rfc-1918.md'
+  - 'Post Installation Tasks':
-  - 'Advanced SSL': 'firststeps-ssl.md'
+    - 'Advanced SSL': 'firststeps-ssl.md'
-  - 'Rspamd UI': 'firststeps-rspamd_ui.md'
+    - 'Disable IPv6': 'firststeps-disable_ipv6.md'
-  - 'Reverse Proxy': 'firststeps-rp.md'
+    - 'DMARC Reporting': 'firststeps-dmarc_reporting.md'
-  - 'SNAT': 'firststeps-snat.md'
+    - 'IP bindings': 'firststeps-ip_bindings.md'
-  - 'Disable IPv6': 'firststeps-disable_ipv6.md'
+    - 'Local MTA on Docker host': 'firststeps-local_mta.md'
-  - 'Relayhosts': 'firststeps-relayhost.md'
+    - 'Logging': 'firststeps-logging.md'
-  - 'Logging': 'firststeps-logging.md'
+    - 'Reverse Proxy': 'firststeps-rp.md'
-  - 'Local MTA on Docker host': 'firststeps-local_mta.md'
+    - 'Rspamd UI': 'firststeps-rspamd_ui.md'
-  - 'Sync job migration': 'firststeps-sync_jobs_migration.md'
+    - 'SNAT': 'firststeps-snat.md'
-  - 'IP bindings': 'firststeps-ip_bindings.md'
+    - 'Sync job migration': 'firststeps-sync_jobs_migration.md'
-- 'Models':
+  - 'Models':
-  - 'Sender and receiver model': 'model-sender_rcv.md'
+    - 'ACL': 'model-acl.md'
-  - 'ACL': 'model-acl.md'
+    - 'Password hashing': 'model-passwd.md'
-- 'Debugging & Troubleshooting':
+    - 'Sender and receiver model': 'model-sender_rcv.md'
-    - 'Introduction': debug.md
+  - 'General Troubleshooting':
-    - 'Logs': 'debug-logs.md'
+    - 'Introduction': 'debug.md'
-    - 'Attach a Container': 'debug-attach_service.md'
-    - 'Reset Passwords (incl. SQL)': 'debug-reset_pw.md'
-    - 'Manual MySQL upgrade': 'debug-mysql_upgrade.md'
-    - 'Remove Persistent Data': 'debug-rm_volumes.md'
-    - 'Common Problems': 'debug-common_problems.md'
     - 'Admin login to SOGo': 'debug-admin_login_sogo.md'
-- 'Backup & Restore':
+    - 'Advanced: Find memory leaks in Rspamd': 'debug-asan_rspamd.md'
-  - 'Helper script':
+    - 'Attach a Container': 'debug-attach_service.md'
-      - 'Backup': 'b_n_r_backup.md'
+    - 'Common Problems': 'debug-common_problems.md'
-      - 'Restore': 'b_n_r_restore.md'
+    - 'Logs': 'debug-logs.md'
-  - 'Manually':
+    - 'Manual MySQL upgrade': 'debug-mysql_upgrade.md'
+    - 'Recover crashed Aria storage engine': 'debug-mysql_aria.md'
+    - 'Remove Persistent Data': 'debug-rm_volumes.md'
+    - 'Reset Passwords (incl. SQL)': 'debug-reset_pw.md'
+    - 'Reset TLS certificates': 'debug-reset_tls.md'
+  - 'Backup & Restore':
+    - 'Component backup':
+      - 'Backup': 'b_n_r-backup.md'
+      - 'Restore': 'b_n_r-restore.md'
+    - 'Cold-standby (rolling backup)': 'b_n_r-coldstandby.md'
+    - 'Manual backups':
       - 'Maildir': 'u_e-backup_restore-maildir.md'
-      - 'MySQL': 'u_e-backup_restore-mysql.md'
+      - 'MySQL (mysqldump)': 'u_e-backup_restore-mysql.md'
-- 'Usage & Examples':
+    - 'mailcow-internal backups':
-  - 'mailcow UI':
+      - 'Recover accidentally deleted data': 'b_n_r-accidental_deletion.md'
-      - 'Configuration': 'u_e-mailcow_ui-config.md'
+  - 'Manual/Guides/Examples':
+    - 'mailcow UI':
       - 'Blacklist / Whitelist': 'u_e-mailcow_ui-bl_wl.md'
+      - 'Configuration': 'u_e-mailcow_ui-config.md'
+      - 'CSS overrides': 'u_e-mailcow_ui-css.md'
       - 'Pushover': 'u_e-mailcow_ui-pushover.md'
       - 'Spamfilter': 'u_e-mailcow_ui-spamfilter.md'
-      - 'Temporary email aliases': 'u_e-mailcow_ui-spamalias.md'
       - 'Tagging': 'u_e-mailcow_ui-tagging.md'
+      - 'Temporary email aliases': 'u_e-mailcow_ui-spamalias.md'
       - 'Two-Factor Authentication': 'u_e-mailcow_ui-tfa.md'
-  - 'Postfix':
+      - 'WebAuthn / FIDO2': 'u_e-fido2.md'
+    - 'Postfix':
+      - 'Add trusted networks': 'u_e-postfix-trust_networks.md'
       - 'Custom transport maps': 'u_e-postfix-custom_transport.md'
-      - 'Whitelist IP in Postscreen': 'u_e-postfix-postscreen_whitelist.md'
       - 'Customize/Expand main.cf': 'u_e-postfix-extra_cf.md'
       - 'Disable Sender Addresses Verification': 'u_e-postfix-disable_sender_verification.md'
       - 'Max. message size (attachment size)': 'u_e-postfix-attachment_size.md'
+      - 'Relayhosts': 'u_e-postfix-relayhost.md'
       - 'Statistics with pflogsumm': 'u_e-postfix-pflogsumm.md'
-  - 'Unbound':
+      - 'Whitelist IP in Postscreen': 'u_e-postfix-postscreen_whitelist.md'
+    - 'Unbound':
       - 'Using an external DNS service': 'u_e-unbound-fwd.md'
-  - 'Dovecot':
+    - 'Dovecot':
+      - 'Customize/Expand dovecot.conf': 'u_e-dovecot-extra_conf.md'
       - 'Enable "any" ACL settings': 'u_e-dovecot-any_acl.md'
       - 'Expunge a Users mails': 'u_e-dovecot-expunge.md'
-      - 'Customize/Expand dovecot.conf': 'u_e-dovecot-extra_conf.md'
       - 'FTS (Solr)': 'u_e-dovecot-fts.md'
       - 'IMAP IDLE interval': 'u_e-dovecot-idle_interval.md'
       - 'Mail crypt': 'u_e-dovecot-mail-crypt.md'
       - 'More Examples with DOVEADM': 'u_e-dovecot-more.md'
-      - 'Move vmail volume': 'u_e-dovecot-vmail-volume.md'
+      - 'Move Maildir (vmail)': 'u_e-dovecot-vmail-volume.md'
       - 'Public folders': 'u_e-dovecot-public_folder.md'
       - 'Static master user': 'u_e-dovecot-static_master.md'
-  - 'Nginx': 
+      - 'Vacation replies for catchall addresses': 'u_e-dovecot-catchall_vacation.md'
-     - 'Custom sites': 'u_e-nginx.md'
+    - 'Nginx':
-     - 'Create subdomain webmail.example.org': 'u_e-webmail-site.md'
+      - 'Create subdomain webmail.example.org': 'u_e-webmail-site.md'
-  - 'Redis': 'u_e-redis.md'
+      - 'Custom sites': 'u_e-nginx.md'
-  - 'Rspamd': 'u_e-rspamd.md'
+    - 'Watchdog':
-  - 'SOGo': 'u_e-sogo.md'
+      - 'Thresholds': 'u_e-watchdog-thresholds.md'
-  - 'Docker':
+    - 'Redis': 'u_e-redis.md'
+    - 'Rspamd': 'u_e-rspamd.md'
+    - 'SOGo': 'u_e-sogo.md'
+    - 'Docker':
       - 'Customize Dockerfiles': 'u_e-docker-cust_dockerfiles.md'
       - 'Docker Compose Bash Completion': 'u_e-docker-dc_bash_compl.md'
-  - 'Why unbound?': 'u_e-why_unbound.md'
+    - 'Why unbound?': 'u_e-why_unbound.md'
-  - 'Autodiscover / Autoconfig': 'u_e-autodiscover_config.md'
+    - 'Autodiscover / Autoconfig': 'u_e-autodiscover_config.md'
-  - 'Redirect HTTP to HTTPS': 'u_e-80_to_443.md'
+    - 'Redirect HTTP to HTTPS': 'u_e-80_to_443.md'
-  - 'Adjust Service Configurations': 'u_e-change_config.md'
+    - 'Re-enable TLS 1.0 and TLS 1.1': 'u_e-reeanble-weak-protocols.md'
-  - 'Deinstall': 'u_e-deinstall.md'
+    - "Run scripts before and after updates": "u_e-update-hooks.md"
-  - 'Re-enable TLS 1.0 and TLS 1.1': 'u_e-reeanble-weak-protocols.md'
+  - 'Client Configuration':
-  - 'Mailpiler Integration': 'u_e-mailpiler-integration.md'
+    - 'Overview': 'client.md'
-  - 'Exchange Hybrid Setup': 'u_e-exchange-onprem.md'
+    - 'Android': 'client/client-android.md'
-- 'Client Configuration':
+    - 'Apple macOS / iOS': 'client/client-apple.md'
-  - 'Overview': 'client.md'
+    - 'eM Client': 'client/client-emclient.md'
-  - 'Android': 'client/client-android.md'
+    - 'KDE Kontact': 'client/client-kontact.md'
-  - 'Apple macOS / iOS': 'client/client-apple.md'
+    - 'Microsoft Outlook': 'client/client-outlook.md'
-  - 'eM Client': 'client/client-emclient.md'
+    - 'Mozilla Thunderbird': 'client/client-thunderbird.md'
-  - 'KDE Kontact': 'client/client-kontact.md'
+    - 'Windows Mail': 'client/client-windows.md'
-  - 'Microsoft Outlook': 'client/client-outlook.md'
+    - 'Windows Phone': 'client/client-windowsphone.md'
-  - 'Mozilla Thunderbird': 'client/client-thunderbird.md'
+    - 'Manual configuration': 'client/client-manual.md'
-  - 'Windows Mail': 'client/client-windows.md'
+  - 'Third party apps':
-  - 'Windows Phone': 'client/client-windowsphone.md'
+    - 'Borgmatic Backup': 'third_party-borgmatic.md'
-  - 'Manual configuration': 'client/client-manual.md'
+    - 'Exchange Hybrid Setup': 'third_party-exchange_onprem.md'
-- 'Third party apps':
+    - 'Gitea': 'third_party-gitea.md'
-  - 'SOGo Connector for Thunderbird': 'third_party-thunderbird.md'
+    - 'Gogs': 'third_party-gogs.md'
-  - 'Roundcube': 'third_party-roundcube.md'
+    - 'Mailman 3': 'third_party-mailman3.md'
-  - 'Portainer': 'third_party-portainer.md'
+    - 'Mailpiler Integration': 'third_party-mailpiler_integration.md'
-  - 'Gogs': 'third_party-gogs.md'
+    - 'Nextcloud': 'third_party-nextcloud.md'
-  - 'Gitea': 'third_party-gitea.md'
+    - 'Portainer': 'third_party-portainer.md'
-  - 'Nextcloud': 'third_party-nextcloud.md'
+    - 'Roundcube': 'third_party-roundcube.md'
-icon:
-  logo: 'images/logo.svg'
 extra:
   palette:
-    primary: 'indigo'
+    primary: "indigo"
-    accent: 'orange'
+    accent: "orange"
   social:
     - icon: fontawesome/solid/globe-americas
       link: https://mailcow.email
     - icon: fontawesome/brands/github-alt
       link: https://github.com/mailcow
-extra_css: [extra.css]
+    - icon: fontawesome/brands/twitter
-extra_javascript: [clients.js]
+      link: https://twitter.com/mailcow_email    
+extra_css: [ extra.css ]
+extra_javascript: [ clients.js ]
+plugins:
+  - search
+  - redirects:
+      redirect_maps:
+        # 'old': 'new'
+        'u_e-mailpiler-integration.md': 'third_party-mailpiler_integration.md'
+        'b_n_r_accidental_deletion.md': 'b_n_r-accidental_deletion.md'
+        'debug-reset-tls.md': 'debug-reset_tls.md'

requirements.txt

@@ -0,0 +1,3 @@
+mkdocs-material==8.1.7
+mkdocs-redirects==1.0.3
+pygments==2.11.2