diff --git a/docs/third_party/third_party-borgmatic.de.md b/docs/third_party/third_party-borgmatic.de.md new file mode 100644 index 000000000..cc8fcbb2a --- /dev/null +++ b/docs/third_party/third_party-borgmatic.de.md @@ -0,0 +1,230 @@ +# Borgmatic Backup + +## Einführung + +Borgmatic ist ein großartiger Weg, um Backups auf Ihrem Mailcow-Setup durchzuführen, da es Ihre Daten sicher verschlüsselt und extrem einfach zu +einzurichten. + +Aufgrund seiner Deduplizierungsfähigkeiten können Sie eine große Anzahl von Backups speichern, ohne große Mengen an Speicherplatz zu verschwenden. +Speicherplatz zu verschwenden. So können Sie Backups in sehr kurzen Abständen durchführen, um einen minimalen Datenverlust zu gewährleisten, wenn die Notwendigkeit besteht +Daten aus einer Sicherung wiederherzustellen. + +Dieses Dokument führt Sie durch den Prozess zur Aktivierung kontinuierlicher Backups für mailcow mit borgmatic. Die borgmatic +Funktionalität wird durch das [borgmatic Docker image von b3vis](https://github.com/b3vis/docker-borgmatic) bereitgestellt. Schauen Sie sich +die `README` in diesem Repository, um mehr über die anderen Optionen (wie z.B. Push-Benachrichtigungen) zu erfahren, die verfügbar sind. +Diese Anleitung behandelt nur die Grundlagen. + +## Einrichten von borgmatic + +### Erstellen oder ändern Sie `docker-compose.override.yml` + +Im mailcow-dockerized Stammverzeichnis erstellen oder bearbeiten Sie `docker-compose.override.yml` und fügen Sie die folgende +Konfiguration ein: +```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: +``` + +Stellen Sie sicher, dass Sie die `BORG_PASSPHRASE` in eine sichere Passphrase Ihrer Wahl ändern. + +Aus Sicherheitsgründen mounten wir das maildir als schreibgeschützt. Wenn Sie später Daten wiederherstellen wollen, müssen Sie das +müssen Sie das `ro`-Flag entfernen, bevor Sie die Daten wiederherstellen. Dies wird im Abschnitt über die Wiederherstellung von Backups beschrieben. + +### Erstellen Sie `data/conf/borgmatic/etc/config.yaml` + +Als nächstes müssen wir die borgmatic-Konfiguration erstellen. + +```shell +source mailcow.conf +cat < 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 +``` + +Das Erstellen der Datei auf diese Weise stellt sicher, dass die korrekten MySQL-Zugangsdaten aus `mailcow.conf` übernommen werden. + +Diese Datei ist ein minimales Beispiel für die Verwendung von borgmatic mit einem Konto `user` beim Cloud-Speicheranbieter `rsync.net` für +ein Repository namens `mailcow` (siehe `repositories` Einstellung). Es wird sowohl das maildir als auch die MySQL-Datenbank sichern, was alles ist +was alles ist, was Sie brauchen, um Ihr mailcow Setup nach einem Vorfall wiederherzustellen. Die Aufbewahrungseinstellungen werden ein Archiv für +jede Stunde der letzten 24 Stunden, eines pro Tag der Woche, eines pro Woche des Monats und eines pro Monat des letzten halben +Jahr. + +Schauen Sie in der [borgmatic Dokumentation](https://torsion.org/borgmatic/) nach, wie Sie andere Arten von Repositories oder +Konfigurationsoptionen. Wenn Sie ein lokales Dateisystem als Backup-Ziel verwenden, stellen Sie sicher, dass Sie es in den +Container einbinden. Der Container definiert zu diesem Zweck ein Volume namens `/mnt/borg-repository`. + +!!! note + Wenn Sie rsync.net nicht verwenden, können Sie wahrscheinlich das Element `remote_path` aus Ihrer Konfiguration streichen. + +### Erstellen Sie einen crontab + +Erstellen Sie eine neue Textdatei in `data/conf/borgmatic/etc/crontab.txt` mit folgendem Inhalt: + +``` +14 * * * * PATH=$PATH:/usr/bin /usr/bin/borgmatic --stats -v 0 2>&1 +``` + +Diese Datei erwartet eine crontab-Syntax. Das hier gezeigte Beispiel veranlasst das Backup, jede Stunde um 14 Minuten nach +nach der vollen Stunde auszuführen und am Ende einige nette Statistiken zu protokollieren. + +### SSH-Schlüssel in Ordner ablegen + +Legen Sie die SSH-Schlüssel, die Sie für entfernte Repository-Verbindungen verwenden wollen, in `data/conf/borgmatic/ssh` ab. OpenSSH erwartet die +übliche `id_rsa`, `id_ed25519` oder ähnliches in diesem Verzeichnis zu finden. Stellen Sie sicher, dass die Datei `chmod 600` ist und nicht von der Welt gelesen werden kann +oder OpenSSH wird sich weigern, den SSH-Schlüssel zu benutzen. + +### Den Container hochfahren + +Für den nächsten Schritt müssen wir den Container in einem konfigurierten Zustand hochfahren und laufen lassen. Um das zu tun, führen Sie aus: + +```shell +docker-compose up -d +``` + +## Wiederherstellung von einem Backup + +Das Wiederherstellen eines Backups setzt voraus, dass Sie mit einer neuen Installation von mailcow beginnen, und dass Sie derzeit keine +keine benutzerdefinierten Daten in ihrem maildir oder ihrer mailcow Datenbank. + +### Wiederherstellen von maildir + +!!! warning + Dies wird Dateien in Ihrem maildir überschreiben! Führen Sie dies nicht aus, es sei denn, Sie beabsichtigen tatsächlich, Mail + Dateien von einem Backup wiederherzustellen. + +!!! note "Wenn Sie SELinux im Erzwingungsmodus verwenden" + Wenn Sie mailcow auf einem Host mit SELinux im Enforcing-Modus verwenden, müssen Sie es vorübergehend deaktivieren während + während der Extraktion des Archivs vorübergehend deaktivieren, da das Mailcow-Setup das vmail-Volumen als privat kennzeichnet, das ausschließlich dem Dovecot-Container + ausschließlich. SELinux wird (berechtigterweise) jeden anderen Container, wie z.B. den borgmatic Container, daran hindern, auf + dieses Volume zu schreiben. + +Bevor Sie eine Wiederherstellung durchführen, müssen Sie das vmail-Volume in `docker-compose.override.yml` beschreibbar machen, indem Sie das +das `ro`-Flag aus dem Volume entfernen. +Dann können Sie den folgenden Befehl verwenden, um das Maildir aus einem Backup wiederherzustellen: + +```shell +docker-compose exec borgmatic-mailcow borgmatic extract --path mnt/source --archive latest +``` + +Alternativ können Sie auch einen beliebigen Archivnamen aus der Liste der Archive angeben (siehe +[Auflistung aller verfügbaren Archive](#auflistung-aller-verfügbaren-archive)) + +### MySQL wiederherstellen + +!!! warning + Die Ausführung dieses Befehls löscht und erstellt die mailcow-Datenbank neu! Führen sie diesen Befehl nicht aus, es sei denn sie beabsichtigen, die mailcow-Datenbank von einem Backup wiederherzustellen. + +Um die MySQL-Datenbank aus dem letzten Archiv wiederherzustellen, verwenden Sie diesen Befehl: + +```shell +docker-compose exec borgmatic-mailcow borgmatic restore --archive latest +``` + +Alternativ können Sie auch einen beliebigen Archivnamen aus der Liste der Archive angeben (siehe +[Auflistung aller verfügbaren Archive](#auflistung-aller-verfügbaren-archive)) + +### Nach der Wiederherstellung + +Nach der Wiederherstellung müssen Sie mailcow neu starten. Wenn Sie den SELinux-Erzwingungsmodus deaktiviert haben, wäre jetzt ein guter Zeitpunkt, um +ihn wieder zu aktivieren. + +Um mailcow neu zu starten, verwenden Sie den folgenden Befehl: + +```shell +docker-compose down && docker-compose up -d +``` + +Wenn Sie SELinux verwenden, werden dadurch auch alle Dateien in Ihrem vmail-Volume neu benannt. Seien Sie geduldig, denn dies kann +eine Weile dauern kann, wenn Sie viele Dateien haben. + +## Nützliche Befehle + +### Manueller Archivierungslauf (mit Debugging-Ausgabe) + +```shell +docker-compose exec borgmatic-mailcow borgmatic -v 2 +``` + +### Auflistung aller verfügbaren Archive + +```shell +docker-compose exec borgmatic-mailcow borgmatic list +``` + +### Sperre aufheben + +Wenn borg während eines Archivierungslaufs unterbrochen wird, hinterlässt es eine veraltete Sperre, die gelöscht werden muss, bevor +neue Operationen durchgeführt werden können: + +```shell +docker-compose exec borgmatic-mailcow borg break-lock user@rsync.net:mailcow +``` + +Wobei `user@rsync.net:mailcow` die URI zu Ihrem Repository ist. + +Jetzt wäre ein guter Zeitpunkt, einen manuellen Archivierungslauf durchzuführen, um sicherzustellen, dass er erfolgreich durchgeführt werden kann. + +### Exportieren von Schlüsseln + +Wenn Sie eine der `Schlüsseldatei'-Methoden zur Verschlüsselung verwenden, **MÜSSEN** Sie sich selbst um die Sicherung der Schlüsseldateien kümmern. Die +Schlüsseldateien werden erzeugt, wenn Sie das Repository initialisieren. Die `repokey`-Methoden speichern die Schlüsseldatei innerhalb des +Repository, so dass eine manuelle Sicherung nicht so wichtig ist. + +Beachten Sie, dass Sie in beiden Fällen auch die Passphrase haben müssen, um die Archive zu entschlüsseln. + +Um die Schlüsseldatei zu holen, führen Sie aus: + +```shell +docker-compose exec borgmatic-mailcow borg key export --paper user@rsync.net:mailcow +``` + +Wobei `user@rsync.net:mailcow` die URI zu Ihrem Repository ist. \ No newline at end of file diff --git a/docs/third_party/third_party-borgmatic.en.md b/docs/third_party/third_party-borgmatic.en.md new file mode 100644 index 000000000..5d988dbb7 --- /dev/null +++ b/docs/third_party/third_party-borgmatic.en.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 < 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. \ No newline at end of file diff --git a/docs/third_party/third_party-exchange_onprem.de.md b/docs/third_party/third_party-exchange_onprem.de.md new file mode 100644 index 000000000..a31d3ca45 --- /dev/null +++ b/docs/third_party/third_party-exchange_onprem.de.md @@ -0,0 +1,43 @@ +Die Verwendung von Microsoft Exchange in einem hybriden Setup ist mit mailcow möglich. Mit diesem Setup können Sie Postfächer auf Ihrer mailcow hinzufügen und trotzdem [Exchange Online Protection](https://docs.microsoft.com/microsoft-365/security/office-365-security/exchange-online-protection-overview?view=o365-worldwide) nutzen. +**Alle Postfächer, die in Exchange eingerichtet sind, erhalten ihre Mails wie gewohnt**, während mit dem hybriden Ansatz zusätzliche Postfächer in mailcow ohne weitere Konfiguration eingerichtet werden können. + +Dieses Setup ist sehr praktisch, wenn Sie die [Office 365 Sicherheitsvorgaben](https://docs.microsoft.com/azure/active-directory/fundamentals/concept-fundamentals-security-defaults) aktiviert haben und Anwendungen von Drittanbietern sich nicht mehr in Ihre Postfächer mit einer der [unterstützten Methoden](https://docs.microsoft.com/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365) einloggen können. + + +## Voraussetzungen +- Der mx Record Ihrer Domain muss auf den Exchange Mail Service zeigen. Melden Sie sich in Ihrem Admin-Center an und suchen Sie in den DNS-Einstellungen Ihrer Domäne nach Ihrer personalisierten Gateway-Domäne. Sie sollte wie folgt aussehen: `contoso-com.mail.protection.outlook.com`. Wenden Sie sich an Ihren Domainregistrator, um weitere Informationen zur Änderung des mx-Eintrags zu erhalten. +- Die Domäne, für die Sie zusätzliche Postfächer haben möchten, muss in Exchange als "Interne Relay-Domäne" eingerichtet werden. + 1. Melden Sie sich bei Ihrem [Exchange Admin Center](https://admin.exchange.microsoft.com) an. + 2. Wählen Sie den Bereich "Mailflow" und klicken Sie auf "Akzeptierte Domänen". + 3. Wählen Sie die Domäne aus und schalten Sie sie von "autorisiert" auf "internes Relais" um. + + +## Einrichten der Mailcow +Ihre Mailcow muss alle Mails an Ihren personalisierten Exchange Host weiterleiten. Es ist die gleiche Host-Adresse, die wir bereits für den mx Record gesucht haben. + +1. Fügen Sie die Domain zu Ihrer Mailcow hinzu +2. [Fügen Sie Ihre personalisierte Exchange Host Adresse als relayhost hinzu](../manual-guides/Postfix/u_e-postfix-relayhost.md) +3. Fügen Sie Ihre personalisierte Exchange Host Adresse als Weiterleitungshost hinzu, um alle weitergeleiteten Mails von Exchange bedingungslos zu akzeptieren. (Admin > Konfiguration & Details > Konfigurations-Dropdown > Weiterleitungshosts) +4. Gehen Sie zu den Domäneneinstellungen und wählen Sie den neu hinzugefügten Host in der Dropdown-Liste "Absenderabhängige Transporte" aus. Aktivieren Sie die Weiterleitung, indem Sie die Kontrollkästchen "Diese Domäne weiterleiten", "Alle Empfänger weiterleiten" und "Nur nicht vorhandene Postfächer weiterleiten" aktivieren. + +!!! info + Von nun an wird Ihre Mailcow alle Mails akzeptieren, die von Exchange weitergeleitet werden. Die **Eingangsfilterung und damit das neuronale Lernen Ihrer Kuh wird nicht mehr funktionieren**. Da alle Mails über Exchange geroutet werden, wird der [Filterungsprozess dort abgewickelt](https://docs.microsoft.com/exchange/antispam-and-antimalware/antispam-and-antimalware?view=exchserver-2019). + + +## Connectors in Exchange einrichten +Der gesamte Mailverkehr läuft nun über Exchange. Zu diesem Zeitpunkt filtert der Exchange Online-Schutz bereits alle ein- und ausgehenden Mails. Jetzt müssen wir zwei Konnektoren einrichten, um eingehende Mails von unserem Exchange Service an die Mailcow weiterzuleiten und einen weiteren, um Mails zuzulassen, die von der Mailcow an unseren Exchange Service weitergeleitet werden. Sie können der [offiziellen Anleitung von Microsoft] folgen (https://docs.microsoft.com/exchange/mail-flow-best-practices/use-connectors-to-configure-mail-flow/set-up-connectors-to-route-mail#2-set-up-a-connector-from-microsoft-365-or-office-365-to-your-email-server). + +!!! warning + Für den Connector, der die Mails von Ihrer Mailcow zu Exchange weiterleitet, bietet Microsoft zwei Möglichkeiten der Authentifizierung an. Der empfohlene Weg ist die Verwendung eines tls-Zertifikats, das mit einem Subject-Namen konfiguriert ist, der mit einer akzeptierten Domäne in Exchange übereinstimmt. Andernfalls müssen Sie die Authentifizierung mit der statischen IP-Adresse Ihrer Mailcow wählen. + +## Validierung +Der einfachste Weg, die hybride Einrichtung zu überprüfen, ist das Senden einer Mail aus dem Internet an eine Mailbox, die nur auf der Mailcow existiert und andersherum. + +### Allgemeine Probleme +- Die Validierung des Connectors von Exchange zu Ihrer Mailcow schlug fehl mit `550 5.1.10 RESOLVER.ADR.RecipientNotFound; Recipient test@contoso.com not found by SMTP address lookup` +**Mögliche Lösung:** Ihre Domäne ist nicht als "internes Relay" eingerichtet. Exchange kann daher den Empfänger nicht finden. +- Mails, die von der Mailcow an eine Mailbox im Internet gesendet werden, können nicht zugestellt werden. Non Delivery Report mit Fehler `550 5.7.64 TenantAttribution; Relay Access Denied` +**Mögliche Lösung:** Die Authentifizierungsmethode ist fehlgeschlagen. Stellen Sie sicher, dass der Betreff des Zertifikats mit einer akzeptierten Domäne in Exchange übereinstimmt. Versuchen Sie stattdessen die Authentifizierung über eine statische IP. + +Microsoft-Anleitung für die Einrichtung des Connectors und zusätzliche Anforderungen: https://docs.microsoft.com/exchange/mail-flow-best-practices/use-connectors-to-configure-mail-flow/set-up-connectors-to-route-mail#prerequisites-for-your-on-premises-email-environment + diff --git a/docs/third_party/third_party-exchange_onprem.en.md b/docs/third_party/third_party-exchange_onprem.en.md new file mode 100644 index 000000000..669f922b2 --- /dev/null +++ b/docs/third_party/third_party-exchange_onprem.en.md @@ -0,0 +1,42 @@ +Using Microsoft Exchange in a hybrid setup is possible with mailcow. With this setup you can add mailboxes on your mailcow and still use [Exchange Online Protection](https://docs.microsoft.com/microsoft-365/security/office-365-security/exchange-online-protection-overview?view=o365-worldwide). +**All mailboxes setup in Exchange will receive their mails as usual**, while with the hybrid approach additional Mailboxes can be setup in mailcow without any further configuration. + +This setup becomes very handy if you have enabled the [Office 365 security defaults](https://docs.microsoft.com/azure/active-directory/fundamentals/concept-fundamentals-security-defaults) and third party applications can no longer login into your mailboxes by any of the [supported methods](https://docs.microsoft.com/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365). + + +## Requirements +- The mx Record of your domain needs to point at the Exchange mail service. Log into your Admin center and look out for the dns settings of your domain to find your personalized gateway domain. It should look like this `contoso-com.mail.protection.outlook.com`. Contact your domain registrant to get further information on how to change mx record. +- The domain you want to have additional mailboxes for must be setup as `internal relay domain` in Exchange. + 1. Log in to your [Exchange Admin Center](https://admin.exchange.microsoft.com) + 2. Select the `mail flow` pane and click on `accepted domains` + 3. Select the domain and switch it from `authorative` to `internal relay` + + +## Set up the mailcow +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](../manual-guides/Postfix/u_e-postfix-relayhost.md) +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 + +!!! info + From now on your mailcow will accept all mails relayed from Exchange. The **inbound filtering and so the neural learning of your cow will no longer work**. Because all mails are routed through Exchange the [filtering process is handled there](https://docs.microsoft.com/exchange/antispam-and-antimalware/antispam-and-antimalware?view=exchserver-2019). + + +## Set up Connectors in Exchange +All mail traffic now goes through Exchange. At this point the Exchange Online Protection already filters all incoming and outgoing mails. Now we need to set up two connectors to relay incoming mails from our Exchange Service to the mailcow and another one to allow mails relayed from the mailcow to our exchange service. You can follow the [official guide from Microsoft](https://docs.microsoft.com/exchange/mail-flow-best-practices/use-connectors-to-configure-mail-flow/set-up-connectors-to-route-mail#2-set-up-a-connector-from-microsoft-365-or-office-365-to-your-email-server). + +!!! warning + For the connector that handles mails from your mailcow to Exchange Microsoft offers two ways of authenticating it. The recommended way is to use a tls certificate configured with a subject name that matches an accepted domain in Exchange. Otherwise you need to choose authentication with the static ip address of your mailcow. + +## Validating +The easiest way to validate the hybrid setup is by sending a mail from the internet to a mailbox that only exists on the mailcow and vice versa. + +### Common Issues +- The connector validation from Exchange to your mailcow failed with `550 5.1.10 RESOLVER.ADR.RecipientNotFound; Recipient test@contoso.com not found by SMTP address lookup` +**Possible Solution:** Your domain is not set up as `internal relay`. Exchange therefore cannot find the recipient +- Mails sent from the mailcow to a mailbox in the internet cannot be sent. Non Delivery Report with error `550 5.7.64 TenantAttribution; Relay Access Denied` +**Possible Solution:** The authentication method failed. Make sure the certificate subject matches an accepted domain in Exchange. Try authenticating by static ip instead. + +Microsoft Guide for the connector setup and additional requirements: https://docs.microsoft.com/exchange/mail-flow-best-practices/use-connectors-to-configure-mail-flow/set-up-connectors-to-route-mail#prerequisites-for-your-on-premises-email-environment \ No newline at end of file diff --git a/docs/third_party/third_party-gitea.de.md b/docs/third_party/third_party-gitea.de.md new file mode 100644 index 000000000..5e0748304 --- /dev/null +++ b/docs/third_party/third_party-gitea.de.md @@ -0,0 +1,55 @@ +Mit der Fähigkeit von Gitea, sich über SMTP zu authentifizieren, ist es trivial, es mit mailcow zu integrieren. Es sind nur wenige Änderungen erforderlich: + +1\. Öffnen Sie `docker-compose.override.yml` und fügen Sie Gitea hinzu: + +``` +version: '2.1' +services: + + gitea-mailcow: + image: gitea/gitea:1 + volumes: + - ./data/gitea:/data + networks: + mailcow-network: + aliases: + - gitea + ports: + - "${GITEA_SSH_PORT:-127.0.0.1:4000}:22" +``` + +2\. Erstellen Sie `data/conf/nginx/site.gitea.custom`, fügen Sie folgendes hinzu: +``` +location /gitea/ { + proxy_pass http://gitea:3000/; +} +``` + +3\. Öffne `mailcow.conf` und definiere den Port Bind, den Gitea für SSH verwenden soll. Beispiel: + +``` +GITEA_SSH_PORT=127.0.0.1:4000 +``` + +5\. Führen Sie `docker-compose up -d` aus, um den Gitea-Container hochzufahren und führen Sie anschließend `docker-compose restart nginx-mailcow` aus. + +6\. Wenn Sie mailcow zu https gezwungen haben, führen Sie Schritt 9 aus und starten Sie gitea mit `docker-compose restart gitea-mailcow` neu. Fahren Sie mit Schritt 7 fort (Denken Sie daran, https anstelle von http zu verwenden, `https://mx.example.org/gitea/` + +7\. Öffnen Sie `http://${MAILCOW_HOSTNAME}/gitea/`, zum Beispiel `http://mx.example.org/gitea/`. Für die Datenbankdetails stellen Sie `mysql` als Datenbankhost ein. Verwenden Sie den in mailcow.conf gefundenen Wert von DBNAME als Datenbankname, DBUSER als Datenbankbenutzer und DBPASS als Datenbankpasswort. + +8\. Sobald die Installation abgeschlossen ist, loggen Sie sich als Administrator ein und setzen Sie "Einstellungen" -> "Autorisierung" -> "SMTP aktivieren". SMTP-Host sollte `postfix` mit Port `587` sein, setzen Sie `Skip TLS Verify`, da wir ein nicht gelistetes SAN verwenden ("postfix" ist höchstwahrscheinlich nicht Teil Ihres Zertifikats). + +9\. Erstellen Sie `data/gitea/gitea/conf/app.ini` und setzen Sie die folgenden Werte. Sie können [gitea cheat sheet, leider bisher nur in Englisch verfügbar](https://docs.gitea.io/en-us/config-cheat-sheet/) für deren Bedeutung und andere mögliche Werte konsultieren. + +``` +[server] +SSH_LISTEN_PORT = 22 +# Für GITEA_SSH_PORT=127.0.0.1:4000 in mailcow.conf, setzen: +SSH_DOMAIN = 127.0.0.1 +SSH_PORT = 4000 +# Für MAILCOW_HOSTNAME=mx.example.org in mailcow.conf (und Standard-Ports für HTTPS), setzen: +ROOT_URL = https://mx.example.org/gitea/ +``` + +10\. Starten Sie gitea neu mit `docker-compose restart gitea-mailcow`. Ihre Nutzer sollten in der Lage sein, sich mit von mailcow verwalteten Konten anzumelden. + diff --git a/docs/third_party/third_party-gitea.en.md b/docs/third_party/third_party-gitea.en.md new file mode 100644 index 000000000..62cc81878 --- /dev/null +++ b/docs/third_party/third_party-gitea.en.md @@ -0,0 +1,54 @@ +With Gitea' ability to authenticate over SMTP it is trivial to integrate it with mailcow. Few changes are needed: + +1\. Open `docker-compose.override.yml` and add gitea: + +``` +version: '2.1' +services: + + gitea-mailcow: + image: gitea/gitea:1 + volumes: + - ./data/gitea:/data + networks: + mailcow-network: + aliases: + - gitea + ports: + - "${GITEA_SSH_PORT:-127.0.0.1:4000}:22" +``` + +2\. Create `data/conf/nginx/site.gitea.custom`, add: +``` +location /gitea/ { + proxy_pass http://gitea:3000/; +} +``` + +3\. Open `mailcow.conf` and define the binding you want gitea to use for SSH. Example: + +``` +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\. 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\. 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\. 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] +SSH_LISTEN_PORT = 22 +# For GITEA_SSH_PORT=127.0.0.1:4000 in mailcow.conf, set: +SSH_DOMAIN = 127.0.0.1 +SSH_PORT = 4000 +# For MAILCOW_HOSTNAME=mx.example.org in mailcow.conf (and default ports for HTTPS), set: +ROOT_URL = https://mx.example.org/gitea/ +``` + +10\. Restart gitea with `docker-compose restart gitea-mailcow`. Your users should be able to login with mailcow managed accounts. \ No newline at end of file diff --git a/docs/third_party/third_party-mailman3.de.md b/docs/third_party/third_party-mailman3.de.md new file mode 100644 index 000000000..12e479c41 --- /dev/null +++ b/docs/third_party/third_party-mailman3.de.md @@ -0,0 +1,325 @@ +# Installation von mailcow und Mailman 3 auf der Basis von dockerisierten Versionen + +!!! info + Diese Anleitung ist eine Kopie von [dockerized-mailcow-mailman](https://github.com/g4rf/dockerized-mailcow-mailman). Bitte posten Sie Probleme, Fragen und Verbesserungen in den [issue tracker](https://github.com/g4rf/dockerized-mailcow-mailman/issues) dort. + +!!! warning + mailcow ist nicht verantwortlich für Datenverlust, Hardwareschäden oder kaputte Tastaturen. Diese Anleitung kommt ohne jegliche Garantie. Macht Backups bevor ihr anfangt, **Kein Backup kein Mitleid!** + +## Einleitung + +Diese Anleitung zielt darauf ab, [mailcow-dockerized](https://github.com/mailcow/mailcow-dockerized) mit [docker-mailman] (https://github.com/maxking/docker-mailman) zu installieren und zu konfigurieren und einige nützliche Skripte bereitzustellen. Eine wesentliche Bedingung ist, dass *mailcow* und *Mailman* in ihren eigenen Installationen für unabhängige Updates erhalten bleiben. + +Es gibt einige Anleitungen und Projekte im Internet, aber sie sind nicht auf dem neuesten Stand und/oder unvollständig in der Dokumentation oder Konfiguration. Diese Anleitung basiert auf der Arbeit von: + +- [mailcow-mailman3-dockerized](https://github.com/Shadowghost/mailcow-mailman3-dockerized) von [Shadowghost](https://github.com/Shadowghost) +- [mailman-mailcow-integration](https://gitbucket.pgollor.de/docker/mailman-mailcow-integration) + +Nach Beendigung dieser Anleitung werden [mailcow-dockerized](https://github.com/mailcow/mailcow-dockerized) und [docker-mailman](https://github.com/maxking/docker-mailman) laufen und *Apache* als Reverse-Proxy wird die Web-Frontends bedienen. + +Das verwendete Betriebssystem ist ein *Ubuntu 20.04 LTS*. + +## Installation + +Diese Anleitung basiert auf verschiedenen Schritten: + +1. DNS-Einrichtung +1. Installieren Sie *Apache* als Reverse Proxy +1. Beziehen Sie SSL-Zertifikate mit *Let's Encrypt*. +1. Installieren Sie *mailcow* mit *Mailman* Integration +1. Installieren Sie *Mailman*. +1. 🏃 Ausführen + +### DNS-Einrichtung + +Der größte Teil der Konfiguration ist in *mailcow*s [DNS Konfiguration](../prerequisite/prerequisite-dns.md) enthalten. Nachdem diese Einrichtung abgeschlossen ist, fügen Sie eine weitere Subdomain für *Mailman* hinzu, z.B. `lists.example.org`, die auf denselben Server zeigt: + +``` +# Name Typ Wert +lists IN A 1.2.3.4 +lists IN AAAA dead:beef +``` + +### Installieren Sie *Apache* als Reverse Proxy + +Installieren Sie *Apache*, z.B. mit dieser Anleitung von *Digital Ocean*: [How To Install the Apache Web Server on Ubuntu 20.04 (Englisch)](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-ubuntu-20-04). + +Aktivieren Sie bestimmte *Apache* Module (als *root* oder *sudo*): + +``` +a2enmod rewrite proxy proxy_http headers ssl wsgi proxy_uwsgi http2 +``` + +Möglicherweise müssen Sie weitere Pakete installieren, um diese Module zu erhalten. Dieses [PPA](https://launchpad.net/~ondrej/+archive/ubuntu/apache2) von *Ondřej Surý* könnte Ihnen helfen. + +#### vHost-Konfiguration + +Kopieren Sie die [mailcow.conf](https://github.com/g4rf/dockerized-mailcow-mailman/tree/master/apache/mailcow.conf) und die [mailman.conf](https://github.com/g4rf/dockerized-mailcow-mailman/tree/master/apache/mailman.conf) in den *Apache* conf Ordner `sites-available` (z.B. unter `/etc/apache2/sites-available`). + +Änderung in `mailcow.conf`: +- `MAILCOW_HOSTNAME` zu Ihrem **MAILCOW_HOSTNAME** + +Änderung in `mailman.conf`: +- `MAILMAN_DOMAIN` in Ihre *Mailman*-Domain (z.B. `Lists.example.org`) + +**Aktivieren Sie die Konfiguration noch nicht, da die ssl-Zertifikate und Verzeichnisse noch fehlen. + +### Beziehen Sie SSL-Zertifikate mit *Let's Encrypt*. + +Prüfen Sie, ob Ihre DNS-Konfiguration über das Internet verfügbar ist und auf die richtigen IP-Adressen zeigt, z.B. mit [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 + +Installieren Sie [certbot](https://certbot.eff.org/) (als *root* oder *sudo*): + +``` +apt install certbot +``` + +Holen Sie sich die gewünschten Zertifikate (als *root* oder *sudo*): + +``` +certbot certonly -d mailcow_HOSTNAME +certbot certonly -d MAILMAN_DOMAIN +``` + +### Installieren Sie *mailcow* mit *Mailman* Integration + +#### Installieren Sie mailcow + +Folgen Sie der [mailcow installation](../i_u_m/i_u_m_install.md). **Schritt 5 auslassen und nicht mit `docker-compose` starten!** + +#### Mailcow konfigurieren + +Dies ist auch **Schritt 4** in der offiziellen *mailcow-Installation* (`nano mailcow.conf`). Passen Sie also Ihre Bedürfnisse an und ändern Sie die folgenden Variablen: + +``` +HTTP_PORT=18080 # verwenden Sie nicht 8080, da mailman es braucht +HTTP_BIND=127.0.0.1 # +HTTPS_PORT=18443 # Sie können 8443 verwenden +HTTPS_BIND=127.0.0.1 # # HTTPS_BIND=127.0.0.1 + +SKIP_LETS_ENCRYPT=y # Der Reverse Proxy wird die SSL-Verifizierung durchführen + +SNAT_TO_SOURCE=1.2.3.4 # ändern Sie dies in Ihre IPv4 +SNAT6_TO_SOURCE=dead:beef # Ändern Sie dies in Ihre globale IPv6 +``` + +#### Mailman-Integration hinzufügen + +Erstelle die Datei `/opt/mailcow-dockerized/docker-compose.override.yml` (z.B. mit `nano`) und füge die folgenden Zeilen hinzu: + +``` +version: '2.1' + +services: + postfix-mailcow: + volumes: + - /opt/mailman:/opt/mailman + networks: + - docker-mailman_mailman + +networks: + docker-mailman_mailman: + external: true +``` + +Das zusätzliche Volume wird von *Mailman* verwendet, um zusätzliche Konfigurationsdateien für *mailcow postfix* zu generieren. Das externe Netzwerk wird von *Mailman* erstellt und verwendet. *mailcow* benötigt es, um eingehende Listenmails an *Mailman* zu liefern. + +Erstellen Sie die Datei `/opt/mailcow-dockerized/data/conf/postfix/extra.cf` (z.B. mit `nano`) und fügen Sie die folgenden Zeilen hinzu: + +``` +# 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 +``` + +Da wir hier die *mailcow postfix* Konfiguration überschreiben, kann dieser Schritt Ihre normalen Mailtransporte unterbrechen. Überprüfen Sie die [originalen Konfigurationsdateien](https://github.com/mailcow/mailcow-dockerized/tree/master/data/conf/postfix), wenn sich etwas geändert hat. + +#### SSL-Zertifikate + +Da wir *mailcow* als Proxy verwenden, müssen wir die SSL-Zertifikate in die *mailcow*-Dateistruktur kopieren. Diese Aufgabe wird das Skript [renew-ssl.sh](https://github.com/g4rf/dockerized-mailcow-mailman/tree/master/scripts/renew-ssl.sh) für uns erledigen: + +- Kopieren Sie die Datei nach `/opt/mailcow-dockerized` +- Ändere **mailcow_HOSTNAME** in deinen *mailcow* Hostnamen +- Machen Sie es ausführbar (`chmod a+x renew-ssl.sh`) +- **Noch nicht ausführen, da wir zuerst Mailman benötigen** + +Sie müssen einen *cronjob* erstellen, so dass neue Zertifikate kopiert werden. Führen Sie ihn als *root* oder *sudo* aus: + +``` +crontab -e +``` + +Um das Skript jeden Tag um 5 Uhr morgens laufen zu lassen, fügen Sie hinzu: + +``` +0 5 * * * /opt/mailcow-dockerized/renew-ssl.sh +``` + +### Installieren Sie *Mailman*. + +Befolgen Sie im Wesentlichen die Anweisungen unter [docker-mailman](https://github.com/maxking/docker-mailman). Da sie sehr umfangreich sind, ist hier in aller Kürze beschrieben, was zu tun ist: + +Als *root* oder *sudo*: + +``` +cd /opt +mkdir -p mailman/core +mkdir -p mailman/web +git clone https://github.com/maxking/docker-mailman +cd docker-mailman +``` + +#### Mailman konfigurieren + +Erstellen Sie einen langen Schlüssel für *Hyperkitty*, z.B. mit dem Linux-Befehl `cat /dev/urandom | tr -dc a-zA-Z0-9 | head -c30; echo`. Speichern Sie diesen Schlüssel vorerst als HYPERKITTY_KEY. + +Erstellen Sie ein langes Passwort für die Datenbank, z. B. mit dem Linux-Befehl `cat /dev/urandom | tr -dc a-zA-Z0-9 | head -c30; echo`. Speichern Sie dieses Passwort zunächst als DBPASS. + +Erstellen Sie einen langen Schlüssel für *Django*, z. B. mit dem Linux-Befehl `cat /dev/urandom | tr -dc a-zA-Z0-9 | head -c30; echo`. Speichern Sie diesen Schlüssel für einen Moment als DJANGO_KEY. + +Erstellen Sie die Datei `/opt/docker-mailman/docker-compose.override.yaml` und ersetzen Sie `HYPERKITTY_KEY`, `DBPASS` und `DJANGO_KEY` durch die generierten Werte: + +``` +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 +``` + +Bei `mailman-web` geben Sie die korrekten Werte für `SERVE_FROM_DOMAIN` (z.B. `lists.example.org`), `MAILMAN_ADMIN_USER` und `MAILMAN_ADMIN_EMAIL` ein. Sie benötigen die Admin-Zugangsdaten, um sich in der Web-Oberfläche (*Pistorius*) anzumelden. Um **das Passwort zum ersten Mal** zu setzen, verwenden Sie die Funktion *Passwort vergessen* im Webinterface. + +Über andere Konfigurationsoptionen lesen Sie die Dokumentationen [Mailman-web](https://github.com/maxking/docker-mailman#mailman-web-1) und [Mailman-core](https://github.com/maxking/docker-mailman#mailman-core-1). + +#### Konfigurieren Sie Mailman core und Mailman web + +Erstellen Sie die Datei `/opt/mailman/core/mailman-extra.cfg` mit dem folgenden Inhalt. `mailman@example.org` sollte auf ein gültiges Postfach oder eine Umleitung verweisen. + +``` +[mailman] +default_language: de +site_owner: mailman@example.org +``` + +Erstellen Sie die Datei `/opt/mailman/web/settings_local.py` mit dem folgenden Inhalt. `mailman@example.org` sollte auf ein gültiges Postfach oder eine Umleitung verweisen. + +``` +# Gebietsschema +LANGUAGE_CODE = 'de-de' + +# soziale Authentifizierung deaktivieren +SOCIALACCOUNT_PROVIDERS = {} + +# ändern +DEFAULT_FROM_EMAIL = 'mailman@example.org' + +DEBUG = False +``` +Sie können `LANGUAGE_CODE` und `SOCIALACCOUNT_PROVIDERS` an Ihre Bedürfnisse anpassen. Im Moment hat `SOCIALACCOUNT_PROVIDERS` keinen Effekt, siehe [issue #2](https://github.com/g4rf/dockerized-mailcow-mailman/issues/2). + +### 🏃 Ausführen + +Ausführen (als *root* oder *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 +``` + +**Warten Sie ein paar Minuten!** Die Container müssen ihre Datenbanken und Konfigurationsdateien erstellen. Dies kann bis zu 1 Minute und mehr dauern. + +## Bemerkungen + +### Neue Listen werden von Postfix nicht sofort erkannt + +Wenn man eine neue Liste anlegt und versucht, sofort eine E-Mail zu versenden, antwortet *postfix* mit `Benutzer existiert nicht`, weil *postfix* die Liste noch nicht an *Mailman* übergeben hat. Die Konfiguration unter `/opt/mailman/core/var/data/postfix_lmtp` wird nicht sofort aktualisiert. Wenn Sie die Liste sofort benötigen, starten Sie *postifx* manuell neu: + +``` +cd /opt/mailcow-dockerized +docker-compose restart postfix-mailcow +``` + +## Update + +**mailcow** hat sein eigenes Update-Skript in `/opt/mailcow-dockerized/update.sh`, [siehe die Dokumentation](../i_u_m/i_u_m_update.md). + +Für **Mailman** holen Sie sich einfach die neueste Version aus dem [github repository](https://github.com/maxking/docker-mailman). + +## Sicherung + +**mailcow** hat ein eigenes Backup-Skript. [Lies die Docs](../backup_restore/b_n_r_backup.md) für weitere Informationen. + +**Mailman** gibt keine Backup-Anweisungen in der README.md an. Im [gitbucket von pgollor](https://gitbucket.pgollor.de/docker/mailman-mailcow-integration/blob/master/mailman-backup.sh) befindet sich ein Skript, das hilfreich sein könnte. + +## ToDo + +### Skript installieren + +Schreiben Sie ein Skript wie in [mailman-mailcow-integration/mailman-install.sh](https://gitbucket.pgollor.de/docker/mailman-mailcow-integration/blob/master/mailman-install.sh), da viele der Schritte automatisierbar sind. + +1. Fragen Sie alle Konfigurationsvariablen ab und erstellen Sie Passwörter und Schlüssel. +2. Führen Sie eine (halb)automatische Installation durch. +3. Viel Spaß! + + + diff --git a/docs/third_party/third_party-mailman3.en.md b/docs/third_party/third_party-mailman3.en.md new file mode 100644 index 000000000..67130c45e --- /dev/null +++ b/docs/third_party/third_party-mailman3.en.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 +2. Install *Apache* as a reverse proxy +3. Obtain SSL certificates with *Let's Encrypt* +4. Install *mailcow* with *Mailman* integration +5. Install *Mailman* +6. 🏃 Run + +### DNS setup + +Most of the configuration is covered by *mailcow*s [DNS setup](../prerequisite/prerequisite-dns.md). 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](../i_u_m/i_u_m_install.md). **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](../i_u_m/i_u_m_update.md). + +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](../backup_restore/b_n_r_backup.md) 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! \ No newline at end of file diff --git a/docs/third_party/third_party-mailpiler_integration.de.md b/docs/third_party/third_party-mailpiler_integration.de.md new file mode 100644 index 000000000..524135733 --- /dev/null +++ b/docs/third_party/third_party-mailpiler_integration.de.md @@ -0,0 +1,69 @@ +Dies ist eine einfache Integration von mailcow-Aliasen und dem Mailbox-Namen in mailpiler bei Verwendung von IMAP-Authentifizierung. + +**Disclaimer**: Dies wird weder offiziell vom mailcow-Projekt noch von seinen Mitwirkenden gepflegt oder unterstützt. Es wird keine Garantie oder Unterstützung angeboten, jedoch steht es Ihnen frei, Themen auf GitHub zu öffnen, um einen Fehler zu melden oder weitere Ideen zu liefern. [GitHub Repo kann hier gefunden werden](https://github.com/patschi/mailpiler-mailcow-integration). + +!!! info + Die Unterstützung für Domain Wildcards wurde in Piler 1.3.10 implementiert, das am 03.01.2021 veröffentlicht wurde. Frühere Versionen funktionieren grundsätzlich, aber nach dem Einloggen sehen Sie keine E-Mails, die von oder an den Domain-Alias gesendet werden. (z.B. wenn @example.com ein Alias für admin@example.com ist) + +## Das zu lösende Problem + +mailpiler bietet die Authentifizierung auf Basis von IMAP an, zum Beispiel: + +```php +$config['ENABLE_IMAP_AUTH'] = 1; +$config['IMAP_HOST'] = 'mail.example.com'; +$config['IMAP_PORT'] = 993; +$config['IMAP_SSL'] = true; +``` + +- Wenn Sie sich also mit `patrik@example.com` anmelden, sehen Sie nur zugestellte E-Mails, die von oder an diese spezielle E-Mail-Adresse gesendet wurden. +- Wenn zusätzliche Aliase in mailcow definiert werden, wie z.B. `team@example.com`, werden Sie keine Emails sehen, die an oder von dieser Email-Adresse gesendet wurden, auch wenn Sie ein Empfänger von Emails sind, die an diese Alias-Adresse gesendet wurden. + +Indem wir uns in den Authentifizierungsprozess von mailpiler einklinken, sind wir in der Lage, die erforderlichen Daten über die mailcow API während des Logins zu erhalten. Dies löst API-Anfragen an die mailcow-API aus (die einen Nur-Lese-API-Zugang erfordern), um die Aliase auszulesen, an denen Ihre E-Mail-Adresse teilnimmt, und auch den "Namen" des Postfachs, der angegeben wurde, um ihn nach dem Login oben rechts in mailpiler anzuzeigen. + +Zugelassene E-Mail-Adressen können in den Mailpiler-Einstellungen oben rechts nach dem Einloggen eingesehen werden. + +!!! info + Dies wird nur einmal während des Authentifizierungsprozesses abgefragt. Die autorisierten Aliase und der Realname sind für die gesamte Dauer der Benutzersitzung gültig, da mailpiler sie in den Sitzungsdaten setzt. Wird ein Benutzer aus einem bestimmten Alias entfernt, so wird dies erst nach dem nächsten Login wirksam. + +## Die Lösung + +Hinweis: Die Dateipfade können je nach Einrichtung variieren. + +### Voraussetzungen + +- Eine funktionierende mailcow-Instanz +- Eine funktionierende mailpiler Instanz ([Sie finden eine Installationsanleitung hier](https://patrik.kernstock.net/2020/08/mailpiler-installation-guide/), [überprüfen Sie unterstützte Versionen hier](https://github.com/patschi/mailpiler-mailcow-integration#piler)) +- Ein mailcow API-Schlüssel (Nur-Lesen funktioniert): `Konfiguration & Details - Zugang - Nur-Lesen-Zugang`. Vergessen Sie nicht, den API-Zugang von Ihrer mailpiler IP zu erlauben. + +!!! warning + Da mailpiler sich gegenüber mailcow, unserem IMAP-Server, authentifiziert, können fehlgeschlagene Logins von Nutzern oder Bots eine Sperre für Ihre mailpiler-Instanz auslösen. Daher sollten Sie in Erwägung ziehen, die IP-Adresse der mailpiler-Instanz innerhalb von mailcow auf eine Whitelist zu setzen: `Konfiguration & Details - Konfiguration - Fail2ban-Parameter - Whitelisted networks/hosts`. + +### Einrichtung + +1. Setzen Sie die benutzerdefinierte Abfragefunktion von mailpiler und fügen Sie diese an `/usr/local/etc/piler/config-site.php` an: + + ```php + $config['MAILCOW_API_KEY'] = 'YOUR_READONLY_API_KEY'; + $config['MAILCOW_SET_REALNAME'] = true; // wenn nicht angegeben, dann ist der Standardwert false + $config['CUSTOM_EMAIL_QUERY_FUNCTION'] = 'query_mailcow_for_email_access'; + include('auth-mailcow.php'); + ``` + + Sie können auch den mailcow-Hostnamen ändern, falls erforderlich: + ```php + $config['MAILCOW_HOST'] = 'mail.domain.tld'; // standardmäßig $config['IMAP_HOST'] + ``` + +2. Laden Sie die PHP-Datei mit den Funktionen aus dem [GitHub Repo](https://github.com/patschi/mailpiler-mailcow-integration) herunter: + + ```sh + curl -o /usr/local/etc/piler/auth-mailcow.php https://raw.githubusercontent.com/patschi/mailpiler-mailcow-integration/master/auth-mailcow.php + ``` + +3. Erledigt! + + Stellen Sie sicher, dass Sie sich erneut mit Ihren IMAP-Zugangsdaten anmelden, damit die Änderungen wirksam werden. + + Wenn es nicht funktioniert, ist höchstwahrscheinlich etwas mit der API-Abfrage selbst nicht in Ordnung. Versuchen Sie eine Fehlersuche, indem Sie manuelle API-Anfragen an die API senden. (Tipp: Öffnen Sie `https://mail.domain.tld/api` auf Ihrer Instanz) + diff --git a/docs/third_party/third_party-mailpiler_integration.en.md b/docs/third_party/third_party-mailpiler_integration.en.md new file mode 100644 index 000000000..7d9702ed9 --- /dev/null +++ b/docs/third_party/third_party-mailpiler_integration.en.md @@ -0,0 +1,68 @@ +This is a simple integration of mailcow aliases and the mailbox name into mailpiler when using IMAP authentication. + +**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: + +```php +$config['ENABLE_IMAP_AUTH'] = 1; +$config['IMAP_HOST'] = 'mail.example.com'; +$config['IMAP_PORT'] = 993; +$config['IMAP_SSL'] = true; +``` + +- So when you log in using `patrik@example.com`, you will only see delivered emails sent from or to this specific email address. +- When additional aliases are defined in mailcow, like `team@example.com`, you won't see emails sent to or from this email address even the fact you're a recipient of mails sent to this alias address. + +By hooking into the authentication process of mailpiler, we are able to get required data via the mailcow API during login. This fires API requests to the mailcow API (requiring read-only API access) to read out the aliases your email address participates and also the "Name" of the mailbox specified to display it on the top-right of mailpiler after login. + +Permitted email addresses can be seen in the mailpiler settings top-right after logging in. + +!!! info + This is only pulled once during the authentication process. The authorized aliases and the realname are valid for the whole duration of the user session as mailpiler sets them in the session data. If user is removed from specific alias, this will only take effect after next login. + +## The solution + +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/), [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 + As mailpiler authenticates against mailcow, our IMAP server, failed logins of users or bots might trigger a block for your mailpiler instance. Therefore you might want to consider whitelisting the IP address of the mailpiler instance within mailcow: `Configuration & Details - Configuration - Fail2ban parameters - Whitelisted networks/hosts`. + +### Setup + +1. Set the custom query function of mailpiler and append this to `/usr/local/etc/piler/config-site.php`: + + ```php + $config['MAILCOW_API_KEY'] = 'YOUR_READONLY_API_KEY'; + $config['MAILCOW_SET_REALNAME'] = true; // when not specified, then default is false + $config['CUSTOM_EMAIL_QUERY_FUNCTION'] = 'query_mailcow_for_email_access'; + include('auth-mailcow.php'); + ``` + + You can also change the mailcow hostname, if required: + ```php + $config['MAILCOW_HOST'] = 'mail.domain.tld'; // defaults to $config['IMAP_HOST'] + ``` + +2. Download the PHP file with the functions from the [GitHub repo](https://github.com/patschi/mailpiler-mailcow-integration): + + ```sh + curl -o /usr/local/etc/piler/auth-mailcow.php https://raw.githubusercontent.com/patschi/mailpiler-mailcow-integration/master/auth-mailcow.php + ``` + +3. Done! + + Make sure to re-login with your IMAP credentials for changes to take effect. + + If it doesn't work, most likely something's wrong with the API query itself. Consider debugging by sending manual API requests to the API. (Tip: Open `https://mail.domain.tld/api` on your instance) \ No newline at end of file diff --git a/docs/third_party/third_party-nextcloud.de.md b/docs/third_party/third_party-nextcloud.de.md new file mode 100644 index 000000000..42da3f9b4 --- /dev/null +++ b/docs/third_party/third_party-nextcloud.de.md @@ -0,0 +1,105 @@ +## Nextcloud mit dem Helper-Skript verwalten + +Nextcloud kann mit dem [helper script](https://github.com/mailcow/mailcow-dockerized/raw/master/helper-scripts/nextcloud.sh), das in mailcow enthalten ist, eingerichtet (Parameter `-i`) und entfernt (Parameter `-p`) werden. Um Nextcloud zu installieren, navigieren Sie einfach zu Ihrem mailcow-dockerized Root-Ordner und führen Sie das Helper-Skript wie folgt aus: + +`./helper-scripts/nextcloud.sh -i` + +Für den Fall, dass Sie das Passwort (z.B. für admin) vergessen haben und kein neues anfordern können [über den Passwort-Reset-Link auf dem Login-Bildschirm] (https://docs.nextcloud.com/server/20/admin_manual/configuration_user/reset_admin_password.html?highlight=reset), können Sie durch den Aufruf des Helper-Skripts mit `-r` als Parameter ein neues Passwort setzen. Verwenden Sie diese Option nur, wenn Ihre Nextcloud nicht so konfiguriert ist, dass sie mailcow zur Authentifizierung verwendet, wie im nächsten Abschnitt beschrieben. + +## Konfigurieren Sie Nextcloud, um mailcow für die Authentifizierung zu verwenden + +Im Folgenden wird beschrieben, wie die Authentifizierung über mailcow unter Verwendung des OAuth2-Protokolls eingerichtet wird. Wir nehmen nur an, dass Sie Nextcloud bereits unter _cloud.example.com_ eingerichtet haben und dass Ihre mailcow unter _mail.example.com_ läuft. Es spielt keine Rolle, wenn Ihre Nextcloud auf einem anderen Server läuft, Sie können immer noch mailcow für die Authentifizierung verwenden. + +1\. Melden Sie sich bei mailcow als Administrator an. + +2\. Scrollen Sie nach unten zu _OAuth2 Apps_ und klicken Sie auf die Schaltfläche _Hinzufügen_. Geben Sie die Redirect URI als `https://cloud.example.com/index.php/apps/sociallogin/custom_oauth2/Mailcow` an und klicken Sie auf _Hinzufügen_. Speichern Sie die Client-ID und das Geheimnis für später. + +!!! info + Einige Installationen, einschließlich derer, die mit dem Helper-Skript von mailcow eingerichtet wurden, müssen index.php/ aus der URL entfernen, um einen erfolgreichen Redirect zu erhalten: `https://cloud.example.com/apps/sociallogin/custom_oauth2/Mailcow` + +3\. Melden Sie sich bei Nextcloud als Administrator an. + +4\. Klicken Sie auf die Schaltfläche in der oberen rechten Ecke und wählen Sie _Apps_. Klicken Sie auf die Schaltfläche "Suchen" in der Symbolleiste, suchen Sie nach dem Plugin [_Social Login_](https://apps.nextcloud.com/apps/sociallogin) und klicken Sie daneben auf _Herunterladen und aktivieren_. + +5\. Klicken Sie auf die Schaltfläche in der oberen rechten Ecke und wählen Sie _Einstellungen_. Scrollen Sie zum Abschnitt _Administration_ auf der linken Seite und klicken Sie auf _Social Login_. + +6\. Entfernen Sie das Häkchen bei den folgenden Punkten: + +- "Automatische Erstellung neuer Benutzer deaktivieren" +- "Benutzern erlauben, soziale Logins mit ihren Konten zu verbinden". +- "Nicht verfügbare Benutzergruppen bei der Anmeldung nicht entfernen" +- "Gruppen automatisch erstellen, wenn sie nicht vorhanden sind" +- "Anmeldung für Benutzer ohne zugeordnete Gruppen einschränken". + +7\. Überprüfen Sie die folgenden Punkte: + +- "Die Erstellung eines Kontos verhindern, wenn die E-Mail-Adresse in einem anderen Konto existiert" +- "Benutzerprofil bei jeder Anmeldung aktualisieren" +- "Benachrichtigung der Administratoren über neue Benutzer deaktivieren". + +Klicken Sie auf die Schaltfläche _Speichern_. + +8\. Scrollen Sie nach unten zu _Custom OAuth2_ und klicken Sie auf die Schaltfläche _+_. +9\. Konfigurieren Sie die Parameter wie folgt: + +- Interner Name: `Mailcow` +- Titel: `Mailcow` +- API Basis-URL: `https://mail.example.com` +- Autorisierungs-URL: `https://mail.example.com/oauth/authorize` +- Token-URL: `https://mail.example.com/oauth/token` +- Profil-URL: `https://mail.example.com/oauth/profile` +- Abmelde-URL: (leer lassen) +- Kunden-ID: (die Sie in Schritt 1 erhalten haben) +- Client Secret: (was Sie in Schritt 1 erhalten haben) +- Bereich: `Profil` + +Klicken Sie auf die Schaltfläche _Speichern_ ganz unten auf der Seite. + +--- + +Wenn Sie bisher Nextcloud mit mailcow-Authentifizierung über user\_external/IMAP verwendet haben, müssen Sie einige zusätzliche Schritte durchführen, um Ihre bestehenden Benutzerkonten mit OAuth2 zu verknüpfen. + +1\. Klicken Sie auf die Schaltfläche in der oberen rechten Ecke und wählen Sie _Apps_. Scrollen Sie nach unten zur App _Externe Benutzerauthentifizierung_ und klicken Sie daneben auf _Entfernen_. +2\. Führen Sie die folgenden Abfragen in Ihrer Nextcloud-Datenbank aus (wenn Sie Nextcloud mit dem Skript von mailcow einrichten, können Sie `source mailcow.conf && docker-compose exec mysql-mailcow mysql -u$DBUSER -p$DBPASS $DBNAME` ausführen): +``` +INSERT INTO nc_users (uid, uid_lower) SELECT DISTINCT uid, LOWER(uid) FROM nc_users_external; +INSERT INTO nc_sociallogin_connect (uid, identifier) SELECT DISTINCT uid, CONCAT("Mailcow-", uid) FROM nc_users_external; +``` + +--- + +Wenn Sie Nextcloud bisher ohne mailcow-Authentifizierung, aber mit den gleichen Benutzernamen wie mailcow genutzt haben, können Sie Ihre bestehenden Benutzerkonten auch mit OAuth2 verknüpfen. + +1\. Führen Sie die folgenden Abfragen in Ihrer Nextcloud-Datenbank aus (wenn Sie Nextcloud mit dem Skript von mailcow einrichten, können Sie `source mailcow.conf && docker-compose exec mysql-mailcow mysql -u$DBUSER -p$DBPASS $DBNAME` ausführen): +``` +INSERT INTO nc_sociallogin_connect (uid, identifier) SELECT DISTINCT uid, CONCAT("Mailcow-", uid) FROM nc_users; +``` + +--- + +## Aktualisieren + +Die Nextcloud-Instanz kann einfach mit dem Web-Update-Mechanismus aktualisiert werden. Bei größeren Updates können nach dem Update weitere Änderungen vorgenommen werden. Nachdem die Nextcloud-Instanz geprüft wurde, werden Probleme angezeigt. Dies können z.B. fehlende Indizes in der DB oder ähnliches sein. +Es wird angezeigt, welche Befehle ausgeführt werden müssen, diese müssen im php-fpm-mailcow Container platziert werden. + +Führen Sie z.B. folgenden Befehl aus, um die fehlenden Indizes hinzuzufügen +`docker exec -it -u www-data $(docker ps -f name=php-fpm-mailcow -q) bash -c "php /web/nextcloud/occ db:add-missing-indices"` + +--- + +## Fehlersuche und Fehlerbehebung + +Es kann vorkommen, dass Sie die Nextcloud-Instanz von Ihrem Netzwerk aus nicht erreichen können. Dies kann daran liegen, dass der Eintrag Ihres Subnetzes im Array 'trusted_proxies' fehlt. Sie können Änderungen in der Nextcloud config.php in `data/web/nextcloud/config/*` vornehmen. + +``` +'trusted_proxies' => + array ( + 0 => 'fd4d:6169:6c63:6f77::/64', + 1 => '172.22.1.0/24', + 2 => 'NewSubnet/24', + ), +``` + +Nachdem die Änderungen vorgenommen wurden, muss der nginx-Container neu gestartet werden. +`docker-compose restart nginx-mailcow` + diff --git a/docs/third_party/third_party-nextcloud.en.md b/docs/third_party/third_party-nextcloud.en.md new file mode 100644 index 000000000..3f8715b79 --- /dev/null +++ b/docs/third_party/third_party-nextcloud.en.md @@ -0,0 +1,105 @@ + +## Manage Nextcloud using the helper script + +Nextcloud can be set up (parameter `-i`) and removed (parameter `-p`) with the [helper script](https://github.com/mailcow/mailcow-dockerized/raw/master/helper-scripts/nextcloud.sh) included with mailcow. In order to install Nextcloud simply navigate to your mailcow-dockerized root folder and run the helper script as follows: + +`./helper-scripts/nextcloud.sh -i` + +In case you have forgotten the password (e.g. for admin) and can't request a new one [via the password reset link on the login screen](https://docs.nextcloud.com/server/20/admin_manual/configuration_user/reset_admin_password.html?highlight=reset) calling the helper script with `-r` as parameter allows you to set a new password. Only use this option if your Nextcloud isn't configured to use mailcow for authentication as described in the next section. + +## Configure Nextcloud to use mailcow for authentication + +The following describes how set up authentication via mailcow using the OAuth2 protocol. We will only assume that you have already set up Nextcloud at _cloud.example.com_ and that your mailcow is running at _mail.example.com_. It does not matter if your Nextcloud is running on a different server, you can still use mailcow for authentication. + +1\. Log into mailcow as administrator. + +2\. Scroll down to _OAuth2 Apps_ and click the _Add_ button. Specify the redirect URI as `https://cloud.example.com/index.php/apps/sociallogin/custom_oauth2/Mailcow` and click _Add_. Save the client ID and secret for later. + +!!! info + Some installations, including those setup using the helper script of mailcow, need to remove index.php/ from the URL to get a successful redirect: `https://cloud.example.com/apps/sociallogin/custom_oauth2/Mailcow` + +3\. Log into Nextcloud as administrator. + +4\. Click the button in the top right corner and select _Apps_. Click the search button in the toolbar, search for the [_Social Login_](https://apps.nextcloud.com/apps/sociallogin) plugin and click _Download and enable_ next to it. + +5\. Click the button in the top right corner and select _Settings_. Scroll down to the _Administration_ section on the left and click _Social login_. + +6\. Uncheck the following items: + +- "Disable auto create new users" +- "Allow users to connect social logins with their accounts" +- "Do not prune not available user groups on login" +- "Automatically create groups if they do not exists" +- "Restrict login for users without mapped groups" + +7\. Check the following items: + +- "Prevent creating an account if the email address exists in another account" +- "Update user profile every login" +- "Disable notify admins about new users" + +Click the _Save_ button. + +8\. Scroll down to _Custom OAuth2_ and click the _+_ button. +9\. Configure the parameters as follows: + +- Internal name: `Mailcow` +- Title: `Mailcow` +- API Base URL: `https://mail.example.com` +- Authorize URL: `https://mail.example.com/oauth/authorize` +- Token URL: `https://mail.example.com/oauth/token` +- Profile URL: `https://mail.example.com/oauth/profile` +- Logout URL: (leave blank) +- Client ID: (what you obtained in step 1) +- Client Secret: (what you obtained in step 1) +- Scope: `profile` + +Click the _Save_ button at the very bottom of the page. + +--- + +If you have previously used Nextcloud with mailcow authentication via user\_external/IMAP, you need to perform some additional steps to link your existing user accounts with OAuth2. + +1\. Click the button in the top right corner and select _Apps_. Scroll down to the _External user authentication_ app and click _Remove_ next to it. +2\. Run the following queries in your Nextcloud database (if you set up Nextcloud using mailcow's script, you can run `source mailcow.conf && docker-compose exec mysql-mailcow mysql -u$DBUSER -p$DBPASS $DBNAME`): +``` +INSERT INTO nc_users (uid, uid_lower) SELECT DISTINCT uid, LOWER(uid) FROM nc_users_external; +INSERT INTO nc_sociallogin_connect (uid, identifier) SELECT DISTINCT uid, CONCAT("Mailcow-", uid) FROM nc_users_external; +``` + +--- + +If you have previously used Nextcloud without mailcow authentication, but with the same usernames as mailcow, you can also link your existing user accounts with OAuth2. + +1\. Run the following queries in your Nextcloud database (if you set up Nextcloud using mailcow's script, you can run `source mailcow.conf && docker-compose exec mysql-mailcow mysql -u$DBUSER -p$DBPASS $DBNAME`): +``` +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` \ No newline at end of file diff --git a/docs/third_party/third_party-portainer.de.md b/docs/third_party/third_party-portainer.de.md new file mode 100644 index 000000000..7e4571105 --- /dev/null +++ b/docs/third_party/third_party-portainer.de.md @@ -0,0 +1,62 @@ +Um Portainer zu aktivieren, müssen die docker-compose.yml und site.conf für Nginx geändert werden. + +1\. Erstellen Sie eine neue Datei `docker-compose.override.yml` im mailcow-dockerized Stammverzeichnis und fügen Sie die folgende Konfiguration ein +``` +version: '2.1' +services: + portainer-mailcow: + image: portainer/portainer-ce + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ./data/conf/portainer:/data + restart: always + dns: + - 172.22.1.254 + dns_search: mailcow-network + networks: + mailcow-network: + aliases: + - portainer +``` +2a\. Erstelle `data/conf/nginx/portainer.conf`: +``` +upstream portainer { + server portainer-mailcow:9000; +} + +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} +``` + +2b\. Fügen Sie einen neuen Standort für die Standard-Mailcow-Site ein, indem Sie die Datei `data/conf/nginx/site.portainer.custom` erstellen: +``` + location /portainer/ { + proxy_http_version 1.1; + proxy_set_header Host $http_host; # required for docker client's sake + proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_read_timeout 900; + + proxy_set_header Connection ""; + proxy_buffers 32 4k; + proxy_pass http://portainer/; + } + + location /portainer/api/websocket/ { + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_pass http://portainer/api/websocket/; + } +``` + +3\. Übernehmen Sie Ihre Änderungen: +``` +docker-compose up -d && docker-compose restart nginx-mailcow +``` + +Nun können Sie einfach zu https://${MAILCOW_HOSTNAME}/portainer/ navigieren, um Ihre Portainer-Container-Überwachungsseite anzuzeigen. Sie werden dann aufgefordert, ein neues Passwort für den **admin** Account anzugeben. Nachdem Sie Ihr Passwort eingegeben haben, können Sie sich mit der Portainer UI verbinden. + diff --git a/docs/third_party/third_party-portainer.en.md b/docs/third_party/third_party-portainer.en.md new file mode 100644 index 000000000..aca755692 --- /dev/null +++ b/docs/third_party/third_party-portainer.en.md @@ -0,0 +1,61 @@ +In order to enable Portainer, the docker-compose.yml and site.conf for Nginx must be modified. + +1\. Create a new file `docker-compose.override.yml` in the mailcow-dockerized root folder and insert the following configuration +``` +version: '2.1' +services: + portainer-mailcow: + image: portainer/portainer-ce + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - ./data/conf/portainer:/data + restart: always + dns: + - 172.22.1.254 + dns_search: mailcow-network + networks: + mailcow-network: + aliases: + - portainer +``` +2a\. Create `data/conf/nginx/portainer.conf`: +``` +upstream portainer { + server portainer-mailcow:9000; +} + +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} +``` + +2b\. Insert a new location to the default mailcow site by creating the file `data/conf/nginx/site.portainer.custom`: +``` + location /portainer/ { + proxy_http_version 1.1; + proxy_set_header Host $http_host; # required for docker client's sake + proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_read_timeout 900; + + proxy_set_header Connection ""; + proxy_buffers 32 4k; + proxy_pass http://portainer/; + } + + location /portainer/api/websocket/ { + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_pass http://portainer/api/websocket/; + } +``` + +3\. Apply your changes: +``` +docker-compose up -d && docker-compose restart nginx-mailcow +``` + +Now you can simply navigate to https://${MAILCOW_HOSTNAME}/portainer/ to view your Portainer container monitoring page. You’ll then be prompted to specify a new password for the **admin** account. After specifying your password, you’ll then be able to connect to the Portainer UI. \ No newline at end of file diff --git a/docs/third_party/third_party-roundcube.de.md b/docs/third_party/third_party-roundcube.de.md new file mode 100644 index 000000000..6e912fb4e --- /dev/null +++ b/docs/third_party/third_party-roundcube.de.md @@ -0,0 +1,255 @@ +## Installation von Roundcube + +Laden Sie Roundcube 1.5.x in das Web htdocs Verzeichnis herunter und entpacken Sie es (hier `rc/`): +``` +# Prüfen Sie, ob eine neuere Version vorliegt! +cd daten/web +wget -O - https://github.com/roundcube/roundcubemail/releases/download/1.5.2/roundcubemail-1.5.2-complete.tar.gz | tar xfvz - + +# Ändern Sie den Ordnernamen +mv roundcubemail-1.5.2 rc + +# Berechtigungen ändern +chown -R root: rc/ + +# Fix Allow remote resources (https://github.com/roundcube/roundcubemail/issues/8170) sollte in 1.6 nicht erforderlich sein +sed -i "s/\$prefix = '\.\/';/\$prefix = preg_replace\('\/\[\?\&]\.\*\$\/', '', \$_SERVER\['REQUEST_URI'] \?\? ''\) \?: '\.\/';/g" rc/program/include/rcmail.php +``` + +Wenn Sie eine Rechtschreibprüfung benötigen, erstellen Sie eine Datei `data/hooks/phpfpm/aspell.sh` mit folgendem Inhalt und geben Sie dann `chmod +x data/hooks/phpfpm/aspell.sh` ein. Dadurch wird eine lokale Rechtschreibprüfung installiert. Beachten Sie, dass die meisten modernen Webbrowser eine eingebaute Rechtschreibprüfung haben, so dass Sie diese vielleicht nicht benötigen. +``` +#!/bin/bash +apk update +apk add aspell-de # oder jede andere Sprache +``` + +Erstellen Sie eine Datei `data/web/rc/config/config.inc.php` mit dem folgenden Inhalt. + - **Ändern Sie den Parameter `des_key` auf einen Zufallswert.** Er wird verwendet, um Ihr IMAP-Passwort vorübergehend zu speichern. + - Der `db_prefix` ist optional, wird aber empfohlen. + - Wenn Sie die Rechtschreibprüfung im obigen Schritt nicht installiert haben, entfernen Sie den Parameter `spellcheck_engine` und ersetzen ihn durch `$config['enable_spellcheck'] = false;`. +``` + array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +$config['enable_installer'] = true; +$config['smtp_conn_options'] = array( + 'ssl' => array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +$config['db_prefix'] = 'mailcow_rc1'; +``` + +Richten Sie Ihren Browser auf `https://myserver/rc/installer` und folgen Sie den Anweisungen. +Initialisiere die Datenbank und verlasse das Installationsprogramm. + +**Löschen Sie das Verzeichnis `data/web/rc/installer` nach einer erfolgreichen Installation! + +## Konfigurieren Sie die ManageSieve-Filterung + +Öffnen Sie `data/web/rc/plugins/managesieve/config.inc.php` und ändern Sie die folgenden Parameter (oder fügen Sie sie am Ende der Datei hinzu): +``` +$config['managesieve_port'] = 4190; +$config['managesieve_host'] = 'tls://dovecot'; +$config['managesieve_conn_options'] = array( + ssl' => array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +// Aktiviert separate Verwaltungsschnittstelle für Urlaubsantworten (außer Haus) +// 0 - kein separater Abschnitt (Standard), +// 1 - Abschnitt "Urlaub" hinzufügen, +// 2 - Abschnitt "Urlaub" hinzufügen, aber Abschnitt "Filter" ausblenden +$config['managesieve_vacation'] = 1; +``` + +## Aktivieren Sie die Funktion "Passwort ändern" in Roundcube + +Öffnen Sie `data/web/rc/config/config.inc.php` und aktivieren Sie das Passwort-Plugin: + +``` +[...] +$config['plugins'] = array( + 'archive', + 'password', +); +[...] +``` + +Öffnen Sie `data/web/rc/plugins/password/password.php`, suchen Sie nach `case 'ssha':` und fügen Sie oben hinzu: + +``` + case 'ssha256': + $salt = rcube_utils::random_bytes(8); + $crypted = base64_encode( hash('sha256', $password . $salt, TRUE ) . $salt ); + $prefix = '{SSHA256}'; + break; +``` + +Öffnen Sie `data/web/rc/plugins/password/config.inc.php` und ändern Sie die folgenden Parameter (oder fügen Sie sie am Ende der Datei hinzu): + +``` +$config['password_driver'] = 'sql'; +$config['password_algorithm'] = 'ssha256'; +$config['password_algorithm_prefix'] = '{SSHA256}'; +$config['password_query'] = "UPDATE mailbox SET password = %P WHERE username = %u"; +``` + +## CardDAV Adressbücher in Roundcube einbinden + +Laden Sie die neueste Version von [RCMCardDAV](https://github.com/mstilkerich/rcmcarddav) in das Roundcube Plugin Verzeichnis und entpacken Sie es (hier `rc/plugins`): +``` +cd data/web/rc/plugins +wget -O - https://github.com/mstilkerich/rcmcarddav/releases/download/v4.3.0/carddav-v4.3.0.tar.gz | tar xfvz - +chown -R root: carddav/ +``` + +Kopieren Sie die Datei `config.inc.php.dist` nach `config.inc.php` (hier in `rc/plugins/carddav`) und fügen Sie die folgende Voreinstellung an das Ende der Datei an - vergessen Sie nicht, `mx.example.org` durch Ihren eigenen Hostnamen zu ersetzen: +``` +$prefs['SOGo'] = array( + 'name' => 'SOGo', + 'username' => '%u', + 'password' => '%p', + 'url' => 'https://mx.example.org/SOGo/dav/%u/', + 'carddav_name_only' => true, + 'use_categories' => true, + 'active' => true, + 'readonly' => false, + 'refresh_time' => '02:00:00', + 'fixed' => array( 'active', 'name', 'username', 'password', 'refresh_time' ), + 'hide' => false, +); +``` +Bitte beachten Sie, dass dieses Preset nur das Standard-Adressbuch integriert (dasjenige, das den Namen "Persönliches Adressbuch" trägt und nicht gelöscht werden kann). Weitere Adressbücher werden derzeit nicht automatisch erkannt, können aber manuell in den Roundcube-Einstellungen hinzugefügt werden. + +Aktivieren Sie das Plugin, indem Sie `carddav` zu `$config['plugins']` in `rc/config/config.inc.php` hinzufügen. + +Wenn Sie die Standard-Adressbücher (die in der Roundcube-Datenbank gespeichert sind) entfernen möchten, so dass nur die CardDAV-Adressbücher zugänglich sind, fügen Sie `$config['address_book_type'] = '';` in die Konfigurationsdatei `data/web/rc/config/config.inc.php` ein. + +--- + +Optional können Sie Roundcube's Link zu der mailcow Apps Liste hinzufügen. +Um dies zu tun, öffnen oder erstellen Sie `data/web/inc/vars.local.inc.php` und fügen Sie den folgenden Code-Block hinzu: + +*HINWEIS: Vergessen Sie nicht, das ` 'SOGo', + 'link' => '/SOGo/' + ), + array( + 'name' => 'Roundcube', + 'link' => '/rc/' + ) +); +... +``` + +## Aktualisierung von Roundcube + +Ein Upgrade von Roundcube ist recht einfach: Gehen Sie auf die [Github releases](https://github.com/roundcube/roundcubemail/releases) Seite für Roundcube und holen Sie sich den Link für die "complete.tar.gz" Datei für die gewünschte Version. Dann folgen Sie den untenstehenden Befehlen und ändern Sie die URL und den Namen des Roundcube-Ordners, falls nötig. + + +``` +# Starten Sie eine Bash-Sitzung des mailcow PHP-Containers +docker exec -it mailcowdockerized_php-fpm-mailcow_1 bash + +# Installieren Sie die erforderliche Upgrade-Abhängigkeit, dann aktualisieren Sie Roundcube auf die gewünschte Version +apk add rsync +cd /tmp +wget -O - https://github.com/roundcube/roundcubemail/releases/download/1.5.2/roundcubemail-1.5.2-complete.tar.gz | tar xfvz - +cd roundcubemail-1.5.2 +bin/installto.sh /web/rc + +# Geben Sie 'Y' ein und drücken Sie die Eingabetaste, um Ihre Installation von Roundcube zu aktualisieren. + +# Entfernen Sie übrig gebliebene Dateien +cd /tmp +rm -rf roundcube* + +# Fix Allow remote resources (https://github.com/roundcube/roundcubemail/issues/8170) sollte in 1.6 nicht benötigt werden +sed -i "s/\$prefix = '\.\/';/\$prefix = preg_replace\('\/\[\?\&]\.\*\$\/', '', \$_SERVER\['REQUEST_URI'] \?\? ''\) \?: '\.\/';/g" /web/rc/program/include/rcmail.php +``` + +## Administratoren ohne Passwort in Roundcube einloggen lassen + +Installieren Sie zunächst das Plugin [dovecot_impersonate] (https://github.com/corbosman/dovecot_impersonate/) und fügen Sie Roundcube als App hinzu (siehe oben). + +Editieren Sie `mailcow.conf` und fügen Sie folgendes hinzu: + +``` +# Erlaube Admins, sich in Roundcube als Email-Benutzer einzuloggen (ohne Passwort) +# Roundcube mit Plugin dovecot_impersonate muss zuerst installiert werden + +ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE=y +``` + +Editieren Sie `docker-compose.override.yml` und verfassen/erweitern Sie den Abschnitt für `php-fpm-mailcow`: + +```yml +version: '2.1' +services: + php-fpm-mailcow: + environment: + - ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE=${ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE:-n} +``` + + +Bearbeiten Sie `data/web/js/site/mailbox.js` und den folgenden Code nach [`if (ALLOW_ADMIN_EMAIL_LOGIN) { ... }`](https://github.com/mailcow/mailcow-dockerized/blob/2f9da5ae93d93bf62a8c2b7a5a6ae50a41170c48/data/web/js/site/mailbox.js#L485-L487) + +```js +if (ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE) { + item.action += ''; +} +``` + +Bearbeiten Sie `data/web/mailbox.php` und fügen Sie diese Zeile zum Array [`$template_data`](https://github.com/mailcow/mailcow-dockerized/blob/2f9da5ae93d93bf62a8c2b7a5a6ae50a41170c48/data/web/mailbox.php#L33-L43) hinzu: + +```php + 'allow_admin_email_login_roundcube' => (preg_match("/^(yes|y)+$/i", $_ENV["ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE"])) ? 'true' : 'false', +``` + +Bearbeiten Sie `data/web/templates/mailbox.twig` und fügen Sie diesen Code am Ende des [javascript-Abschnitts] ein (https://github.com/mailcow/mailcow-dockerized/blob/2f9da5ae93d93bf62a8c2b7a5a6ae50a41170c48/data/web/templates/mailbox.twig#L49-L57): + +```js + var ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE = {{ allow_admin_email_login_roundcube }}; +``` + +Kopieren Sie den Inhalt der folgenden Dateien aus diesem [Snippet](https://gitlab.com/-/snippets/2038244): + +* `data/web/inc/lib/RoundcubeAutoLogin.php` +* `data/web/rc-auth.php` + +Starten Sie schließlich mailcow neu + +``` +docker-compose down +docker-compose up -d +``` + + + + diff --git a/docs/third_party/third_party-roundcube.en.md b/docs/third_party/third_party-roundcube.en.md new file mode 100644 index 000000000..9e3e93fb0 --- /dev/null +++ b/docs/third_party/third_party-roundcube.en.md @@ -0,0 +1,251 @@ +## Installing Roundcube + +Download Roundcube 1.5.x to the web htdocs directory and extract it (here `rc/`): +``` +# Check for a newer release! +cd data/web +wget -O - https://github.com/roundcube/roundcubemail/releases/download/1.5.2/roundcubemail-1.5.2-complete.tar.gz | tar xfvz - + +# Change folder name +mv roundcubemail-1.5.2 rc + +# Change permissions +chown -R root: rc/ + +# Fix Allow remote resources (https://github.com/roundcube/roundcubemail/issues/8170) should not be required in 1.6 +sed -i "s/\$prefix = '\.\/';/\$prefix = preg_replace\('\/\[\?\&]\.\*\$\/', '', \$_SERVER\['REQUEST_URI'] \?\? ''\) \?: '\.\/';/g" rc/program/include/rcmail.php +``` + +If you need spell check features, create a file `data/hooks/phpfpm/aspell.sh` with the following content, then `chmod +x data/hooks/phpfpm/aspell.sh`. This installs a local spell check engine. Note, most modern web browsers have built in spell check, so you may not want/need this. +``` +#!/bin/bash +apk update +apk add aspell-en # or any other language +``` + +Create a file `data/web/rc/config/config.inc.php` with the following content. + - **Change the `des_key` parameter to a random value.** It is used to temporarily store your IMAP password. + - The `db_prefix` is optional but recommended. + - If you didn't install spell check in the above step, remove `spellcheck_engine` parameter and replace it with `$config['enable_spellcheck'] = false;`. +``` + array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +$config['enable_installer'] = true; +$config['smtp_conn_options'] = array( + 'ssl' => array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +$config['db_prefix'] = 'mailcow_rc1'; +``` + +Point your browser to `https://myserver/rc/installer` and follow the instructions. +Initialize the database and leave the installer. + +**Delete the directory `data/web/rc/installer` after a successful installation!** + +## Configure ManageSieve filtering + +Open `data/web/rc/plugins/managesieve/config.inc.php` and change the following parameters (or add them at the bottom of that file): +``` +$config['managesieve_port'] = 4190; +$config['managesieve_host'] = 'tls://dovecot'; +$config['managesieve_conn_options'] = array( + 'ssl' => array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +// Enables separate management interface for vacation responses (out-of-office) +// 0 - no separate section (default), +// 1 - add Vacation section, +// 2 - add Vacation section, but hide Filters section +$config['managesieve_vacation'] = 1; +``` + +## Enable change password function in Roundcube + +Open `data/web/rc/config/config.inc.php` and enable the password plugin: + +``` +... +$config['plugins'] = array( + 'archive', + 'password', +); +... +``` + +Open `data/web/rc/plugins/password/password.php`, search for `case 'ssha':` and add above: + +``` + case 'ssha256': + $salt = rcube_utils::random_bytes(8); + $crypted = base64_encode( hash('sha256', $password . $salt, TRUE ) . $salt ); + $prefix = '{SSHA256}'; + break; +``` + +Open `data/web/rc/plugins/password/config.inc.php` and change the following parameters (or add them at the bottom of that file): + +``` +$config['password_driver'] = 'sql'; +$config['password_algorithm'] = 'ssha256'; +$config['password_algorithm_prefix'] = '{SSHA256}'; +$config['password_query'] = "UPDATE mailbox SET password = %P WHERE username = %u"; +``` + +## Integrate CardDAV addressbooks in Roundcube + +Download the latest release of [RCMCardDAV](https://github.com/mstilkerich/rcmcarddav) to the Roundcube plugin directory and extract it (here `rc/plugins`): +``` +cd data/web/rc/plugins +wget -O - https://github.com/mstilkerich/rcmcarddav/releases/download/v4.3.0/carddav-v4.3.0.tar.gz | tar xfvz - +chown -R root: carddav/ +``` + +Copy the file `config.inc.php.dist` to `config.inc.php` (here in `rc/plugins/carddav`) and append the following preset to the end of the file - don't forget to replace `mx.example.org` with your own hostname: +``` +$prefs['SOGo'] = array( + 'name' => 'SOGo', + 'username' => '%u', + 'password' => '%p', + 'url' => 'https://mx.example.org/SOGo/dav/%u/', + 'carddav_name_only' => true, + 'use_categories' => true, + 'active' => true, + 'readonly' => false, + 'refresh_time' => '02:00:00', + 'fixed' => array( 'active', 'name', 'username', 'password', 'refresh_time' ), + 'hide' => false, +); +``` +Please note, that this preset only integrates the default addressbook (the one that's named "Personal Address Book" and can't be deleted). Additional addressbooks are currently not automatically detected but can be manually added within the roundecube settings. + +Enable the plugin by adding `carddav` to `$config['plugins']` in `rc/config/config.inc.php`. + +If you want to remove the default addressbooks (stored in the Roundcube database), so that only the CardDAV addressbooks are accessible, append `$config['address_book_type'] = '';` to the config file `data/web/rc/config/config.inc.php`. + +--- + +Optionally, you can add Roundcube's link to the mailcow Apps list. +To do this, open or create `data/web/inc/vars.local.inc.php` and add the following code-block: + +*NOTE: Don't forget to add the ` 'SOGo', + 'link' => '/SOGo/' + ), + array( + 'name' => 'Roundcube', + 'link' => '/rc/' + ) +); +... +```` + +## Upgrading Roundcube + +Upgrading Roundcube is rather simple, go to the [Github releases](https://github.com/roundcube/roundcubemail/releases) page for Roundcube and get the link for the "complete.tar.gz" file for the wanted release. Then follow the below commands and change the URL and Roundcube folder name if needed. + + +``` +# Enter a bash session of the mailcow PHP container +docker exec -it mailcowdockerized_php-fpm-mailcow_1 bash + +# Install required upgrade dependency, then upgrade Roundcube to wanted release +apk add rsync +cd /tmp +wget -O - https://github.com/roundcube/roundcubemail/releases/download/1.5.2/roundcubemail-1.5.2-complete.tar.gz | tar xfvz - +cd roundcubemail-1.5.2 +bin/installto.sh /web/rc + +# Type 'Y' and press enter to upgrade your install of Roundcube + +# Remove leftover files +cd /tmp +rm -rf roundcube* + +# Fix Allow remote resources (https://github.com/roundcube/roundcubemail/issues/8170) should not be required in 1.6 +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). + +Edit `mailcow.conf` and add the following: + +``` +# Allow admins to log into Roundcube as email user (without any password) +# Roundcube with plugin dovecot_impersonate must be installed first + +ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE=y +``` + +Edit `docker-compose.override.yml` and crate/extend the section for `php-fpm-mailcow`: + +```yml +version: '2.1' +services: + php-fpm-mailcow: + environment: + - ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE=${ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE:-n} +``` + + +Edit `data/web/js/site/mailbox.js` and the following code after [`if (ALLOW_ADMIN_EMAIL_LOGIN) { ... }`](https://github.com/mailcow/mailcow-dockerized/blob/2f9da5ae93d93bf62a8c2b7a5a6ae50a41170c48/data/web/js/site/mailbox.js#L485-L487) + +```js +if (ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE) { + item.action += ''; +} +``` + +Edit `data/web/mailbox.php` and add this line to array [`$template_data`](https://github.com/mailcow/mailcow-dockerized/blob/2f9da5ae93d93bf62a8c2b7a5a6ae50a41170c48/data/web/mailbox.php#L33-L43): + +```php + 'allow_admin_email_login_roundcube' => (preg_match("/^(yes|y)+$/i", $_ENV["ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE"])) ? 'true' : 'false', +``` + +Edit `data/web/templates/mailbox.twig` and add this code to the bottom of the [javascript section](https://github.com/mailcow/mailcow-dockerized/blob/2f9da5ae93d93bf62a8c2b7a5a6ae50a41170c48/data/web/templates/mailbox.twig#L49-L57): + +```js + var ALLOW_ADMIN_EMAIL_LOGIN_ROUNDCUBE = {{ allow_admin_email_login_roundcube }}; +``` + +Copy the contents of the following files from this [Snippet](https://gitlab.com/-/snippets/2038244): + +* `data/web/inc/lib/RoundcubeAutoLogin.php` +* `data/web/rc-auth.php` + +Finally, restart mailcow + +``` +docker-compose down +docker-compose up -d +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5d3498809..0292477fa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -143,15 +143,15 @@ nav: - 'Windows Mail': 'client/client-windows.md' - 'Manual configuration': 'client/client-manual.md' - 'Third party apps': - - 'Borgmatic Backup': 'third_party-borgmatic.md' - - 'Exchange Hybrid Setup': 'third_party-exchange_onprem.md' - - 'Gitea': 'third_party-gitea.md' - - 'Gogs': 'third_party-gogs.md' - - 'Mailman 3': 'third_party-mailman3.md' - - 'Mailpiler Integration': 'third_party-mailpiler_integration.md' - - 'Nextcloud': 'third_party-nextcloud.md' - - 'Portainer': 'third_party-portainer.md' - - 'Roundcube': 'third_party-roundcube.md' + - 'Borgmatic Backup': 'third_party/third_party-borgmatic.md' + - 'Exchange Hybrid Setup': 'third_party/third_party-exchange_onprem.md' + - 'Gitea': 'third_party/third_party-gitea.md' + - 'Gogs': 'tthird_party/hird_party-gogs.md' + - 'Mailman 3': 'third_party/third_party-mailman3.md' + - 'Mailpiler Integration': 'third_party/third_party-mailpiler_integration.md' + - 'Nextcloud': 'third_party/third_party-nextcloud.md' + - 'Portainer': 'third_party/third_party-portainer.md' + - 'Roundcube': 'third_party/third_party-roundcube.md' plugins: - search