From 82b698750ee6a03813a53b7af1c82dc70a22299e Mon Sep 17 00:00:00 2001 From: Ralf Zerres Date: Fri, 21 Sep 2018 14:54:45 +0200 Subject: [PATCH] Markdown: documentation update Signed-off-by: Ralf Zerres --- README.md | 88 +++++++++++++++++++++++-------------------- lang/german/README.md | 87 ++++++++++++++++++++++++------------------ 2 files changed, 97 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index f7f9635..3661bd0 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,8 @@ and combines it with managemnet functionality of `snapper`. `dsnap-sync` creates backups as btrfs-snapshots on a selectable target device. Plug in and mount any btrfs-formatted device to your system. Supported targets -may be either local attached USB drives, as well as automountable remote host -RAIDs. +may be either local attached USB drives, automountable RAID devices or LTFS +aware tapes. All supported targets can be located on a remote host. If possible the backup process will send incremental snapshots to the target drive. If the snapshot will be stored on a remote host, the transport will be secured with ssh. @@ -32,17 +32,19 @@ will offer details as a reference point. ## Backup process The default `dsnap-sync` backup process will iterate through all defined `snapper` -configurations that are found on your source system. If you prefer to have single -processes for each configuration, you are free to define isolated systemd-units or -call `dsnap-sync` interactively while referencing the intended `snapper` configuration -(option `-c` or `--config`). +configurations that are found on your source system. + +If you prefer to have single processes for each configuration or configuration +groups, you are free to define isolated systemd-units. They will be triggerd +interactively or via timer units. `dsnap-sync` will cycle through each +referenced `snapper` configuration (option `-c` or `--config`). For each selected `snapper` configuration `dsnap-sync` * will present/select target device informations * will prepare snapper structures * will perform the actual backup - (handle backupdir, handle snapper structures, handle btrfs send /btrfs recieve) + (handle backupdir, handle snapper structures, handle btrfs send / btrfs recieve) * will finalize the actual backup (update snapper metadata for each source and target snapshot) * will perform cleanup tasks @@ -57,30 +59,31 @@ will need to complete compared to a full backup process. ### Interactive backups -An interactive process will gide you to select a mounted btrfs device. -You can pre-select the target drive via [command line options](./README.md#Options). +An interactive process will gide you to select a backup target. +You can pre-select the target via [command line options](./README.md#Options). To uniquely define / select a target devices you either need to choose * a pair of a btrfs UUID and SUBVOLID * a TARGET name (read 'mount point') +* a MediaPool / Tape VolumeName This will asure, that `dsnap-sync` can distinguish backup processes that have a commen source device, but save data to different target devices. As -an example it might be advisable, to save the project subvolume redundantliy +an example it might be advisable, to save the project subvolume redundantly on to independent targets (disk and tape). Before `dsnap-sync` will perform the backup, it will present the backupdir, -spit out the source and target locations will. You have to confirm or adapt +and spit out the source and target locations. You have to confirm or adapt the given values. You may use commandline options to supress interaction (e.g --noconfirm, --batch). ### Scheduled backups -A scheduled process should be defined as a systemd.unit. Inside the unit +A scheduled process should be defined as a systemd unit. Inside the unit definition the execution parameter will take the `dsnap-sync` call, appending all needed parameters as config options. In combination with a corresponding -systemd.timer unit, you are able to finetune your backup needs. +systemd timer unit, you are able to fine tune your backup needs. The [example section](usr/share/doc/dsnap-sync/Examples.md#systemd) will offer details as a reference point. @@ -96,7 +99,7 @@ Following tools are used: - findmnt - sed - snapper -- ssh +- ssh / scp As an option, you can enrich interactive responses using @@ -113,6 +116,7 @@ Following tools are used: - ltfs - mkltfs - mtx +- perl - sed ## Installation @@ -159,7 +163,8 @@ Please use your host software package manager. Options: -a, --automount start automount for given path to get a valid target mountpoint. -b, --backupdir backupdir is a relative path that will be appended to target backup-root - --use-btrfs-quota use btrfs-quota to calculate snapshot size + --backuptype Specify backup type + --batch no user interaction -d, --description Change the snapper description. Default: "latest incremental backup" --label-finished snapper description tagging successful jobs. Default: "dsnap-sync backup" --label-running snapper description tagging active jobs. Default: "dsnap-sync in progress" @@ -167,25 +172,25 @@ Please use your host software package manager. Default: "dsnap-sync last incremental" --color Enable colored output messages -c, --config Specify the snapper configuration to use. Otherwise will perform for each snapper - configuration. Can list multiple configurations within quotes, space-separated - (e.g. -c "root home"). + configuration. You can select multiple configurations + (e.g. -c "root" -c "home"; --config root --config home) --config-postfix Specify a postfix that will be appended to the destination snapper config name. + --dry-run perform a trial run (no changes are written). + --mediapool Specify the name of the tape MediaPool -n, --noconfirm Do not ask for confirmation for each configuration. Will still prompt for backup - --batch directory name on first backup" --nonotify Disable graphical notification (via dbus) --nopv Disable graphical progress output (disable pv) - -r, --remote
Send the snapshot backup to a remote machine. The snapshot will be sent via ssh. + --noionice Disable setting of I/O class and priority options on target + -r, --remote
Send the snapshot backup to a remote machine. The snapshot will be sent via ssh You should specify the remote machine's hostname or ip address. The 'root' user - must be permitted to login on the remote machine. - -p, --port The remote port. + must be permitted to login on the remote machine + -p, --port The remote port -s, --subvolid Specify the subvolume id of the mounted BTRFS subvolume to back up to. Defaults to 5. - -u, --uuid Specify the UUID of the mounted BTRFS subvolume to back up to. Otherwise will prompt." - If multiple mount points are found with the same UUID, will prompt user." - -t, --target Specify the mountpoint of the BTRFS subvolume to back up to. - --remote
Send the snapshot backup to a remote machine. The snapshot will be sent via ssh. You - should specify the remote machine's hostname or ip address. The 'root' user must be - permitted to login on the remote machine. - --dry-run perform a trial run where no changes are made. + --use-btrfs-quota use btrfs-quota to calculate snapshot size + -u, --uuid Specify the UUID of the mounted BTRFS subvolume to back up to. Otherwise will prompt + If multiple mount points are found with the same UUID, will prompt for user selection + -t, --target Specify the mountpoint of the backup device + --volumename Specify the name of the tape volume -v, --verbose Be verbose on what's going on (min: --verbose=1, max: --verbose=3) --version show program version @@ -218,28 +223,29 @@ backup types are differenciated: Please adapt the defaults, if your milage varies. -* btrfs clone +* btrfs-clone To duplicate an existing `snapper` configuration within a source host, you should use this backup type. It is useful, if a selected `snapper` configuration from the source host will be synced to a target external disk (disk-2-disk-2-disk). - The clone configuration will be managable via `snapper` management - tools as well. Of course the target device needs to offer a btrfs - filesystem to hold the snapshots. + The clone configuration will be managable via `snapper` as expected. + Please be aware, that the target device must be a btrfs filesystem + that can save the snapshots. * btrfs-archive If the target device is not a btrfs filesystem (e.g. ext4, xfs, ltofs tapes), you need to use this backup type. - data are copied backupdir. - `dsnap-sync` will take the data of the source snapshot-ID and copy them - to an ordenary subdirectory. This Base-Directory will be located on the - target-device below the backupdir (target-subdirectory). Inside this - 'target-subdirectory' `dsnap-sync` will mimic the `snapper` structure: + `dsnap-sync` will take the data of the source snapshot-ID and copy the + data as a stream file inside ther target-subdirectory. `dsnap-sync` will + mimic a `snapper` structure inside the 'target-subdirectory': - * the actual btrfs stream will we copied to a subdirectoy called `snapshot` + * create a config specific subdirectory (`archive-`) + * create a snapshot-id subdirectory (``) + * create the btrfs stream file inside the subdirectory + (`_[full | incremental].btrfs`) * the proccess metadata are saved to a file called `info.xml` If you enabled the `ltfs` package, support for backups to tape is possible. @@ -286,9 +292,9 @@ An open-source implementation can be found at ## Contributing -Help is very welcome! Feel free to fork and issue a pull request to add features or -tackle open issues. If you are requesting new features, please have a look at the -TODO list. It might be already on the agenda. +Help is very welcome! Feel free to fork and issue a pull request to add +features or tackle open issues. If you are requesting new features, please +have a look at the TODO list. It might be already on the agenda. ## Related projects diff --git a/lang/german/README.md b/lang/german/README.md index 31f1737..20634bc 100644 --- a/lang/german/README.md +++ b/lang/german/README.md @@ -11,10 +11,11 @@ Funktionalität und kombiniert diese mit den Management-Funktionen von `snapper`. `dsnap-sync` erstellt die Sicherungen als btrfs-Snapshots auf einem Ziel-Gerät. -Hierzu muss das Gerät zunächst mit btrfs formatiert werden. Anschließend wird -es im Betriebssystem bereitgestellt. Das unterstützte Ziel-Medium ist entweder -eine USB Festplatte, oder auch ein automatisch eingelinktes RAID System auf -einem entfernten Host. +Hierzu muss das Gerät zunächst formatiert und anschließend im Betriebssystem +bereitgestellt werden. Das unterstützte Ziel-Medium ist entweder +eine USB Festplatte, ein automatisch eingelinktes RAID System, oder ein LTFS +formatiertes Band. Alle unterstützten Ziel-Geräte können sich auch auf einem +einem entfernten Host befinden. Wenn möglich wird der Sicherungs-Prozess nur die inkrementellen Veränderungen im Snapshot auf das Ziel-Gerät übertragen. Bei Sicherungen auf einem entfernten Host wird die Übertragung mittels ssh gesichert. @@ -28,21 +29,24 @@ verweisen. ## Sicherungs-Prozess -Für einen Sicherungs-Prozess `dsnap-sync` wird in der Standardkonfiguration +Für einen Sicherungs-Prozess wird `dsnap-sync` in der Standardkonfiguration alle definierten `snapper` Konfigurationen des Quell-Systems einbeziehen. -Wenn Sie individuelle Sicherungs-Prozesse je `snapper` Konfiguration -preferieren, können sie eigenständige systemd-units definieren, oder -`dsnap-sync` interaktiv aufrufen und nur auf die gewünschte snapper -Konfiguration referenzieren (Option: `-c` oder `--config`). +Wenn Sie es vorziehen, individuelle Sicherungs-Prozesse je `snapper` Konfiguration +oder Konfigurations-Gruppen einzurichten, sollten sie eigenständige systemd units +definieren. Diese können anschließend interaktiv oder über timer units +aufgerufen werden. +`dsnap-sync` wird alle refenzierten `snapper` Konfigurationen im Sicherungslauf +berücksichtigen (Option: `-c` oder `--config`). Für jede ausgewählte `snapper` Konfiguration wird `dsnap-sync` * die Ziel-Geräte Informationen anzeigen/auswählen +* die snapper Strukturen vorbereiten * die eigentliche Sicherung ausführen (Verarbeitung für backupdir, snapper Strukturen, btrfs send / btrfs recieve) * abschließende Sicherungs-Arbeiten ausführen (Aktualisierung der snapper Metadata für jeden Quell- und Ziel-Snapshot) -* abschließende Aufräumarbeiten +* abschließende Aufräumarbeiten durchführen Üblicherweise beschreiben artverwandte Tools diesen Prozess als Disk to Disk (d2d) Sicherung. Wenn möglich wird `dsnap-sync` die @@ -64,6 +68,7 @@ müssen sie entweder * ein Paar aus btrfs UUID und SUBVOLID * ein Target (hier: 'mount point') +* ein MediaPool / Band-Name auswählen. Damit ist `dsnap-sync` in der Lage Sicherungsprozesse zu unterscheiden, die als Quelle den gleichen Snapshot haben, jedoch @@ -103,7 +108,7 @@ Folgende Tools werden verwendet: - findmnt - sed - snapper -- ssh +- ssh / scp Optional können interaktive Rückmeldungen mit foldenen Tools ergänzt werden: @@ -122,6 +127,7 @@ Folgende Tools werden verwendet: - ltfs - mkltfs - mtx +- perl - sed ## Installation @@ -171,7 +177,8 @@ Software Paket Manager. Options: -a, --automount start automount for given path to get a valid target mountpoint. -b, --backupdir backupdir is a relative path that will be appended to target backup-root - --use-btrfs-quota use btrfs-quota to calculate snapshot size + --backuptype Specify backup type + --batch no user interaction -d, --description Change the snapper description. Default: "latest incremental backup" --label-finished snapper description tagging successful jobs. Default: "dsnap-sync backup" --label-running snapper description tagging active jobs. Default: "dsnap-sync in progress" @@ -179,25 +186,25 @@ Software Paket Manager. Default: "dsnap-sync last incremental" --color Enable colored output messages -c, --config Specify the snapper configuration to use. Otherwise will perform for each snapper - configuration. Can list multiple configurations within quotes, space-separated - (e.g. -c "root home"). + configuration. You can select multiple configurations + (e.g. -c "root" -c "home"; --config root --config home) --config-postfix Specify a postfix that will be appended to the destination snapper config name. + --dry-run perform a trial run (no changes are written). + --mediapool Specify the name of the tape MediaPool -n, --noconfirm Do not ask for confirmation for each configuration. Will still prompt for backup - --batch directory name on first backup" --nonotify Disable graphical notification (via dbus) --nopv Disable graphical progress output (disable pv) - -r, --remote
Send the snapshot backup to a remote machine. The snapshot will be sent via ssh. + --noionice Disable setting of I/O class and priority options on target + -r, --remote
Send the snapshot backup to a remote machine. The snapshot will be sent via ssh You should specify the remote machine's hostname or ip address. The 'root' user - must be permitted to login on the remote machine. - -p, --port The remote port. + must be permitted to login on the remote machine + -p, --port The remote port -s, --subvolid Specify the subvolume id of the mounted BTRFS subvolume to back up to. Defaults to 5. - -u, --uuid Specify the UUID of the mounted BTRFS subvolume to back up to. Otherwise will prompt." - If multiple mount points are found with the same UUID, will prompt user." - -t, --target Specify the mountpoint of the BTRFS subvolume to back up to. - --remote
Send the snapshot backup to a remote machine. The snapshot will be sent via ssh. You - should specify the remote machine's hostname or ip address. The 'root' user must be - permitted to login on the remote machine. - --dry-run perform a trial run where no changes are made. + --use-btrfs-quota use btrfs-quota to calculate snapshot size + -u, --uuid Specify the UUID of the mounted BTRFS subvolume to back up to. Otherwise will prompt + If multiple mount points are found with the same UUID, will prompt for user selection + -t, --target Specify the mountpoint of the backup device + --volumename Specify the name of the tape volume -v, --verbose Be verbose on what's going on (min: --verbose=1, max: --verbose=3) --version show program version @@ -246,15 +253,18 @@ sorgen. Folgende Sicherungstypen werden unterschieden: * btrfs-archive Stellt das Ziel-Gerät kein btrfs Dateisystem bereit (e.g. ext4, xfs, - ltofs tapes), kann der Sicherungstpy btrfs-archive angewendet werden. + ltofs tapes), kann der Sicherungstyp btrfs-archive angewendet werden. `dsnap-sync` wird anhand der Quell Snapshot-ID die Daten in ein gewöhnliches Unterverzeichnis kopieren. Dieses Stamm-Verzeichnis befindet sich unterhalb des Backup-Verzeichnisses auf dem Ziel-Gerät (target-subdirectory). Unterhalb des 'target-subdirectory' erstellt - `dsnap-sync` in Analogie zur `snapper` Struktur: + `dsnap-sync` in Analogie zur `snapper` Datenablabe folgende Struktur: - * der aktuelle btrfs Stream wird im Unterverzeichnis `snapshot` abgelegt + * ein Unterverzeichnis des Konfigurations-Namens (`archive-`) + * ein Unterverzeichnis der Snapshot-ID (``) + * der aktuelle btrfs Stream wird im Unterverzeichnis abgelegt + (`_[full | incremental].btrfs`) * die Metadaten des Prozesses werden in der Datei `info.xml` abgelegt Steht `ltfs` zur Verfügung, ist ein Backup auf Bänder möglich. @@ -311,8 +321,9 @@ der für Festplatten üblichen Funktionsweise implementiert. Ab Geräten der LTO5 Generation sind Sie in der Lage, Bänder für die LTFS-Nutzung vorzubareiten (formatieren, bzw. partitionieren). Anschließend können erfolgreich formatierte Bänder in das Dateisystem -eingehängt werden (FUSE). Das Beschreiben und Auslesen der Daten erfolgt dann -mit den gewohnten Betriebssystem Tools. Eine Open-Source Implementierung finden Sie z.B. unter +eingehängt werden (FUSE). Das Beschreiben und Auslesen der Daten erfolgt +dann mit den gewohnten Betriebssystem Tools. Eine Open-Source Implementierung +finden Sie z.B. unter [LinearTapeFileSystem](https://github.com/LinearTapeFileSystem/ltfs). ## Mitarbeit @@ -324,14 +335,16 @@ Vielleicht findet Ihr dort auch Anregungen. ## Ähnliche Projekte -`dsnap-sync` basiert auf dem ursprünglichen Code von Wes Barnetts. Als open-source war -meine Intention, die Erweiterungen in das Projekt zurückfliessen zu lassen. -Neben der Tatsache, dass diese Version bashisms eleminiert hat, sieht Wes sich leider -zeitlich ausser Stande, den neuen Code in angemessener Art und Weise zu prüfen um ihn -anschließende in `snap-sync` einzubinden. Jeder ist willkommen dies zu tun. +`dsnap-sync` basiert auf dem ursprünglichen Code von Wes Barnetts. Als +open-source war meine Intention, die Erweiterungen in das Projekt +zurückfliessen zu lassen. Neben der Tatsache, dass diese Version bashisms +eleminiert hat, sieht Wes sich leider zeitlich ausser Stande, den neuen +Code in angemessener Art und Weise zu prüfen um ihn anschließende in +`snap-sync` einzubinden. Jeder ist willkommen dies zu tun. -Bis dahin habe ich mich entschlossen, die Ergebnisse als Fork unter dem Namen `dsnap-sync` -zu veröffentlichen. Die Namensämderung soll mögliche Verwechslungen vermeinden. +Bis dahin habe ich mich entschlossen, die Ergebnisse als Fork unter dem +Namen `dsnap-sync` zu veröffentlichen. Die Namensämderung soll mögliche +Verwechslungen vermeinden. ## Lizenz