rzerres/dsnap-sync
1
0
Fork 0
Code Issues Pull Requests Releases 1 Activity

dsnap-sync: update documentation for tag 0.5.9

Browse Source 
* README.md
* TODO.md
* Examples.md

Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>
This commit is contained in:
Ralf Zerres
2018-08-25 19:12:03 +02:00
parent 3fa9655950
commit 8b606c90da
4 changed files with 115 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
README.md
View File

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

12
TODO.md
View File

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

62
lang/german/README.md
View File

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

0
usr/share/doc/Examples.md → usr/share/doc/dsnap-sync/Examples.md
View File