Merge pull request #809 from i-doit/updating-backup-and-restore

docs: Update article and note

docs/de/wartung-und-betrieb/daten-sichern-und-wiederherstellen/index.md

@@ -4,80 +4,102 @@ Da sich in der [IT-Dokumentation](../../glossar.md#Glossar-IT-Dokumentation) wic
 
 Hierbei müssen drei Bereiche abgedeckt werden: die [Datenbanken](#backup-und-recovery-der-datenbanken), die [Dateien](#backup-und-recovery-der-dateien) von _i-doit_ und die [Systemkonfiguration](#backup-und-recovery-der-systemkonfiguration).
 
-Backup und Recovery der Datenbanken
------------------------------------
+!!! note "Sollte i-doit aus einem kompletten Backup wiederhergestellt werden müssen, dann nutzen Sie bitte die [Migrations Artikel](../../upgrades-und-umzuege/umzug-einer-installation-unter-linux.md)"
 
-Hierzu kann das Kommandozeilen-Tool mysqldump verwendet werden. Ein einfaches Beispiel zum Sichern aller Daten:
+## Backup und Recovery der Datenbanken
 
-    mysqldump -hlocalhost -uroot -p --all-databases > backup.sql
+Hierzu kann das Kommandozeilen-Tool `mysqldump` verwendet werden. Ein einfaches Beispiel zum Sichern aller Daten:
+
+```sh
+mysqldump -hlocalhost -uroot -p --all-databases > backup.sql
+```
 
 Das entsprechende Recovery:
 
-    mysql -hlocalhost -uroot -p < backup.sql
+```sh
+mysql -hlocalhost -uroot -p < backup.sql
+```
 
-Während eines Backups sollte _i-doit_ nicht verwendet werden, um die Backups nicht zu korrumpieren. Für die Zeit des Backups bzw. des Recoverys kann der Webserver deaktiviert werden. Auf Debian-basierten Linux-Distributionen führt man
+Während eines Backups sollte _i-doit_ nicht verwendet werden, um die Backups nicht zu korrumpieren. Für die Zeit des Backups bzw. des Wiederherstellens kann der Webserver deaktiviert werden. Auf Debian-basierten Linux-Distributionen führt man
 
-    sudo service apache2 stop
+```sh
+sudo service apache2 stop
+```
 
 aus. Nach dem Backup/Recovery kann mit
 
-    sudo service apache2 start
+```sh
+sudo service apache2 start
+```
 
 der Webserver wieder aktiviert werden. Sind [Cronjobs](../../automatisierung-und-integration/cli/index.md) für _i-doit_ eingerichtet, sollten diese ebenfalls während der Sicherung deaktiviert und nach Abschluss wieder aktiviert werden.
 
 !!! success "Komprimieren"
 
     Viel Speicherplatz kann man sparen, indem die SQL-Dumps komprimiert werden. Die obigen Befehle könnten demnach so aussehen
 
-        # Backup:
-        mysqldump -hlocalhost -uroot -p --all-databases | gzip -9 > backup.sql.gz
+    # Backup:
+    ```sh
+    mysqldump -hlocalhost -uroot -p --all-databases | gzip -9 > backup.sql.gz
+    ```
 
-        # Recovery:
-        gunzip < backup.sql.gz | mysql -hlocalhost -uroot -p
+    # Recovery:
+    ```sh
+    gunzip < backup.sql.gz | mysql -hlocalhost -uroot -p
+    ```
 
-!!! attention "Foreign Key Contraints"
+!!! attention "Foreign Key Constraints"
 
-    Beim Wiederherstellen von Datenbank-Inhalten kann es vorkommen, dass MySQL/MariaDB mit einer Fehlermeldung abbricht, etwa: errno: 150 "Foreign key constraint is incorrectly formed"
+    Beim Wiederherstellen von Datenbank-Inhalten kann es vorkommen, dass MySQL/MariaDB mit einer Fehlermeldung abbricht, etwa: `errno: 150 "Foreign key constraint is incorrectly formed"`
 
-    Dies liegt daran, dass die Daten und Strukturen nacheinander, d. h., Tabelle für Tabelle wiederhergestellt werden. Zwischenzeitlich existieren demnach alte neben neuen (wiederhergestellten) Daten. Das Datenbank-Modell von i-doit enthält sehr viele Verknüpfungen von Tabellen untereinander, für die Foreign Keys Contraints verwendet werden. Diese Referenzierung von beispielsweise einem Datensatz A in Tabelle 1 auf Datensatz B in Tabelle 2 unterliegt bestimmten Automatismen, wenn A oder B aktualisiert oder gar gelöscht werden. Die Reihenfolge spielt dabei eine wichtige Rolle, wann A und wann B wiederhergestellt werden. Alte und neue Referenzen können allerdings dieselben Indizes verwenden, auch wenn sie unterschiedliche Referenzierungen ausdrücken. Dadurch kann es zu oben genannten Fehlern kommen.
+    Dies liegt daran, dass die Daten und Strukturen nacheinander, d. h., Tabelle für Tabelle wiederhergestellt werden. Zwischenzeitlich existieren demnach alte neben neuen (wiederhergestellten) Daten. Das Datenbank-Modell von i-doit enthält sehr viele Verknüpfungen von Tabellen untereinander, für die Foreign Keys Constraints verwendet werden. Diese Referenzierung von beispielsweise einem Datensatz A in Tabelle 1 auf Datensatz B in Tabelle 2 unterliegt bestimmten Automatismen, wenn A oder B aktualisiert oder gar gelöscht werden. Die Reihenfolge spielt dabei eine wichtige Rolle, wann A und wann B wiederhergestellt werden. Alte und neue Referenzen können allerdings dieselben Indizes verwenden, auch wenn sie unterschiedliche Referenzierungen ausdrücken. Dadurch kann es zu oben genannten Fehlern kommen.
 
     Als Workaround bietet es sich an, die Datenbanken vor der Wiederherstellung explizit zu löschen:
 
-        -- Standard-Name der System-Datenbank:
-        DROP DATABASE idoit_system;
+    -- Standard-Name der System-Datenbank:
+    ```sql
+    DROP DATABASE idoit_system;
+    ```
 
-        -- Standard-Name der ersten Mandanten-Datenbank:
-        DROP DATABASE idoit_data;
+    -- Standard-Name der ersten Mandanten-Datenbank:
+    ```sql
+    DROP DATABASE idoit_data;
+    ```
 
-Backup und Recovery der Dateien
--------------------------------
+## Backup und Recovery der Dateien
 
 Es empfiehlt sich, das gesamte Verzeichnis von _i-doit_ zu sichern und bei Bedarf wiederherzustellen. Mittels
 
-    tar -czvf i-doit.tar.gz /pfad/zu/i-doit
+```sh
+tar -czvf i-doit.tar.gz /pfad/zu/i-doit
+```
 
 kann ein komprimiertes Tar-Archiv erstellt werden.
 
 Das entsprechende Recovery:
 
-    tar -xzv i-doit.tar.gz
+```sh
+tar -xzv i-doit.tar.gz
+```
 
-Backup und Recovery der Systemkonfiguration
--------------------------------------------
+## Backup und Recovery der Systemkonfiguration
 
 Wichtig für den unmittelbaren Betrieb von _i-doit_ ist es, die Konfigurations-Dateien vom Apache Webserver, von PHP und von MySQL/MariaDB zu sichern und bei Bedarf wiederherzustellen. Bestenfalls hast du bereits bei der [Installation](../../installation/index.md) von _i-doit_ die entsprechenden Anpassungen an den Konfigurationsdateien dokumentiert und sicher hinterlegt.
 
-Backup mittels VM-Snapshots
----------------------------
+## Backup mittels VM-Snapshots
 
 Häufig wird _i-doit_ auf einer virtuellen Maschine (VM) installiert. Für ein Backup und Recovery reicht es allerdings nicht aus, schlicht Snapshots der VMs im laufenden Betrieb zu erstellen. Das Problem liegt in der Konsistenz der Datenbanken: Die Daten liegen eventuell im Arbeitsspeicher und befinden sich (noch) nicht im nichtflüchtigen Speicher. Sie werden demnach durch die Sicherung oftmals nicht erfasst und gingen im Fall des Falles verloren.
 
-Soll auf Snapshosts dennoch nicht verzichtet werden, muss vorher das DBMS MySQL/MariaDB gestoppt werden. Auf Debian-basierten Linux-Betriebssystemen erledigt dies der Befehl:
+Soll auf Snapshots dennoch nicht verzichtet werden, muss vorher das DBMS MySQL/MariaDB gestoppt werden. Auf Debian-basierten Linux-Betriebssystemen erledigt dies der Befehl:
 
-    sudo service mysql stop
+```sh
+sudo service mysql stop
+```
 
 Nach dem Snapshot wird das DBMS wieder gestartet:
 
-    sudo service mysql start
+```sh
+sudo service mysql start
+```
 
 Sicherlich hinreichend bekannt, aber dennoch wichtig zu erwähnen: **Backups sollten niemals auf dem System verbleiben, das gesichert wird.**

docs/en/maintenance-and-operation/backup-and-recovery/index.md

@@ -4,80 +4,106 @@ Since the [IT-documentation](../../glossary.md) contains important data required
 
 In this context, the following three areas need to be covered: [databases](index.md), [files](index.md) of i-doit and the [system configuration](index.md).
 
-Backup and Recovery of Databases
---------------------------------
+!!! note "If you need to restore i-doit from a complete backup, please use the [Migration article](../../upgrades-and-migrations/migration-of-an-installation-under-linux.md)"
 
-For this purpose, you can use the command line tool mysqldump. A simple example for securing all data:
+## Backup and Recovery of Databases
 
-    mysqldump -hlocalhost -uroot -p --all-databases > backup.sql
+For this purpose, you can use the command line tool `mysqldump`. A simple example for securing all data:
+
+```sh
+mysqldump -hlocalhost -uroot -p --all-databases > backup.sql
+```
 
 The corresponding recovery is this:
 
-    mysql -hlocalhost -uroot -p < backup.sql
+```sh
+mysql -hlocalhost -uroot -p < backup.sql
+```
 
 You should not use i-doit during the backup process in order not to corrupt the backup. The Webserver can be deactivated for the time of the backup/recovery. On Debian-based Linux distributions the command
 
-    sudo service apache2 stop
+```sh
+sudo service apache2 stop
+```
 
-is executed. When the backup/recovery is finished, the command  
+is executed. When the backup/recovery is finished, the command
 
-    sudo service apache2 start
+```sh
+sudo service apache2 start
+```
 
 can be used to reactivate the Webserver. If applicable, you should also deactivate [Cronjobs](../../automation-and-integration/cli/index.md), which are set up in i-doit, during the data securing process and reactivate them afterwards.
 
 !!! success "Compressing"
 
     A lot of disk space can be saved by compressing the SQL-dumps. For example, the commands mentioned above could look as follows:
 
-        # Backup:
-        mysqldump -hlocalhost -uroot -p --all-databases | gzip -9 > backup.sql.gz
+    # Backup:
+
+    ```sh
+    mysqldump -hlocalhost -uroot -p --all-databases | gzip -9 > backup.sql.gz
+    ```
+
+    # Recovery:
 
-        # Recovery:
-        gunzip < backup.sql.gz | mysql -hlocalhost -uroot -p
+    ```sh
+    gunzip < backup.sql.gz | mysql -hlocalhost -uroot -p
+    ```
 
 !!! attention "Foreign Key Constraints"
 
-    When restoring database contents, it may happen that MySQL/MariaDB aborts the process and shows an error message, as for example: errno: 150 "Foreign key constraint is incorrectly formed"
+    When restoring database contents, it may happen that MySQL/MariaDB aborts the process and shows an error message, as for example: `errno: 150 "Foreign key constraint is incorrectly formed"`
 
-    This is caused by the fact that data and structures are restored one after another (meaning table after table). In the meantime, old data exists additionally beside new (restored) data. The database model of i-doit contains many links of tables between each other for which Foreign Key Constraints are used. This reference of, for example, a dataset A in table 1 to a dataset B in table 2, underlies specific automatisms when A or B is updated or even deleted. The order is important to determine when A is restored and when B is restored. Old and new references can however use the same indexes even if they express different references. This may lead to the errors mentioned above.
+    This is caused by the fact that data and structures are restored one after another (meaning table after table). In the meantime, old data exists additionally beside new (restored) data. The database model of i-doit contains many links of tables between each other for which Foreign Key Constraints are used. This reference of, for example, a dataset A in table 1 to a dataset B in table 2, underlies specific automatism when A or B is updated or even deleted. The order is important to determine when A is restored and when B is restored. Old and new references can however use the same indexes even if they express different references. This may lead to the errors mentioned above.
 
     Deleting the databases explicitly before restoring is a suitable workaround for this:
 
-        -- Default name of the system database:
-        DROP DATABASE idoit_system;
+    -- Default name of the system database:
+
+    ```sql
+    DROP DATABASE idoit_system;
+    ```
+
+    -- Default name of the first client database:
 
-        -- Default name of the first client database:
-        DROP DATABASE idoit_data;
+    ```sh
+    DROP DATABASE idoit_data;
+    ```
 
-Backup and Recovery of Files
-----------------------------
+## Backup and Recovery of Files
 
 We recommend securing the complete i-doit folder and - if needed - restoring the complete folder. By using
 
-    tar -czvf i-doit.tar.gz /pfad/zu/i-doit
+```sh
+tar -czvf i-doit.tar.gz /path/to/i-doit
+```
 
 you can create a compressed tar-archive.
 
 The corresponding recovery is this:
 
-    tar -xzv i-doit.tar.gz
+```sh
+tar -xzv i-doit.tar.gz
+```
 
-Backup and Recovery of the System Configuration
------------------------------------------------
+## Backup and Recovery of the System Configuration
 
 It is important for the immediate operation of i-doit to secure the configuration files of the Apache Webserver, PHP and MySQL/MariaDB and restore them, if needed. In the best case, you already documented the corresponding changes of the configuration files and stored them safely during the [installation](../../installation/index.md) process of i-doit.
 
-Backup via VM-Snapshots
------------------------
+## Backup via VM-Snapshots
 
 i-doit is often installed on a virtual machine (VM). However, for backup and recovery purposes it does not suffice to simply make snapshots of the VM during operation. The problem is the consistency of the databases: The data may be stored in the working memory but is not (yet) located in the non-volatile memory. Therefore it may be the case that data is not covered by the backup and thus lost if the backup is needed.
 
 If you still do not want to do without snapshots, the DBMS MySQL/MariaDB needs to be stopped beforehand. On Debian-based operating systems this is carried out via the following command:
 
-    sudo service mysql stop
+```sh
+sudo service mysql stop
+```
 
 When the snapshot was taken, the DBMS is restarted:
 
-    sudo service mysql start
+```sh
+sudo service mysql start
+```
 
 It is surely well understood but still important to mention: **Backups should never stay on the system that is being secured.**