dsnap-sync: update documentation for tag 0.5.9

* README.md
* TODO.md
* Examples.md

Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>

README.md

@@ -1,5 +1,5 @@
 <!-- dsnap-sync README.md -->
-<!-- version: 0.5.7 -->
+<!-- version: 0.5.9 -->
 
 # 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 <path>      start automount for given path to get a valid target mountpoint.
       -b, --backupdir <prefix>    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 <desc>    Change the snapper description. Default: "latest incremental backup"
           --label-finished <desc> snapper description tagging successful jobs. Default: "dsnap-sync backup"
           --label-running <desc>  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 
+  a btrfs-snapshot of an existing `snapper` configuration from a source
-  device to a target device. On the target device the needed `snapper` 
+  device to a target device. On the target device the needed `snapper`
-  structure will be build up as needed. Aside the new target filesystem 
+  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

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)
+  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) 
+  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

lang/german/README.md

@@ -1,5 +1,5 @@
 <!-- dsnap-sync README.md -->
-<!-- version: 0.5.7 -->
+<!-- version: 0.5.9 -->
 
 # 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 <path>      start automount for given path to get a valid target mountpoint.
       -b, --backupdir <prefix>    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 <desc>    Change the snapper description. Default: "latest incremental backup"
           --label-finished <desc> snapper description tagging successful jobs. Default: "dsnap-sync backup"
           --label-running <desc>  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,