Markdown: introduce language specific versions

* new subdir lang to hold the language specific code
* introduce german README.md

README.md

@@ -3,18 +3,24 @@
 
 # dsnap-sync
 
+<p align="center">
+  <span>English</span> |
+  <!-- a href="lang/spanish#dsnap-sync">Spanish</a> | -->
+  <a href="lang/german#dsnap-sync">Deutsch</a>
+</p>
+
 ## About
 
 `dsnap-sync` is designed to backup btrfs formated filesystems.
 It takes advantage of the specific snapshots functionality btrfs offers
-and combines it with managemnet functionality of snapper.
+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.
-If possible the backup process will send incremental snapshots to the target 
+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 
+drive. If the snapshot will be stored on a remote host, the transport will be
 secured with ssh.
 
 The tool is implemented as a posix shell script (dash), to keep the footprint
@@ -25,13 +31,13 @@ will offer details as a reference point.
 
 ## Backup process
 
-The default `dsnap-sync` backup process will iterate through all defined snapper
+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 
+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
+call `dsnap-sync` interactively while referencing the intended `snapper` configuration
 (option `-c` or `--config`).
 
-For each selected snapper configuration `dsnap-sync`
+For each selected `snapper` configuration `dsnap-sync`
 
 * will present/select target device informations
 * will prepare snapper structures
@@ -64,8 +70,8 @@ an example it might be advisable, to save the project subvolume redundantliy
 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 
+spit out the source and target locations will. You have to confirm or adapt
-the given values. You may use commandline options to supress interaction 
+the given values. You may use commandline options to supress interaction
 (e.g --noconfirm, --batch).
 
 
@@ -73,7 +79,7 @@ the given values. You may use commandline options to supress interaction
 
 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 
+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)
 will offer details as a reference point.
@@ -104,7 +110,7 @@ To simplify correct target locations, this project uses a Makefile.
     # make install
 
 If your system uses a non-default location for the snapper
-configuration defaults, specify the location with an environment variable 
+configuration defaults, specify the location with an environment variable
 (`SNAPPER_CONFIG`).
 
     Arch Linux/Fedora/Gentoo:
@@ -113,7 +119,7 @@ configuration defaults, specify the location with an environment variable
     Debian/Ubuntu:
     # make SNAPPER_CONFIG=/etc/default/snapper install
 
-The local snapper configuration will be extended to make use
+The local `snapper` configuration will be extended to make use
 of a new template 'dsnap-sync'.
 
 ### Using distribution packages
@@ -134,7 +140,7 @@ Please use your host software package manager.
 ## Options
 
     Usage: dsnap-sync [options]
-      
+
       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
@@ -170,49 +176,71 @@ Please use your host software package manager.
 ## 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. 
+will take care to create the necessary target filesystem-structure. Following 
+backup types are differenciated:
 
 * btrfs-snapshots
 
-  On the target device the needed snapper structure is validated and build up as needed.
+  This is the default backup type. `dsnap-sync` will use this type to sync
-  Aside the new filesystem path, `dsnap-sync` will use a snapper template 
+  a btrfs-snapshot of an existing `snapper` configuration from a source 
-  (`/etc/snapper/config-templates/dsnap-sync`) to create a new snapper target configuration.
+  device to a target device. On the target device the needed `snapper` 
-  To garantee unique configuration names, `dsnap-sync` take the source configuration name 
+  structure will be build up as needed. Aside the new target filesystem 
-  and postfix it with targets hostname. You can adopt this behaviour with a config option
+  path, `dsnap-sync` will create a new target `snapper` configuration. It
-  (`--config-postfix`).
+  will incorporate the template (`/etc/snapper/config-templates/dsnap-sync`).
- 
+  To garantee unique configuration names, `dsnap-sync` take the source
-  The default `config-template` of dsnap-sync will inherit following snapper parameters:
+  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 
+  `snapper` parameters:
+
   * mark new snapshots as type 'single'
   * mark new snaphosts with cleanup-algorithm 'timeline'
   * apply config option 'CONFIG_TYPE=child'
   * apply config option 'TIMELINE_CREATE=no'
   * apply config option 'TIMELINE_CLEANUP=yes'
-  
+
   Please adapt the defaults, if your milage varies.
-  
+
+* 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.
+
 * btrfs-archive
 
-  Beside btrfs-snapshots, `dsnap-shot` will support another backup type:
+  If the target device is not a btrfs filesystem (e.g. ext4,
-  btrfs-archive. If the target device is not a btrfs filesystem (e.g. ext4,
+  xfs, ltofs tapes), you need to use this backup type.
-  xfs, ltofs tapes), data are copied backupdir.
-  `dsnap-sync` will take the source snapshot-ID and create a corresponding directory 
-  below targets backupdir. Inside this 'target-subdirectory' `dsnap-sync` will mimic the
-  snapper structure: 
   
+  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:
+
   * 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.
 Since storage space on disks are very price efficient this days, environments
-often use removable, external disks as additional backup targets. If the 
+often use removable, external disks as additional backup targets. If the
-external disks aren't mounted at boot time they can't be addressed by the 
+external disks aren't mounted at boot time they can't be addressed by the
-selection function. It's even advisable to not mount them all the time 
+selection function. It's even advisable to not mount them all the time
 (e.g prevent risks for malware encryption attacks).
 
-To link external disks in dynamically, but also asure a persistent naming 
+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`).

lang/german/README.md

@@ -0,0 +1,297 @@
+<!-- dsnap-sync README.md -->
+<!-- version: 0.5.7 -->
+
+# dsnap-sync
+
+## Über
+
+`dsnap-sync` ist konzipiert, um Backups für btrfs formatierte Dateisysteme
+durchzuführen. Es bedient sich der von btrfs bereitgestellten Snapshot
+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.
+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.
+
+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)
+verweisen.
+
+## Sicherungs-Prozess
+
+Für einen Sicherungs-Prozess `dsnap-sync` wird 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`).
+
+Für jede ausgewählte `snapper` Konfiguration wird `dsnap-sync`
+
+* die Ziel-Geräte Informationen anzeigen/auswählen
+* 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
+
+Üblicherweise beschreiben artverwandte Tools diesen Prozess als
+Disk to Disk (d2d) Sicherung. Wenn möglich wird `dsnap-sync` die
+`btrfs send / btrfs recieve` Funktionen nutzen, um nur Veränderungen des
+Snapshots zur übertragen. Dabei vergleicht es Snapshot-Daten des Quell
+Systems mit Snapshot-Daten des Ziel Systems. Existiert eine gemeinsame
+Snapshot-ID auf beiden Systemen, wird `dsnap-sync` die
+`btrfs send / btrfs receive` Pipe vorbereiten und die Daten transferieren.
+Im Vergleich zu einer klassischen Voll-Sicherung verkürzt dies die
+benötigte Übertragungszeit erheblich.
+
+### Interaktive Sicherungen
+
+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.
+Um eine eindeutige Zuordung eines Ziel-Gerätes sicherzustellen,
+müssen sie entweder
+
+* ein Paar aus btrfs UUID und SUBVOLID
+* ein Target (hier: 'mount point')
+
+auswählen. Damit ist `dsnap-sync` in der Lage Sicherungsprozesse zu
+unterscheiden, die als Quelle den gleichen Snapshot haben, jedoch
+auf unterschiedliche Ziele gesichert werden sollen. Als Beispiel sei
+angeführt, dass Projektdaten redundant auf voneinander unabhängige
+Ziel-Medien (Festplatten, Bänder) gesichert werden müssen.
+
+Bevor `dsnap-sync` das eigentliche Backup durchführt, wird es Ihnen
+die Möglichkeit anbieten, einen Backup-Pfad (backudir) auszuwählen.
+Darüber hinaus werden Quell und Ziel Informationen ausgewiesen.
+Sie können die Aufforderung zur Bestätigung der Parameter über
+Kommandozeilen-Parameter unterdrücken (z.B --noconfirm, --batch).
+
+### Zeitgesteuerte Sicherungen
+
+Eine zeitliche Steuerung von Sicherungs-Prozessen sollte über
+systemd-units definiert werden. Innerhalb der systemd.service
+Definition wird in der [Service] Sektion der ExecStart Parameter
+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.
+
+## Anforderungen
+
+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.
+Folgende Tools werden verwendet:
+
+- awk
+- btrfs
+- findmnt
+- sed
+- snapper
+
+Optional können interaktive Rückmeldungen mit foldenen Tools ergänzt
+werden:
+
+- notify-send
+- pv
+
+## Installation
+
+### Aus den Quellen
+
+`dsnap-sync` ist ein Shell Script. Daher ist keine Kompilierung
+erforderlich. Über ein Makefile wird die Installation an den
+richtigen Ziel-Pfad gesteuert.
+
+    # make install
+
+Sollte Ihr System einen unüblichen Speicherort für die snapper
+Konfigurationen verwenden, kann der Pfad in einer Umgebungs-Variable
+für die Installation einbezogen werden (`SNAPPER_CONFIG`).
+
+    Arch Linux/Fedora/Gentoo:
+    # make SNAPPER_CONFIG=/etc/conf.d/snapper install
+
+    Debian/Ubuntu:
+    # make SNAPPER_CONFIG=/etc/default/snapper install
+
+Die lokalen `snapper` Konfiguration werden um ein neues Template
+'dsnap-sync' ergänzt.
+
+### Verwendung eines Distributions-Pakets
+
+Wenn verfügbar können sie `dsnap-sync` als vorkonfiguriertes Paket
+installieren. Bitte verwenden sie hierzu den Betriebssystem eigenen
+Software Paket Manager.
+
+<!--
+* For ARCH-Linux
+[AUR package](https://aur.archlinux.org/packages/dsnap-sync)
+-->
+
+<!-- For Debian
+[deb package](https://packages.debian.org/dsnap-sync). -->
+
+<!-- For Ubuntu
+[deb package](https://packages.ubuntu.org/dsnap-sync). -->
+
+## Optionen
+
+    Usage: dsnap-sync [options]
+
+      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
+      -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"
+          --label-synced <desc>   snapper description tagging last synced jobs.
+                                  Default: "dsnap-sync last incremental"
+          --color                 Enable colored output messages
+      -c, --config <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").
+          --config-postfix <name> Specify a postfix that will be appended to the destination snapper config name.
+      -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 <address>      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 <port>           The remote port.
+      -s, --subvolid <subvlid>    Specify the subvolume id of the mounted BTRFS subvolume to back up to. Defaults to 5.
+      -u, --uuid <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 <target>       Specify the mountpoint of the BTRFS subvolume to back up to.
+          --remote <address>      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.
+      -v, --verbose               Be more verbose on what's going on.
+          --version		          show program version
+
+## Erster Sicherungslauf
+
+Haben Sie bisher noch niemals auf ein Ziel-Gerät gesichert (first run), wird
+`dsnap-sync` für die Erstellung der notwendigen Ziel Dateisystem-Strukturen
+sorgen. Folgende Sicherungstypen werden unterschieden:
+
+* btrfs-snapshots
+
+  Dieser Sicherungstyp ist der Systemstandard. Bei einem btrfs-snapshot
+  wird `dsnap-sync` verwendet, um bestehende `snapper` Konfigurationen
+  der Quelle auf ein Ziel-Gerät zu synchronisieren.
+  Auf dem Ziel-Gerät wird eine `snapper` Struktur falls erforderlich
+  neu erstellt. Dies beinhaltet die Erstellung von Ziel-Dateisystem Pfaden,
+  als auch die Erstellung der snapper Konfiguraktion unter Verwendung eines
+  Templates (`/etc/snapper/config-templates/dsnap-sync`).
+  Um eindeutige Namen bei der Nutzung von Konfiguration sicherzustellen,
+  wird `dsnap-sync` den Host-Namen des Quell-Systems an den Konfigurationsname
+  auf dem Ziel-System anhängen. Sie können dieses Verhalten durch eine
+  Konfigurations-Option anpassen (`--config-postfix`).
+
+  Folgende Parameter werden vom Template `dsnap-sync` an die aktive
+  Konfiguration vererbt:
+
+  * Neue Snapshots als Type 'single' markieren
+  * Neue Snapshots mit dem Clean-Algorithmus 'timeline' markieren
+  * die Konfigurationsoption 'CONFIG-TYPE=child' setzen
+  * die Konfigurationsoption 'TIMELINE_CREATE=no' setzen
+  * die Konfigurationsoption 'TIMELINE_CLEANUP=yes' setzen
+
+  Bitte passen sie diese Einstellungen auf Ihre Bedürfnisse an.
+
+* btrfs-clone
+
+  Dieser Sicherungstyp ermöglicht die Duplizierung einer bereits
+  existierenden `snapper` Konfiguration innerhalb eines Quell-Systems.
+  Sinnvoll ist dies Funktionalität, wenn die auf dem Quell-System
+  die gewählte `snapper` Konfiguration auf externe Festplatten archiviert
+  werden sollen (disk-2-disk-2-disk). Auch diese Clone-Konfiguration
+  kann anschließend über die `snapper` Management-Tools verwaltet
+  werden. Das Ziel-Gerät muss daher zwingend ein btrfs Dateisystem
+  bereitstellen.
+
+* btrfs-archive
+
+  Stellt das Ziel-Gerät kein btrfs Dateisystem bereit (e.g. ext4, xfs,
+  ltofs tapes), kann der Sicherungstpy 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:
+
+  * der aktuelle btrfs Stream wird im Unterverzeichnis `snapshot` abgelegt
+  * die Metadaten des Prozesses werden in der Datei `info.xml` abgelegt
+
+  Steht `ltfs` zur Verfügung, ist ein Backup auf Bänder möglich.
+  Hierbei wird ein Band durch ltfs vorbereitet und kann anschließend in
+  das Dateisystem unter einem definierten Pfad eingebunden werden
+  ('mount-point'). Eine `dsnap-sync` Sicherung auf diesen Pfad erfolgt 
+  über den Sicherungstyp `btrfs-archive`.
+
+## Automounter
+
+`dsnap-sync` stellt alle verwendbaren btrfs Dateisysteme als Prozess-
+Ziele bereit. Da Festplatten mit großen Speicher-Kapazitäten heutzutage
+sehr preiswert angeboten werden, sind externe Festplatten als zusätzliche
+Sicherungsziele üblich. Werden dies externen Festplatten aber nicht
+während des Boot-Prozesses oder über dynamische Regeln eingebunden,
+können sie von `dsnap-sync` nicht in der Auswahl-Funktion angeboten senden.
+Es ist darüber hinaus durchaus sinnvoll, solche Festplatten nicht permanent
+einzubinden (z.B. um die Risiken eines Malware-Angriffs zu minimieren, der
+erreichbare Pfade verschlüsselt.)
+
+Um externe Festplatten dynamisch mit einer persistenten Namens Syntax
+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)
+des Beispiel Dokuments enthält weitere Details.
+
+## Mitarbeit
+
+Hilfe ist sehr willkommen! Gerne könnt Ihr das Projekt forken und PR's einreichen,
+um neue Funktion zu implementieren oder Fehler zu bereinigen.
+Wenn Ihr an neuen Funktionen arbeiten wollt, schaut bitte auch in das TODO Dokument.
+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.
+
+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
+
+<!-- License source -->
+[Logo-CC_BY]: https://i.creativecommons.org/l/by/4.0/88x31.png "Creative Common Logo"
+[License-CC_BY]: https://creativecommons.org/licenses/by/4.0/legalcode "Creative Common License"
+
+Diese Arbeit ist unter der [Creative Common License 4.0][License-CC_BY] lizensiert.
+
+![Creative Common Logo][Logo-CC_BY]
+
+© 2016, 2017  James W. Barnett;
+© 2017 - 2018 Ralf Zerres