diff --git a/docs/backup_restore/b_n_r-backup.de.md b/docs/backup_restore/b_n_r-backup.de.md index 0d738fd13a..af1fecf818 100644 --- 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 ` oder den kurzen `-t ` 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 index f6668c8d51..c3a877b19d 100644 --- 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 ` or short one `-t ` 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 new file mode 100644 index 0000000000..ebba366cb0 --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/backup_restore/b_n_r-delete.en.md b/docs/backup_restore/b_n_r-delete.en.md new file mode 100644 index 0000000000..fa776e2dda --- /dev/null +++ b/docs/backup_restore/b_n_r-delete.en.md @@ -0,0 +1,68 @@ +# Delete Old Backups + +Since the new backup script (introduced in mailcow version 2024-09), it is now possible to delete old backups separately (even without running a backup job). + +To do this, use the new `--delete` parameter or the short form `-d` along with the number of days to keep. + +Examples: + +```bash +# Deletes old backups (older than 3 days) from the path /opt/backups: +./helper-scripts/backup_and_restore.sh --delete /opt/backups 3 + +# Deletes old backups (older than 30 days) from the path /opt/backups +# without any further input from the user (ideal for automation): +./helper-scripts/backup_and_restore.sh --delete /opt/backups 30 --yes +``` + +#### Variables for the Backup/Restore Script +##### Backup Path + +To delete older backups unattended, define the environment variable `MAILCOW_BACKUP_LOCATION` before starting the script: + +```bash +MAILCOW_BACKUP_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh --delete 30 --yes +``` + +!!! danger + Please look closeley: The variable here is called `MAILCOW_BACKUP_LOCATION` + +#### Cronjob + +You can schedule the backup script to delete old backups regularly using a cron job. Make sure that `MAILCOW_BACKUP_LOCATION` exists: + +```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 +``` + +By default, cron sends the complete output of every deletion operation via email. If you only want cron to send an email in case of an error (exit code not equal to zero), you can use the following snippet. The paths must be adjusted according to your setup (this script is a user contribution). + +The following script can be placed in `/etc/cron.daily/mailcow-backup-delete` - don't forget to mark it as executable with `chmod +x`: + +```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 +``` diff --git a/docs/backup_restore/b_n_r-restore.de.md b/docs/backup_restore/b_n_r-restore.de.md index b0f8b85c32..c250c75721 100644 --- a/docs/backup_restore/b_n_r-restore.de.md +++ b/docs/backup_restore/b_n_r-restore.de.md @@ -1,90 +1,100 @@ -### Wiederherstellung -#### Variablen für Backup/Restore Skript +#### Variablen für das Backup/Wiederherstellungsskript ##### 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/den Restore mit Multithreading zu starten muss `THREADS` als Umgebungsvariable vor dem Befehl zum starten hinzugefügt werden. +Um die Sicherung/Wiederherstellung mit Multithreading zu starten, müssen Sie den Parameter `--threads ` oder die Kurzform `-t ` hinzufügen. +```bash +/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -r /opt/backups -c all -t 14 ``` -THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh restore + +!!! info "Hinweis" + Die Zahl nach dem `-t` Zeichen gibt die Anzahl der Threads an. Bitte reduzieren Sie Ihre Kernanzahl um 2, um genügend CPU-Leistung für mailcow selbst zu lassen. + +##### Backup-Pfad +Sie sollten den Pfad des Backup-Verzeichnisses direkt nach dem Parameter `-r`|`--restore` angeben. Das Skript durchsucht das Verzeichnis nach allen Backups und fordert Sie anschließend auf, das Backup auszuwählen, das Sie wiederherstellen möchten. + +Um eine Wiederherstellung unbeaufsichtigt durchzuführen, definieren Sie die Umgebungsvariable `MAILCOW_RESTORE_LOCATION`, bevor Sie das Skript starten: + +```bash +MAILCOW_RESTORE_LOCATION=/opt/backups /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all ``` -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. +!!! danger "Achtung" + Bitte genau hinsehen: Die Variable hier heißt `MAILCOW_RESTORE_LOCATION` -Um ein Backup unbeaufsichtigt durchzuführen, definieren Sie MAILCOW_BACKUP_LOCATION als Umgebungsvariable, bevor Sie das Skript starten: +Oder übergeben Sie den Parameter `-r`|`--restore` mit dem Wiederherstellungspfad als Argument an das Skript: ```bash -MAILCOW_BACKUP_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup all +/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -r /opt/backups -c all ``` -!!! tip "Tipp" - Beide oben genannten Variablen können auch kombiniert werden! Bsp: +!!! tip + Beide oben genannten Variablen können auch kombiniert werden! Beispiel: ```bash - MAILCOW_BACKUP_LOCATION=/opt/backup THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh restore + MAILCOW_RESTORE_LOCATION=/opt/backups MAILCOW_BACKUP_RESTORE_THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all ``` -#### Wiederherstellung der Daten +!!! tip + Sie sollten die Komponente(n), die Sie wiederherstellen möchten, mit `-c` oder `--component` angeben, oder einfach `-c all` verwenden! Beispiel: + ```bash + MAILCOW_RESTORE_LOCATION=/opt/backups MAILCOW_BACKUP_RESTORE_THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c vmail -c crypt -c mysql + ``` -!!! danger "Achtung" +#### Daten wiederherstellen + +!!! danger **Bitte kopieren Sie dieses Skript nicht an einen anderen Ort.** -!!! danger "Achtung für ältere Installationen" - Bitte schauen Sie **VOR** der Wiederherstellung Ihres mailcow Systemes auf einen neuen Server und einem sauberen mailcow-dockerized Ordner, ob in Ihrer mailcow.conf der Wert `MAILDIR_SUB` gesetzt ist. Falls dieser nicht gesetzt ist, so setzen Sie diesen auch bitte in Ihrer neuen mailcow nicht, bzw. entfernen diesen, da sonst **KEINE** E-Mails angezeigt werden. Dovecot lädt E-Mails aus dem besagtem Unterordner des Maildir Volumes unter `$DOCKER_VOLUME_PFAD/mailcowdockerized_vmail-vol-1` und bei Änderung im Vergleich zum Ursprungszustand sind dort keine Mails vorhanden. +!!! danger "Gefahr für ältere Installationen" + Bevor Sie Ihr mailcow-System auf einem neuen Server und einem sauberen mailcow-dockerized-Ordner wiederherstellen, überprüfen Sie bitte, ob der Wert `MAILDIR_SUB` in Ihrer mailcow.conf gesetzt ist. Wenn dieser Wert nicht gesetzt ist, setzen Sie ihn nicht auf Ihrem neuen mailcow Server oder entfernen Sie ihn, da sonst **KEINE** E-Mails angezeigt werden. Dovecot lädt E-Mails aus dem angegebenen Unterordner des Maildir-Volumes unter `$DOCKER_VOLUME_PATH/mailcowdockerized_vmail-vol-1` und wenn es im Vergleich zum Originalzustand eine Änderung gibt, werden keine E-Mails verfügbar sein. -Um eine Wiederherstellung durchzuführen, **starten Sie mailcow**, verwenden Sie das Skript mit "restore" als ersten Parameter. +Um eine Wiederherstellung durchzuführen, **starten Sie mailcow**, und verwenden Sie das Skript mit `--restore` oder `-r` zusammen mit dem Pfad zum Backup-Verzeichnis: -``` { .yaml .no-copy } +```bash # Syntax: -# ./helper-scripts/backup_and_restore.sh restore - +./helper-scripts/backup_and_restore.sh -r /opt/backups -c all ``` -Das Skript wird Sie nach einem Speicherort für die Sicherung der mailcow_DATE-Ordner fragen: - -``` { .bash .no-copy } -Backup location (absolute path, starting with /): /opt/backup -``` - -Anschließend werden alle verfügbaren Backups in dem angegebenen Ordner (in unserem Beispiel `/opt/backup`) angezeigt: +Alle verfügbaren Backups im angegebenen Ordner (in unserem Beispiel `/opt/backups`) werden dann angezeigt: ``` { .bash .no-copy } Found project name mailcowdockerized -[ 1 ] - /opt/backup/mailcow-2023-12-11-13-27-14/ -[ 2 ] - /opt/backup/mailcow-2023-12-11-14-02-06/ +Using /opt/backups as restore location... +[ 1 ] - /opt/backups/mailcow-2023-12-11-13-27-14/ +[ 2 ] - /opt/backups/mailcow-2023-12-11-14-02-06/ ``` -Nun können Sie die Nummer Ihres Backups angeben, welches Sie Wiederherstellen wollen, in diesem Beispiel die 2: +Nun können Sie die Nummer des Backups eingeben, das Sie wiederherstellen möchten, in diesem Beispiel das zweite Backup: ``` { .bash .no-copy } Select a restore point: 2 ``` -Das Skript wird nun alle gesicherten Komponenten Anzeigen, die Sie wiederherstellen können, in unserem Fall haben wir beim Backup Prozess `all` also Alles gewählt, dementsprechend taucht das hier nun auf: +Das Skript zeigt nun alle gesicherten Komponenten an, die es wiederherstellen wird. +In unserem Fall haben wir `all` für den Backup-Prozess ausgewählt, daher werden diese Komponenten hier angezeigt: ``` { .bash .no-copy } -[ 0 ] - all +Matching available components to restore: [ 1 ] - Crypt data [ 2 ] - Rspamd data [ 3 ] - Mail directory (/var/vmail) [ 4 ] - Redis DB [ 5 ] - Postfix data [ 6 ] - SQL DB + +Restoring will start in 5 seconds. Press Ctrl+C to stop. ``` -Auch hier wählen wir nun wieder die Komponente aus, die wir wiederherstellen wollen. Option 0 stellt **ALLES** wieder her. +Nun warten Sie 5 Sekunden, bevor die oben genannten Komponenten wiederhergestellt werden! Wenn Sie den Wiederherstellungsprozess abbrechen möchten, drücken Sie `Ctrl+C`, um den Prozess zu stoppen. -??? warning "Wenn Sie auf eine andere Architektur wiederherstellen wollen..." - Sollten Sie das Backup auf einer anderen Architektur bspw. x86 gemacht haben und wollen dieses Backup nun auf ARM64 wiederherstellen, so wird das Backup von Rspamd als inkompatibel angezeigt und ist nicht einzeln anwählbar. Bei der Wiederherstellung mit Aufruf der Taste 0 wird die Wiederherstellung von Rspamd ebenfalls übersprungen. +??? warning "Wenn Sie auf eine andere Architektur wiederherstellen möchten..." + Wenn Sie das Backup auf einer anderen Architektur erstellt haben, z. B. x86, und dieses Backup jetzt auf ARM64 wiederherstellen möchten, wird das Backup von Rspamd als inkompatibel angezeigt und kann nicht einzeln ausgewählt werden. Beim Wiederherstellen aller Komponenten wird die Wiederherstellung von Rspamd ebenfalls übersprungen. - Beispiel für inkompatibles Rspamd Backup im Auswahl Menü: + Beispiel eines inkompatiblen Rspamd-Backups im Auswahlmenü: - ``` { .bash .no-copy } + ``` { .bash .no-copy } [...] [ NaN ] - Rspamd data (incompatible Arch, cannot restore it) [...] ``` -Nun wird mailcow die von Ihnen ausgewählten Sicherungen wiederherstellen. Bitte beachten Sie, dass je nach Größe der Sicherungen die Wiederherstellung eine gewisse Zeit in Anspruch nehmen kann. \ No newline at end of file +Nun wird mailcow die von Ihnen ausgewählten Backups wiederherstellen. Bitte beachten Sie, dass die Wiederherstellung je nach Größe der Backups einige Zeit in Anspruch nehmen kann. diff --git a/docs/backup_restore/b_n_r-restore.en.md b/docs/backup_restore/b_n_r-restore.en.md index b9eb64cf6e..7b70f8b1fe 100644 --- a/docs/backup_restore/b_n_r-restore.en.md +++ b/docs/backup_restore/b_n_r-restore.en.md @@ -1,29 +1,43 @@ ### Restore #### 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 ` or short one `-t ` flag. ``` -THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh restore +/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -r /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. +!!! info + The number after the `-t` character indicates the number of threads. Please keep your core count -2 to leave enough CPU power for mailcow itself. ##### 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 not rename those folders to not break the restore process. +You should pass the path of the backup directory right after `-r`|`--restore` flag, It will search through the directory to find all backups, +and then it will prompt you to choose the backup you want to restore. + +To run a restore unattended, define MAILCOW_RESTORE_LOCATION as environment variable before starting the script: + +```bash +MAILCOW_RESTORE_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all +``` -To run a backup unattended, define MAILCOW_BACKUP_LOCATION as environment variable before starting the script: +!!! danger + Please look closeley: The variable here is called `MAILCOW_RESTORE_LOCATION` + +Or, pass `-r`|`--restore` with the restore path as argument to the script: ```bash -MAILCOW_BACKUP_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh restore +/opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -r /opt/backup -c all ``` !!! tip Both variables mentioned above can also be combined! Ex: ```bash - MAILCOW_BACKUP_LOCATION=/opt/backup THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh restore + MAILCOW_RESTORE_LOCATION=/opt/backup MAILCOW_BACKUP_RESTORE_THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c all + ``` + +!!! tip + You should specify the component(s) you want to restore with `-c` or `--component`, or just `-c all`! Ex: + ```bash + MAILCOW_RESTORE_LOCATION=/opt/backup MAILCOW_BACKUP_RESTORE_THREADS=14 /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh -c vmail -c crypt -c mysql ``` #### Restoring Data @@ -34,24 +48,18 @@ MAILCOW_BACKUP_LOCATION=/opt/backup /opt/mailcow-dockerized/helper-scripts/backu !!! danger "Danger for older installations" Before restoring your mailcow system on a new server and a clean mailcow-dockerized folder, please check if the value `MAILDIR_SUB` is set in your mailcow.conf. If this value is not set, do not set it in your new mailcow or remove it, otherwise **NO** emails will be displayed. Dovecot loads emails from the mentioned subfolder of the Maildir volume under `$DOCKER_VOLUME_PATH/mailcowdockerized_vmail-vol-1` and if there is any change compared to the original state, no emails will be available there. -To run a restore, **start mailcow**, use the script with "restore" as first parameter. +To run a restore, **start mailcow**, use the script with "--restore" or "-r" with path to backups directory: -``` +```bash # Syntax: -# ./helper-scripts/backup_and_restore.sh restore - -``` - -The script will ask you for a backup location containing the mailcow_DATE folders: - -``` { .bash .no-copy } -Backup location (absolute path, starting with /): /opt/backup +./helper-scripts/backup_and_restore.sh -r /opt/backup -c all ``` All available backups in the specified folder (in our example `/opt/backup`) are then displayed: ``` { .bash .no-copy } Found project name mailcowdockerized +Using /opt/backup as restore location... [ 1 ] - /opt/backup/mailcow-2023-12-11-13-27-14/ [ 2 ] - /opt/backup/mailcow-2023-12-11-14-02-06/ ``` @@ -62,29 +70,34 @@ Now you can enter the number of your backup that you want to restore, in this ex Select a restore point: 2 ``` -The script will now display all the backed up components that you can restore, in our case we have selected `all` for the backup process, so this will now appear here: +The script will now display all the backed up components that the script will restore them. +in our case we have selected `all` for the backup process, so this will now appear here: ``` { .bash .no-copy } -[ 0 ] - all +Matching available components to restore: [ 1 ] - Crypt data [ 2 ] - Rspamd data [ 3 ] - Mail directory (/var/vmail) [ 4 ] - Redis DB [ 5 ] - Postfix data [ 6 ] - SQL DB + + +Restoring will start in 5 seconds. Press Ctrl+C to stop. ``` -Again, we select the component that we want to restore. Option 0 restores **EVERYTHING**. +Now, wait 5 seconds before the above components will be restored! If you want to abort +press `Ctrl+C` to stop the restore process. ??? warning "If you want to restore to a different architecture..." - If you have made the backup on a different architecture, e.g. x86, and now want to restore this backup to ARM64, the backup of Rspamd is displayed as incompatible and cannot be selected individually. When restoring with the 0 key, the restoration of Rspamd is also skipped. + If you have made the backup on a different architecture, e.g. x86, and now want to restore this backup to ARM64, the backup of Rspamd is displayed as incompatible and cannot be selected individually. When restoring all components, the restoration of Rspamd is also skipped. Example of incompatible Rspamd backup in the selection menu: - ``` { .bash .no-copy } + ``` { .bash .no-copy } [...] [ NaN ] - Rspamd data (incompatible Arch, cannot restore it) [...] ``` -Now mailcow will restore the backups you have selected. Please note that the restoration may take some time, depending on the size of the backups. \ No newline at end of file +Now mailcow will restore the backups you have selected. Please note that the restoration may take some time, depending on the size of the backups. diff --git a/mkdocs.yml b/mkdocs.yml index ad10ef5f57..63f9c12689 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,6 +80,7 @@ nav: - 'Component backup & restore': - 'Backup': 'backup_restore/b_n_r-backup.md' - 'Restore': 'backup_restore/b_n_r-restore.md' + - 'Delete' : 'backup_restore/b_n_r-delete.md' - 'Cold-standby (rolling backup)': 'backup_restore/b_n_r-coldstandby.md' - 'Manual backups': - 'Maildir': 'backup_restore/b_n_r-backup_restore-maildir.md' @@ -235,6 +236,7 @@ plugins: 'Component backup & restore' : 'Sicherung und Wiederherstellung von Komponenten' 'Backup': 'Sicherung' 'Restore': 'Wiederherstellung' + 'Delete': 'Löschen' 'Cold-standby (rolling backup)' : 'Cold-standby (rollende Sicherung)' 'Manual backups' : 'Manuelle Sicherung' 'Maildir' : 'Mail-Verzeichnis'