mailcow · h3ssan · Sep 6, 2024 · Sep 6, 2024 · Sep 9, 2024 · Sep 9, 2024
diff --git a/docs/backup_restore/b_n_r-backup.de.md b/docs/backup_restore/b_n_r-backup.de.md
@@ -1,64 +1,89 @@
-### Sicherung
+### Vorwort
 
-#### Anleitung
+!!! danger "Achtung"
+
+    Die Syntax des Backup Skriptes hat sich mit dem Update 2024-09 drastisch im Rahmen der Neuentwicklung des Skriptes verändert. Sollten automatische Sicherungsprozesse auf Ihrem System laufen ändern Sie diese bitte dementsprechend ab.
+
+    Wichtig zu beachten ist die Auslagerung des `--delete-days` Parameters in die neue und separat auszuführende Funktion `-d`.
+
+    Ebenfalls wichtig: Die neue Variable `--yes`, welche für Automatisierungen verwendet wird.
+
+    Bitte entnehmen Sie die geänderten Syntaxe aus dieser Dokumentation.
+
+### Anleitung
 
 Sie können das mitgelieferte Skript `helper-scripts/backup_and_restore.sh` verwenden, um mailcow automatisch zu sichern.
 
 !!! danger "Achtung"
     **Bitte kopieren Sie dieses Skript nicht an einen anderen Ort.**
 
-Um ein Backup zu starten, geben Sie "backup" als ersten Parameter an und entweder eine oder mehrere zu sichernde Komponenten als folgende Parameter.
-Sie können auch "all" als zweiten Parameter verwenden, um alle Komponenten zu sichern. Fügen Sie `--delete-days n` an, um Sicherungen zu löschen, die älter als n Tage sind.
+Um ein Backup zu starten nutzen Sie bitte den Parameter `-b` oder `--backup` zusammen mit dem Zielpfad für das Backup im Schema `/path/to/backup/folder`.
+Geben Sie bitte auch mit `-c` oder `--component` die zu sichernden Komponenten an.
+
+Es folgen einige Beispiele:
 
 ```
-# Syntax:
-# ./helper-scripts/backup_and_restore.sh backup (vmail|crypt|redis|rspamd|postfix|mysql|all|--delete-days)
+# Für die Syntax Anzeige oder allgemeine Hilfe
+# ./helper-scripts/backup_and_restore.sh --help
 
-# Alles sichern, Sicherungen älter als 3 Tage löschen
-./helper-scripts/backup_and_restore.sh backup all --delete-days 3
+# Alle Komponenten nach "/opt/backups" sichern ohne extra Aufforderungen (Ideal für automatische Sicherungen):
+./helper-scripts/backup_and_restore.sh --backup /opt/backups --component all --yes
 
-# vmail-, crypt- und mysql-Daten sichern, Sicherungen löschen, die älter als 30 Tage sind
-./helper-scripts/backup_and_restore.sh backup vmail crypt mysql --delete-days 30
+# Die kurze Variante des selbigen Befehls:
+./helper-scripts/backup_and_restore.sh -b /opt/backups -c all
 
-# vmail sichern
-./helper-scripts/backup_and_restore.sh backup vmail
+# Nur vmail, crypt und mysql Daten sichern
+./helper-scripts/backup_and_restore.sh -b /opt/backups -c vmail -c crypt -c mysql
+
+# Nur vmail sichern
+./helper-scripts/backup_and_restore.sh -b /opt/backups -c vmail
 
 ```
 
-#### Variablen für Backup/Restore Skript
+#### Variablen für das Backup/Restore Skript
 ##### Multithreading
-Seit dem 2022-10 Update ist es möglich das Skript mit Multithreading Support laufen zu lassen. Dies lässt sich sowohl für Backups aber auch für Restores nutzen.
+Um das Backup bzw. den Restore mit mehreren Threads zu starten, nutzen Sie bitte den  `--threads <num>` oder den kurzen `-t <num>` Parameter.
 
-Um das Backup/den Restore mit Multithreading zu starten muss `THREADS` als Umgebungsvariable vor dem Befehl zum starten hinzugefügt werden.
+Beispiel:
 
 ```
-THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
+/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -b /opt/backups -c all -t 14
 ```
-Die Anzahl hinter dem `=` Zeichen gibt dabei dann die Thread Anzahl an. Nehmen Sie bitte immer ihre Kernanzahl -2 um mailcow selber noch genug CPU Leistung zu lassen.
 
-##### Backup Pfad
-Das Skript wird Sie nach einem Speicherort für die Sicherung fragen. Innerhalb dieses Speicherortes wird es Ordner im Format "mailcow_DATE" erstellen.
-Sie sollten diese Ordner nicht umbenennen, um den Wiederherstellungsprozess nicht zu stören.
+!!! info "Hinweis"
 
-Um ein Backup unbeaufsichtigt durchzuführen, definieren Sie MAILCOW_BACKUP_LOCATION als Umgebungsvariable, bevor Sie das Skript starten:
+    Bitte behalten Sie Ihre Kernanzahl um 2 reduziert, um genügend CPU-Leistung für mailcow selbst zu lassen. Wenn Sie beispielsweise 16 Kerne haben, übergeben Sie `-t 14`.
+
+##### Backup-Pfad
+
+Sie sollten den Backup-Pfad direkt nach dem Parameter `-b`|`--backup` angeben. Innerhalb dieses Verzeichnisses werden Ordner im Format "*mailcow_DATUM*" erstellt.
+Sie sollten diese Ordner nicht umbenennen, um den Wiederherstellungsprozess nicht zu beeinträchtigen.
+
+Um ein Backup unbeaufsichtigt durchzuführen, definieren Sie die Umgebungsvariable MAILCOW_BACKUP_LOCATION, bevor Sie das Skript starten:
+
+```bash
+
+MAILCOW_BACKUP_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all --yes
 
-```
-MAILCOW_BACKUP_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
 ```
 
+!!! danger "Achtung"
+    Bitte genau hinsehen: Die Variable hier heißt `MAILCOW_BACKUP_LOCATION`
+
 !!! tip "Tipp"
-        Beide oben genannten Variablen können auch kombiniert werden! Bsp:
-        ```
-        MAILCOW_BACKUP_LOCATION=/opt/backup THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
-        ```
+    Beide oben genannten Variablen können auch kombiniert werden! Bsp:
+
+    ```bash
+    MAILCOW_BACKUP_LOCATION=/opt/backups MAILCOW_BACKUP_RESTORE_THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all --yes
+    ```
 
 #### Cronjob
 
-Sie können das Backup-Skript regelmäßig über einen Cronjob laufen lassen. Stellen Sie sicher, dass `BACKUP_LOCATION` existiert:
+Sie können das Backup-Skript regelmäßig über einen Cronjob laufen lassen. Stellen Sie sicher, dass `MAILCOW_BACKUP_LOCATION` existiert:
 
 ```
 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/mnt/mailcow_backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup mysql crypt redis --delete-days 3
+5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh --backup -c mysql -c crypt -c redis --yes
 ```
 
 Standardmäßig sendet Cron das komplette Ergebnis jeder Backup-Operation per E-Mail. Wenn Sie möchten, dass cron nur im Fehlerfall (Exit-Code ungleich Null) eine E-Mail sendet, können Sie den folgenden Ausschnitt verwenden. Die Pfade müssen entsprechend Ihrer Einrichtung angepasst werden (dieses Skript ist ein Beitrag eines Benutzers).
@@ -68,28 +93,28 @@ Das folgende Skript kann in `/etc/cron.daily/mailcow-backup` platziert werden -
 ```
 #!/bin/sh
 
-# Backup mailcow data
-# https://docs.mailcow.email/b_n_r_backup/
+# Backup mailcow Docs
+# https://docs.mailcow.email/backup_restore/b_n_r-backup/
 
 set -e
 
 OUT="$(mktemp)"
 export MAILCOW_BACKUP_LOCATION="/opt/backup"
+export MAILCOW_BACKUP_RESTORE_THREADS="2"
 SCRIPT="/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh"
-PARAMETERS="backup all"
-OPTIONS="--delete-days 30"
+PARAMETERS=(-c all)
+OPTIONS=(--yes)
 
 # run command
 set +e
-"${SCRIPT}" ${PARAMETERS} ${OPTIONS} 2>&1 > "$OUT"
+"${SCRIPT}" "${PARAMETERS[@]}" "${OPTIONS[@]}" 2>&1 > "$OUT"
 RESULT=$?
 
-if [ $RESULT -ne 0 ]
-    then
-            echo "${SCRIPT} ${PARAMETERS} ${OPTIONS} encounters an error:"
-            echo "RESULT=$RESULT"
-            echo "STDOUT / STDERR:"
-            cat "$OUT"
+if [ $RESULT -ne 0 ]; then
+  echo "${SCRIPT} ${PARAMETERS[@]} ${OPTIONS[@]} encounters an error:"
+  echo "RESULT=$RESULT"
+  echo "STDOUT / STDERR:"
+  cat "$OUT"
 fi
 ```
 
@@ -105,7 +130,8 @@ Cronjobs erstellen:
 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 25 1 * * * rsync -aH --delete /opt/mailcow-dockerized /external_share/backups/mailcow-dockerized
 40 2 * * * rsync -aH --delete /var/lib/docker/volumes /external_share/backups/var_lib_docker_volumes
-5 4 * * * cd /opt/mailcow-dockerized/; BACKUP_LOCATION=/external_share/backups/backup_script /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup mysql crypt redis --delete-days 3
+5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/external_share/backups/backup_script /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c mysql -c crypt -c redis --yes
+5 4 * * * cd /opt/mailcow-dockerized/; /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh --delete /external_share/backups/backup_script 3 --yes
 # Wenn Sie wollen, benutzen Sie das Werkzeug acl, um die Berechtigungen einiger/aller Ordner/Dateien zu sichern: getfacl -Rn /path
 ```
 

diff --git a/docs/backup_restore/b_n_r-backup.en.md b/docs/backup_restore/b_n_r-backup.en.md
@@ -1,64 +1,82 @@
-### Backup
+### Foreword
 
-#### Manual
+!!! danger "Warning"
+
+    The syntax of the backup script has drastically changed with the 2024-09 update as part of the script's redevelopment. If automated backup processes are running on your system, please adjust them accordingly.
+
+    Important to note is the relocation of the `--delete-days` parameter to the new and separately executable function `-d`.
+
+    Also important: the new `--yes` variable, which is used for automation.
+
+    Please refer to this documentation for the updated syntax.
+
+### Manual
 
 You can use the provided script `helper-scripts/backup_and_restore.sh` to backup mailcow automatically.
 
 !!! danger
     **Please do not copy this script to another location.**
 
-To run a backup, write "backup" as first parameter and either one or more components to backup as following parameters.
-You can also use "all" as second parameter to backup all components. Append `--delete-days n` to delete backups older than n days.
+To run a backup, use flag "-b" or "--backup" along with "/path/to/backup/folder", also pass "-c" or "--component"
+to select the component(s) which you want to backup.
 
 ```
-# Syntax:
-# ./helper-scripts/backup_and_restore.sh backup (vmail|crypt|redis|rspamd|postfix|mysql|all|--delete-days)
+# For syntax and usage help:
+# ./helper-scripts/backup_and_restore.sh --help
+
+# Backup all components to "/opt/backups" folder with no prompts (good for automation):
+./helper-scripts/backup_and_restore.sh --backup /opt/backups --component all --yes
 
-# Backup all, delete backups older than 3 days
-./helper-scripts/backup_and_restore.sh backup all --delete-days 3
+# Also, there's short version of the flags:
+./helper-scripts/backup_and_restore.sh -b /opt/backups -c all
 
-# Backup vmail, crypt and mysql data, delete backups older than 30 days
-./helper-scripts/backup_and_restore.sh backup vmail crypt mysql --delete-days 30
+# Backup vmail, crypt and mysql data
+./helper-scripts/backup_and_restore.sh -b /opt/backups -c vmail -c crypt -c mysql
 
 # Backup vmail
-./helper-scripts/backup_and_restore.sh backup vmail
+./helper-scripts/backup_and_restore.sh -b /opt/backups -c vmail
 
 ```
 
 #### Variables for backup/restore script
 ##### Multithreading
-With the 2022-10 update it is possible to run the script with multithreading support. This can be used for backups as well as for restores.
-
-To start the backup/restore with multithreading you have to add `THREADS` as an environment variable in front of the command to execute the script.
+To start the backup/restore with multithreading you have to add `--threads <num>` or short one `-t <num>` flag.
 
 ```
-THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
+/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -b /opt/backups -c all -t 14
 ```
-The number after the `=` character indicates the number of threads. Please keep your core count -2 to leave enough CPU power for mailcow itself.
+Please keep your core count -2 to leave enough CPU power for mailcow itself, such as if you have 16 cores, then pass `-t 14`.
 
 ##### Backup path
-The script will ask you for a backup location. Inside of this location it will create folders in the format "mailcow_DATE".
+You should pass the backup path right after `-b`|`--backup` flag, Inside of this location it will create folders in the format "mailcow_DATE".
 You should not rename those folders to not break the restore process.
 
 To run a backup unattended, define MAILCOW_BACKUP_LOCATION as environment variable before starting the script:
 
 ```
-MAILCOW_BACKUP_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
+MAILCOW_BACKUP_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all --yes
 ```
 
+!!! danger
+    Please look closeley: The variable here is called `MAILCOW_BACKUP_LOCATION`
+
+!!! tip
+    Both variables mentioned above can also be combined! Ex:
+
+    ```bash
+    MAILCOW_BACKUP_LOCATION=/opt/backups MAILCOW_BACKUP_RESTORE_THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all --yes
+    ```
+
 !!! tip
-        Both variables mentioned above can also be combined! Ex:
-        ```
-        MAILCOW_BACKUP_LOCATION=/opt/backup THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all
-        ```
+        Please note: If you specified `MAILCOW_BACKUP_LOCATION` environment variable then there's no need to pass the `-b`|`--backup` flag
 
 #### Cronjob
 
-You can run the backup script regularly via cronjob. Make sure `BACKUP_LOCATION` exists:
+You can run the backup script regularly via cronjob. Make sure `MAILCOW_BACKUP_LOCATION` exists:
 
 ```
 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/mnt/mailcow_backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup mysql crypt redis --delete-days 3
+5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh --backup -c mysql -c crypt -c redis --yes
 ```
 
 Per default cron sends the full result of each backup operation by email. If you want cron to only mail on error (non-zero exit code) you may want to use the following snippet. Pathes need to be modified according to your setup (this script is a user contribution).
@@ -68,28 +86,28 @@ This following script may be placed in `/etc/cron.daily/mailcow-backup` - do not
 ```
 #!/bin/sh
 
-# Backup mailcow data
+# Backup mailcow Docs
 # https://docs.mailcow.email/backup_restore/b_n_r-backup/
 
 set -e
 
 OUT="$(mktemp)"
 export MAILCOW_BACKUP_LOCATION="/opt/backup"
+export MAILCOW_BACKUP_RESTORE_THREADS="2"
 SCRIPT="/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh"
-PARAMETERS="backup all"
-OPTIONS="--delete-days 30"
+PARAMETERS=(-c all)
+OPTIONS=(--yes)
 
 # run command
 set +e
-"${SCRIPT}" ${PARAMETERS} ${OPTIONS} 2>&1 > "$OUT"
+"${SCRIPT}" "${PARAMETERS[@]}" "${OPTIONS[@]}" 2>&1 > "$OUT"
 RESULT=$?
 
-if [ $RESULT -ne 0 ]
-    then
-            echo "${SCRIPT} ${PARAMETERS} ${OPTIONS} encounters an error:"
-            echo "RESULT=$RESULT"
-            echo "STDOUT / STDERR:"
-            cat "$OUT"
+if [ $RESULT -ne 0 ]; then
+  echo "${SCRIPT} ${PARAMETERS[@]} ${OPTIONS[@]} encounters an error:"
+  echo "RESULT=$RESULT"
+  echo "STDOUT / STDERR:"
+  cat "$OUT"
 fi
 ```
 
@@ -105,7 +123,8 @@ Create cronjobs:
 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
 25 1 * * * rsync -aH --delete /opt/mailcow-dockerized /external_share/backups/mailcow-dockerized
 40 2 * * * rsync -aH --delete /var/lib/docker/volumes /external_share/backups/var_lib_docker_volumes
-5 4 * * * cd /opt/mailcow-dockerized/; BACKUP_LOCATION=/external_share/backups/backup_script /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup mysql crypt redis --delete-days 3
+5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/external_share/backups/backup_script /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c mysql -c crypt -c redis --yes
+5 4 * * * cd /opt/mailcow-dockerized/; /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh --delete /external_share/backups/backup_script 3 --yes
 # If you want to, use the acl util to backup permissions of some/all folders/files: getfacl -Rn /path
 ```
 

diff --git a/docs/backup_restore/b_n_r-delete.de.md b/docs/backup_restore/b_n_r-delete.de.md
@@ -0,0 +1,72 @@
+# Alte Backups Löschen
+
+Seit dem neuen Backup Skript (eingeführt in mailcow Version 2024-09) ist es nun separat (auch ohne Backup Job) möglich, alte Backups zu löschen.
+
+Verwenden Sie dazu den neuen Parameter `--delete` oder die Kurzform `-d` samt der Anzahl der zu behaltenden Tage.
+
+Beispiele:
+
+```bash
+
+# Löscht alte Backups (älter als 3 Tage) aus dem Pfad /opt/backups:
+./helper-scripts/backup_and_restore.sh --delete /opt/backups 3
+
+# Löscht alte Backups (älter als 30 Tage) aus dem Pfad /opt/backups
+# ohne weitere Eingabe vom Benutzer (Ideal zur Automatisierung):
+./helper-scripts/backup_and_restore.sh --delete /opt/backups 30 --yes
+
+```
+
+#### Variablen für das Backup/Restore Skript
+##### Backup-Pfad
+
+Um ältere Backups unbeaufsichtigt zu löschen, definieren Sie die Umgebungsvariable `MAILCOW_BACKUP_LOCATION`, bevor Sie das Skript starten:
+
+```bash
+
+MAILCOW_BACKUP_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh --delete 30 --yes
+
+```
+
+!!! danger "Achtung"
+    Bitte genau hinsehen: Die Variable hier heißt `MAILCOW_BACKUP_LOCATION`
+
+#### Cronjob
+
+Sie können das Backup-Skript regelmäßig über einen Cronjob alte Backups löschen lassen. Stellen Sie sicher, dass `MAILCOW_BACKUP_LOCATION` existiert:
+
+```bash
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+5 4 * * * cd /opt/mailcow-dockerized/; MAILCOW_BACKUP_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh --delete 3 --yes
+```
+
+Standardmäßig sendet Cron das komplette Ergebnis jeder Löschungs-Operation per E-Mail. Wenn Sie möchten, dass cron nur im Fehlerfall (Exit-Code ungleich Null) eine E-Mail sendet, können Sie den folgenden Ausschnitt verwenden. Die Pfade müssen entsprechend Ihrer Einrichtung angepasst werden (dieses Skript ist ein Beitrag eines Benutzers).
+
+Das folgende Skript kann in `/etc/cron.daily/mailcow-backup-delete` platziert werden - vergessen Sie nicht, es mit `chmod +x` als ausführbar zu markieren:
+
+```bash
+#!/bin/sh
+
+# Backup Delete mailcow Docs
+# https://docs.mailcow.email/backup_restore/b_n_r-delete/
+
+set -e
+
+OUT="$(mktemp)"
+export MAILCOW_BACKUP_LOCATION="/opt/backup"
+SCRIPT="/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh"
+PARAMETERS=(--delete 30)
+OPTIONS=(--yes)
+
+# run command
+set +e
+"${SCRIPT}" "${PARAMETERS[@]}" "${OPTIONS[@]}" 2>&1 > "$OUT"
+RESULT=$?
+
+if [ $RESULT -ne 0 ]; then
+  echo "${SCRIPT} ${PARAMETERS[@]} ${OPTIONS[@]} encounters an error:"
+  echo "RESULT=$RESULT"
+  echo "STDOUT / STDERR:"
+  cat "$OUT"
+fi
+```