Markdown: introduce language specific versions

* new subdir lang to hold the language specific code
* introduce german README.md
This commit is contained in:
2018-07-16 11:59:55 +02:00
parent 9628a9a623
commit d3b6c972c5
2 changed files with 361 additions and 36 deletions

100
README.md
View File

@@ -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
drive. If the snapshot will be stored on a remote host, the transport will be
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.
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
configurations that are found on your source system. If you prefer to have single
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
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
the given values. You may use commandline options to supress interaction
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
(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.
Aside the new filesystem path, `dsnap-sync` will use a snapper template
(`/etc/snapper/config-templates/dsnap-sync`) to create a new snapper target configuration.
To garantee unique configuration names, `dsnap-sync` take the source 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:
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
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
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:
btrfs-archive. If the target device is not a btrfs filesystem (e.g. ext4,
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:
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:
* 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
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
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
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`).

297
lang/german/README.md Normal file
View File

@@ -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