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

Markdown: documentation update

Browse Source 
Signed-off-by: Ralf Zerres <ralf.zerres@networkx.de>
This commit is contained in:
Ralf Zerres
2018-09-21 14:54:45 +02:00
parent f52ff68318
commit 82b698750e
2 changed files with 97 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
README.md
View File

@@ -17,8 +17,8 @@ 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.
may be either local attached USB drives, automountable RAID devices or LTFS
aware tapes. All supported targets can be located on a remote host.
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.
@@ -32,17 +32,19 @@ 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
processes for each configuration, you are free to define isolated systemd-units or
call `dsnap-sync` interactively while referencing the intended `snapper` configuration
(option `-c` or `--config`).
configurations that are found on your source system.
If you prefer to have single processes for each configuration or configuration
groups, you are free to define isolated systemd-units. They will be triggerd
interactively or via timer units. `dsnap-sync` will cycle through each
referenced `snapper` configuration (option `-c` or `--config`).
For each selected `snapper` configuration `dsnap-sync`
* will present/select target device informations
* will prepare snapper structures
* will perform the actual backup
(handle backupdir, handle snapper structures, handle btrfs send /btrfs recieve)
(handle backupdir, handle snapper structures, handle btrfs send / btrfs recieve)
* will finalize the actual backup
(update snapper metadata for each source and target snapshot)
* will perform cleanup tasks
@@ -57,30 +59,31 @@ will need to complete compared to a full backup process.
### Interactive backups
An interactive process will gide you to select a mounted btrfs device.
You can pre-select the target drive via [command line options](./README.md#Options).
An interactive process will gide you to select a backup target.
You can pre-select the target via [command line options](./README.md#Options).
To uniquely define / select a target devices you either need to choose
* a pair of a btrfs UUID and SUBVOLID
* a TARGET name (read 'mount point')
* a MediaPool / Tape VolumeName
This will asure, that `dsnap-sync` can distinguish backup processes that
have a commen source device, but save data to different target devices. As
an example it might be advisable, to save the project subvolume redundantliy
an example it might be advisable, to save the project subvolume redundantly
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
and spit out the source and target locations. You have to confirm or adapt
the given values. You may use commandline options to supress interaction
(e.g --noconfirm, --batch).
### Scheduled backups
A scheduled process should be defined as a systemd.unit. Inside the unit
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.
systemd timer unit, you are able to fine tune your backup needs.
The [example section](usr/share/doc/dsnap-sync/Examples.md#systemd)
will offer details as a reference point.
@@ -96,7 +99,7 @@ Following tools are used:
- findmnt
- sed
- snapper
- ssh
- ssh / scp
As an option, you can enrich interactive responses using
@@ -113,6 +116,7 @@ Following tools are used:
- ltfs
- mkltfs
- mtx
- perl
- sed
## Installation
@@ -159,7 +163,8 @@ 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
--backuptype <type> Specify backup type <archive | child | parent>
--batch no user interaction
-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"
@@ -167,25 +172,25 @@ Please use your host software package manager.
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").
configuration. You can select multiple configurations
(e.g. -c "root" -c "home"; --config root --config home)
--config-postfix <name> Specify a postfix that will be appended to the destination snapper config name.
--dry-run perform a trial run (no changes are written).
--mediapool Specify the name of the tape MediaPool
-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.
--noionice Disable setting of I/O class and priority options on target
-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.
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.
--use-btrfs-quota use btrfs-quota to calculate snapshot size
-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 for user selection
-t, --target <target> Specify the mountpoint of the backup device
--volumename Specify the name of the tape volume
-v, --verbose Be verbose on what's going on (min: --verbose=1, max: --verbose=3)
--version show program version
@@ -218,28 +223,29 @@ backup types are differenciated:
Please adapt the defaults, if your milage varies.
* btrfs clone
* 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.
The clone configuration will be managable via `snapper` as expected.
Please be aware, that the target device must be a btrfs filesystem
that can save the snapshots.
* btrfs-archive
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:
`dsnap-sync` will take the data of the source snapshot-ID and copy the
data as a stream file inside ther target-subdirectory. `dsnap-sync` will
mimic a `snapper` structure inside the 'target-subdirectory':
* the actual btrfs stream will we copied to a subdirectoy called `snapshot`
* create a config specific subdirectory (`archive-<config-name>`)
* create a snapshot-id subdirectory (`<snapper-id>`)
* create the btrfs stream file inside the subdirectory
(`<snapper-id>_[full | incremental].btrfs`)
* the proccess metadata are saved to a file called `info.xml`
If you enabled the `ltfs` package, support for backups to tape is possible.
@@ -286,9 +292,9 @@ An open-source implementation can be found at
## Contributing
Help is very welcome! Feel free to fork and issue a pull request to add features or
tackle open issues. If you are requesting new features, please have a look at the
TODO list. It might be already on the agenda.
Help is very welcome! Feel free to fork and issue a pull request to add
features or tackle open issues. If you are requesting new features, please
have a look at the TODO list. It might be already on the agenda.
## Related projects

87
lang/german/README.md
View File

@@ -11,10 +11,11 @@ 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.
Hierzu muss das Gerät zunächst formatiert und anschließend im Betriebssystem
bereitgestellt werden. Das unterstützte Ziel-Medium ist entweder
eine USB Festplatte, ein automatisch eingelinktes RAID System, oder ein LTFS
formatiertes Band. Alle unterstützten Ziel-Geräte können sich auch auf einem
einem entfernten Host befinden.
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.
@@ -28,21 +29,24 @@ verweisen.
## Sicherungs-Prozess
Für einen Sicherungs-Prozess `dsnap-sync` wird in der Standardkonfiguration
Für einen Sicherungs-Prozess wird `dsnap-sync` 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`).
Wenn Sie es vorziehen, individuelle Sicherungs-Prozesse je `snapper` Konfiguration
oder Konfigurations-Gruppen einzurichten, sollten sie eigenständige systemd units
definieren. Diese können anschließend interaktiv oder über timer units
aufgerufen werden.
`dsnap-sync` wird alle refenzierten `snapper` Konfigurationen im Sicherungslauf
berücksichtigen (Option: `-c` oder `--config`).
Für jede ausgewählte `snapper` Konfiguration wird `dsnap-sync`
* die Ziel-Geräte Informationen anzeigen/auswählen
* die snapper Strukturen vorbereiten
* 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
* abschließende Aufräumarbeiten durchführen
Üblicherweise beschreiben artverwandte Tools diesen Prozess als
Disk to Disk (d2d) Sicherung. Wenn möglich wird `dsnap-sync` die
@@ -64,6 +68,7 @@ müssen sie entweder
* ein Paar aus btrfs UUID und SUBVOLID
* ein Target (hier: 'mount point')
* ein MediaPool / Band-Name
auswählen. Damit ist `dsnap-sync` in der Lage Sicherungsprozesse zu
unterscheiden, die als Quelle den gleichen Snapshot haben, jedoch
@@ -103,7 +108,7 @@ Folgende Tools werden verwendet:
- findmnt
- sed
- snapper
- ssh
- ssh / scp
Optional können interaktive Rückmeldungen mit foldenen Tools ergänzt
werden:
@@ -122,6 +127,7 @@ Folgende Tools werden verwendet:
- ltfs
- mkltfs
- mtx
- perl
- sed
## Installation
@@ -171,7 +177,8 @@ 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
--backuptype <type> Specify backup type <archive | child | parent>
--batch no user interaction
-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"
@@ -179,25 +186,25 @@ Software Paket Manager.
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").
configuration. You can select multiple configurations
(e.g. -c "root" -c "home"; --config root --config home)
--config-postfix <name> Specify a postfix that will be appended to the destination snapper config name.
--dry-run perform a trial run (no changes are written).
--mediapool Specify the name of the tape MediaPool
-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.
--noionice Disable setting of I/O class and priority options on target
-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.
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.
--use-btrfs-quota use btrfs-quota to calculate snapshot size
-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 for user selection
-t, --target <target> Specify the mountpoint of the backup device
--volumename Specify the name of the tape volume
-v, --verbose Be verbose on what's going on (min: --verbose=1, max: --verbose=3)
--version show program version
@@ -246,15 +253,18 @@ sorgen. Folgende Sicherungstypen werden unterschieden:
* btrfs-archive
Stellt das Ziel-Gerät kein btrfs Dateisystem bereit (e.g. ext4, xfs,
ltofs tapes), kann der Sicherungstpy btrfs-archive angewendet werden.
ltofs tapes), kann der Sicherungstyp 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:
`dsnap-sync` in Analogie zur `snapper` Datenablabe folgende Struktur:
* der aktuelle btrfs Stream wird im Unterverzeichnis `snapshot` abgelegt
* ein Unterverzeichnis des Konfigurations-Namens (`archive-<config-name>`)
* ein Unterverzeichnis der Snapshot-ID (`<snapper-id>`)
* der aktuelle btrfs Stream wird im Unterverzeichnis abgelegt
(`<snapper-id>_[full | incremental].btrfs`)
* die Metadaten des Prozesses werden in der Datei `info.xml` abgelegt
Steht `ltfs` zur Verfügung, ist ein Backup auf Bänder möglich.
@@ -311,8 +321,9 @@ 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
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
@@ -324,14 +335,16 @@ 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.
`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.
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