From 8b606c90dace659f8df53cb5aab7d2c84bf54a23 Mon Sep 17 00:00:00 2001 From: Ralf Zerres Date: Sat, 25 Aug 2018 19:12:03 +0200 Subject: [PATCH] dsnap-sync: update documentation for tag 0.5.9 * README.md * TODO.md * Examples.md Signed-off-by: Ralf Zerres --- README.md | 67 +++++++++++++++++----- TODO.md | 12 ++-- lang/german/README.md | 62 ++++++++++++++++++-- usr/share/doc/{ => dsnap-sync}/Examples.md | 0 4 files changed, 115 insertions(+), 26 deletions(-) rename usr/share/doc/{ => dsnap-sync}/Examples.md (100%) diff --git a/README.md b/README.md index 5afcb6f..f7f9635 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - + # dsnap-sync @@ -26,7 +26,7 @@ secured with ssh. The tool is implemented as a posix shell script (dash), to keep the footprint small. `dsnap-sync` will support interactive and time scheduled backup processes. Scheduling should be implemented as a pair of systemd service and timer-units. -The [example section](usr/share/doc/Examples.md#systemd) +The [example section](usr/share/doc/dsnap-sync/Examples.md#systemd) will offer details as a reference point. ## Backup process @@ -81,10 +81,12 @@ 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. -The [example section](usr/share/doc/Examples.md#systemd) +The [example section](usr/share/doc/dsnap-sync/Examples.md#systemd) will offer details as a reference point. ## Requirements + +### dsnap-sync Beside the posix shell itself (e.g. `dash`), `dsnap-sync`relies on external tools to achieve its goal. At run-time their availability is checked. Following tools are used: @@ -94,12 +96,25 @@ Following tools are used: - findmnt - sed - snapper +- ssh As an option, you can enrich interactive responses using - notify-send - pv +### tape-admin + +Beside the posix shell itself (e.g. `dash`), `dsnap-sync`relies on external +tools to achieve its goal. At run-time their availability is checked. +Following tools are used: + +- jq +- ltfs +- mkltfs +- mtx +- sed + ## Installation ### Building from source @@ -144,6 +159,7 @@ 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 -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" @@ -170,28 +186,28 @@ Please use your host software package manager. 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. - -v, --verbose Be more verbose on what's going on. + -v, --verbose Be verbose on what's going on (min: --verbose=1, max: --verbose=3) --version show program version ## First run If you have never synced to the paticular target device (first run), `dsnap-sync` -will take care to create the necessary target filesystem-structure. Following +will take care to create the necessary target filesystem-structure. Following backup types are differenciated: * btrfs-snapshots This is the default backup type. `dsnap-sync` will use this type to sync - a btrfs-snapshot of an existing `snapper` configuration from a source - device to a target device. On the target device the needed `snapper` - structure will be build up as needed. Aside the new target filesystem + a btrfs-snapshot of an existing `snapper` configuration from a source + device to a target device. On the target device the needed `snapper` + structure will be build up as needed. Aside the new target filesystem path, `dsnap-sync` will create a new target `snapper` configuration. It will incorporate the template (`/etc/snapper/config-templates/dsnap-sync`). To garantee unique configuration names, `dsnap-sync` take the source - configuration name and postfix it with targets hostname. You can adopt + configuration name and postfix it with targets hostname. You can adopt this behaviour with a config option (`--config-postfix`). - The default `config-template` of dsnap-sync will inherit following + The default `config-template` of dsnap-sync will inherit following `snapper` parameters: * mark new snapshots as type 'single' @@ -216,21 +232,21 @@ backup types are differenciated: 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-device below the backupdir (target-subdirectory). Inside this 'target-subdirectory' `dsnap-sync` will mimic the `snapper` structure: * the actual btrfs stream will we copied to a subdirectoy called `snapshot` * the proccess metadata are saved to a file called `info.xml` - + If you enabled the `ltfs` package, support for backups to tape is possible. ltfs will prepare a tape, than can be mounted afterwards to a selectable mount-point. A `dsnap-sync` backup to this path will be handeld as type `btrfs-archive`. - + ## Automounter `dsnap-sync` offer all mounted btrfs filesystems as valid process targets. @@ -244,9 +260,30 @@ To link in external disks dynamically, but also asure a persistent naming syntax, we can use them as auto-mountable targets. To wakeup the automount proccess before parsing available target disks, append the target mount-point as a config option to `dsnap-sync` (e.g: `--automount /var/backups/archive-disk1`). -The [example section](usr/share/doc/Examples.md#Automounter) +The [example section](usr/share/doc/dsnap-sync/Examples.md#Automounter) will offer details as a reference point. +## Tape-Administration / LTFS + +If you use `dsnap-sync` to archive snapshots on a tape, consider to use it +in combination with LTFS. (Work in Progress: Initial support is tested +with LTO7-Tapes in a Quantum SuperLoader3). + +The installation package will include a wrapper script `tape-admin`, which +implements all common tasks that are needed for tape administration. +If you are able to make use of a tape-changer (e.g Quantum SuperLoader3) the +wrapper will take advantage of the `mtx` package to handle barcodes and slot +management. If you create your own barcodes, please consult the documentation +of your Loader-Device. Most likely they do support "Code 39"-Type labels. + +`LTFS` is an attempt to offer read and write-access functionality to serial +tapes in a way that's common with hard drives. From LTO5 onwards, your are +able to format/partition the tape with LTFS-Tools. After the successfull +preparation the LTFS-Tape can be mounted to a selectable mountpoint (via +FUSE). Read and write access can be managed using common OS tools. +An open-source implementation can be found at +[LinearTapeFileSystem](https://github.com/LinearTapeFileSystem/ltfs). + ## Contributing Help is very welcome! Feel free to fork and issue a pull request to add features or diff --git a/TODO.md b/TODO.md index 9498505..918d808 100644 --- a/TODO.md +++ b/TODO.md @@ -10,12 +10,9 @@ # btrfs send -p /my/snapshot-YYYY-MM-DD /my/incremental-snapshot-YYYY-MM-DD | ssh user@host 'cat >/backup/home/incremental-snapshot-YYYY-MM-DD.btrfs' - dsnap-sync: introduce snapper config handling for parent/child types disk2disk -> parent to child on btrfs (default: snapshot) - disk2disk2disk -> child to child on btrfs(clone snapshot) - disk2disk2tape -> child to tape on non-btrfs (send btrfs-stream of snapshot if incremental, copy snapshot if first/full) + disk2disk2disk -> child to child on btrfs (clone snapshot) + disk2disk2tape -> child to tape on non-btrfs (send btrfs-stream of snapshot if incremental, copy snapshot if first/full) - dsnap-sync: parallel tasks per config -- dsnap-sync: introduce snapper function: important snapshots - Important snapshots have important=yes in the userdata - let snapper cleanup/timeline mechanisms respect this ## finished tasks ## @@ -28,3 +25,8 @@ - dsnap-sync: port as posix compatible - dsnap-sync: introduce selectable subvolid option - dsnap-sync: use snapper to administer target synced snapshots +- dsnap-sync: introduce snapper function: important snapshots + Important snapshots have important=yes in the userdata + let snapper cleanup/timeline mechanisms respect this +- tape-admin: handle common tasks for tape-changer administration +- tape-admin: handle common tasks for ltfs tape administration diff --git a/lang/german/README.md b/lang/german/README.md index 9fa8f84..31f1737 100644 --- a/lang/german/README.md +++ b/lang/german/README.md @@ -1,5 +1,5 @@ - + # dsnap-sync @@ -23,7 +23,7 @@ Mit Blick auf Portabilität und Ressourcen-Schonung wurde `dsnap-sync`als Posix Shell Script implementiert (dash). Es unterstützt sowohl interaktive als auch zeitgesteuerte Sicherungs-Prozesse. Zeitgesteuerte Sicherungen sollten als systemd Einheiten (service- und timer-units) implementiert werden. -Für Details wird auf den [Beispiel-Abschnitt](usr/share/doc/Examples.md#systemd) +Für Details wird auf den [Beispiel-Abschnitt](../../usr/share/doc/dsnap-sync/Examples.md#systemd) verweisen. ## Sicherungs-Prozess @@ -58,7 +58,7 @@ benötigte Übertragungszeit erheblich. Ein interkativer Sicherungsprozess wird Ihnen die Auswahl eines Ziel-Gerätes anbieten. Sie können dieses Ziel-Gerät mit -[Kommando-Zeilen Parametern](./README.md#Options) vorauswählen. +[Kommando-Zeilen Parametern](./README.md#Optionen) vorauswählen. Um eine eindeutige Zuordung eines Ziel-Gerätes sicherzustellen, müssen sie entweder @@ -86,10 +86,13 @@ als `dsnap-sync` Aufruf mit allen gewünschten Optionen eingestellt. In Verbindung mit einer zugehörigen systemd.timer Definition sind sie in der Lage, unterschiedliche Ausführungszeiten mit selektierten Optionen umzusetzen. Für Details wird auf den -[Beispiel-Abschnitt](usr/share/doc/Examples.md#systemd) verweisen. +[Beispiel-Abschnitt](../../usr/share/doc/dsnap-sync/Examples.md#systemd) +verweisen. ## Anforderungen +### dsnap-sync + Neben der eigentlichen Posix Shell (e.g. `dash`), bedient sich `dsnap-sync` externer Tools, um die gewünschte Funktionalität bereitzustellen. Deren Verfügbarkeit wird zur Laufzeit überprüft. @@ -100,6 +103,7 @@ Folgende Tools werden verwendet: - findmnt - sed - snapper +- ssh Optional können interaktive Rückmeldungen mit foldenen Tools ergänzt werden: @@ -107,6 +111,19 @@ werden: - notify-send - pv +### tape-admin + +Neben der eigentlichen Posix Shell (e.g. `dash`), bedient sich +`tape-admin` externer Tools, um die gewünschte Funktionalität +bereitzustellen. Deren Verfügbarkeit wird zur Laufzeit überprüft. +Folgende Tools werden verwendet: + +- jq +- ltfs +- mkltfs +- mtx +- sed + ## Installation ### Aus den Quellen @@ -154,6 +171,7 @@ 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 -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" @@ -180,7 +198,7 @@ Software Paket Manager. 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. - -v, --verbose Be more verbose on what's going on. + -v, --verbose Be verbose on what's going on (min: --verbose=1, max: --verbose=3) --version show program version ## Erster Sicherungslauf @@ -262,9 +280,41 @@ einzubinden, können sie als 'automountbare Geräte' definiert werden. Aktiviert wird der Automount-Prozess vor der Ziel-Auswahl zu aktivieren, kannn der 'Mount-Point' als Option beim `dsnap-sync` Aufruf übergeben werden (z.B: `--automount /var/backups/archive-disk1`). -Der [Abschnitt Automount](usr/share/doc/Examples.md#Automounter) +Der [Abschnitt Automount](../../usr/share/doc/dsnap-sync/Examples.md#Automounter) des Beispiel Dokuments enthält weitere Details. +## Tape-Administration / LTFS + +Wenn sie `dsnap-sync` für die Archivierung von Snapshots auf Bänder +verwenden, sollten den Einsatz in Kombination mit LTFS überdenken. +(WIP - work in progress: Die erster erfolgreicher Versuch wurde mit +LTO7-Bändern in einem Quantum SuperLoader3 getestet). + +Das Installations-Paket beinhaltet ein Hilfs-Skript `tape-admin`, das +alle Basisaufgaben für die Administration von Bändern als Funktionen +bereitstellt. Hardware, die einen mechanischen Bandwechsel ermöglicht +(z.B Quantum SuperLoader3), kann das Hilfs-Skript über das Paket `mtx` +steuern. Dies beinhaltet das Auslesen von Barcodes als auch das Laden +und Entladen von Bändern in wählbare Quell- und Ziel-Schächte (Slots). + +(WIP: Die Zuordnung von Band-Namen zu Pools und Slots neben deren +Media-Zugriffsrichtlienen wird in einer JSON-Datei beschrieben. +Diese muss derzeit noch manuell gepflegt werden: +`/etc/dsnap-sync/MediaPools.json`). + +Werden Barcode-Labels selbst erstellt, prüfen Sie bitte Hinweise auf das +zu verwendende Format. Üblicherweise unterstützen die Barcode-Leser +"Code 39" Etiketten. + +`LTFS` ist ein Ansatz, der Lese- und Schreib-Operationen auf Bänder in +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 +[LinearTapeFileSystem](https://github.com/LinearTapeFileSystem/ltfs). + ## Mitarbeit Hilfe ist sehr willkommen! Gerne könnt Ihr das Projekt forken und PR's einreichen, diff --git a/usr/share/doc/Examples.md b/usr/share/doc/dsnap-sync/Examples.md similarity index 100% rename from usr/share/doc/Examples.md rename to usr/share/doc/dsnap-sync/Examples.md