From 27e150878c17f8a6a08428d03f4eb479327a363a Mon Sep 17 00:00:00 2001 From: Axel Burri Date: Mon, 25 May 2015 17:13:36 +0200 Subject: [PATCH] documentation: small corrections (thanks Richard!) --- README.md | 31 ++++++++++++++++--------------- doc/btrbk.1 | 8 ++++---- doc/btrbk.conf.5 | 24 ++++++++++++------------ 3 files changed, 32 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 3bc709d..234e49c 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,11 @@ btrbk is a backup tool for btrfs subvolumes, taking advantage of btrfs specific capabilities to create atomic snapshots and transfer them incrementally to your backup locations. -The source and target locations are specified in a config file. This -allows simple setups on a single machine with locally attached backup -disks, as well as handling more complex scenarios on a server -receiving backups from several hosts via ssh. +The source and target locations are specified in a config file, which +allows to easily configure simple scenarios like "laptop with locally +attached backup disks", as well as more complex ones, e.g. "server +receiving backups from several hosts via ssh, with different retention +policy". Key Features: @@ -165,7 +166,7 @@ attached, simply add the following line to the config: Example: host-initiated backup on fileserver -------------------------------------------- -Lets say you have a fileserver at "myserver.mydomain.com" where you +Let's say you have a fileserver at "myserver.mydomain.com" where you want to create backups of your laptop disk, the config would look like this: @@ -214,7 +215,7 @@ This will pull backups from alpha/beta.mydomain.com and locally create: Example: local time-machine (daily snapshots) --------------------------------------------- -If all you want is creating snapshots of your home directory on a +If all you want is to create snapshots of your home directory on a regular basis: /etc/btrbk/btrbk.conf: @@ -256,19 +257,19 @@ to only fetch the snapshots. target send-receive /mnt/btr_backup/my-laptop.com If the server runs btrbk with this config, the latest snapshot (which -is *always* transferred) as well as 10 weeklies and all monthlies are -received from 192.168.0.42. The source filesystem is never altered -because of `snapshot_preserve_daily all`. +is *always* transferred), 10 weeklies and all monthlies are received +from 192.168.0.42. The source filesystem is never altered because of +`snapshot_preserve_daily all`. Setting up SSH ============== Since btrbk needs root access on the remote side, it is *very -advisable* to take all security precautions you can. Usually backups -are generated periodically without user interaction, so it is not -possible to protect your ssh key with a password. The steps below -shall give you hints on how to secure your ssh server for a backup +advisable* to take all the security precautions you can. Usually +backups are generated periodically without user interaction, so it is +not possible to protect your ssh key with a password. The steps below +will give you hints on how to secure your ssh server for a backup scenario. btrbk provides a little shell script called "ssh_filter_btrbk.sh", @@ -320,7 +321,7 @@ Now restore the snapshot: btrfs subvolume snapshot /mnt/btr_pool/_btrbk_snap/data.20150101 /mnt/btr_pool/data -That's it, your `data` subvolume is restored. If everything went fine, +That's it; your `data` subvolume is restored. If everything went fine, it's time to nuke the broken subvolume: btrfs subvolume delete /mnt/btr_pool/data.BROKEN @@ -373,7 +374,7 @@ How to Contribute Your contributions are welcome! -If you would like to contribute or found bugs: +If you would like to contribute or have found bugs: - Visit the [btrbk project page on GitHub] and use the [issues tracker] there. diff --git a/doc/btrbk.1 b/doc/btrbk.1 index 0320527..64f3eb4 100644 --- a/doc/btrbk.1 +++ b/doc/btrbk.1 @@ -1,4 +1,4 @@ -.TH "btrbk" "1" "2015-05-21" "btrbk v0.18.0" "" +.TH "btrbk" "1" "2015-05-25" "btrbk v0.18.0" "" .SH NAME btrbk \- backup tool for btrfs volumes .SH SYNOPSIS @@ -63,12 +63,12 @@ Then, for each specified target, btrbk creates the backups as follows: If the \fIresume_missing\fR option is set (the default), btrbk transfers all missing snapshots needed to satisfy the configured \fItarget_preserve_{daily,weekly,monthly}\fR retention policy, always -incremental from the latest common parent subvolume found. If no +incrementally from the latest common parent subvolume found. If no common parent subvolume is found, a full backup is created for the first transfer. Note that the latest snapshot (the one created in the first step) is always transferred, regardless of the retention policy. .PP -In a last step, unless the -p (preserve backups) option is set, +As a last step, unless the -p (preserve backups) option is set, snapshots and backup subvolumes that are not preserved by their configured retention policy will be deleted. Note that the latest snapshot as well as the latest backup is always preserved, regardless @@ -119,7 +119,7 @@ are described in .PD .SH EXIT STATUS .sp -\fBbtrbk\fR returns a zero exit status if it succeeds. Non zero is +\fBbtrbk\fR returns a zero exit status if it succeeds. Non-zero is returned in case of failure. .SH AVAILABILITY Please refer to the btrbk project page diff --git a/doc/btrbk.conf.5 b/doc/btrbk.conf.5 index d5f1ba4..fcf8dd6 100644 --- a/doc/btrbk.conf.5 +++ b/doc/btrbk.conf.5 @@ -1,4 +1,4 @@ -.TH "btrbk.conf" "5" "2015-05-21" "btrbk v0.18.0" "" +.TH "btrbk.conf" "5" "2015-05-25" "btrbk v0.18.0" "" .SH NAME btrbk.conf \- btrbk configuration file .SH SYNOPSIS @@ -9,8 +9,8 @@ btrbk.conf \- btrbk configuration file The btrbk configuration file specifies which btrfs subvolumes on the filesystem are to be processed, what target subvolumes should be used to create the backups, and where the snapshots should be -generated. The retention policy as well as other options can be -defined for each backup. +generated. The retention policy, as well as most other options can be +defined either globally or within a section. .PP The options specified always apply to the last section encountered, superseding the values set in upper-level sections. This means that @@ -20,12 +20,12 @@ The sections are: .TP \fBvolume\fR | Directory of a btrfs volume containing the source subvolume(s) to be -backuped. \fI\fR must be an absolute path and point +backed up. \fI\fR must be an absolute path and point to a btrfs volume (or subvolume). Usually the mount point of a btrfs filesystem mounted with the \fIsubvolid=0\fR option. .TP \fBsubvolume\fR -Subvolume to be backuped, relative to the \fI\fR +Subvolume to be backed up, relative to the \fI\fR specified in the \fIvolume\fR section. .TP \fBtarget\fR | @@ -51,10 +51,9 @@ Directory in which the btrfs snapshots are created, relative to does not autmatically create this directory, and the snapshot creation will fail if it is not present. .TP -\fBsnapshot_name\fR -Base name of the created snapshot (and backup). Defaults to -\fI\fR. This option is only valid in the \fItarget\fR -section. +\fBsnapshot_name\fR Base name of the created snapshot (and +backup). This option is only valid in the \fItarget\fR +section. Defaults to \fI\fR. .TP \fBsnapshot_create\fR always|ondemand|no If set to \[lq]ondemand\[rq], the snapshots are only created if the @@ -67,8 +66,9 @@ with the \fIresume_missing\fR option if another instance of btrbk is taking care of snapshot creation). Defaults to \[lq]always\[rq]. .TP \fBincremental\fR yes|no|strict -Perform incremental backups. Defaults to \[lq]yes\[rq]. If set to -\[lq]strict\[rq], non-incremental (initial) backups are never created. +If set, incremental backups are created. If set to \[lq]strict\[rq], +non-incremental (initial) backups are never created. Defaults to +\[lq]yes\[rq]. .TP \fBresume_missing\fR yes|no If set, the backups in the target directory are compared to the source @@ -95,7 +95,7 @@ monthly backup. Defaults to \[lq]all\[rq]. \fBsnapshot_preserve_weekly\fR .TP \fBsnapshot_preserve_monthly\fR -Define retention policy for the snapshots, with same semantics as the +Defines retention policy for the snapshots, with same semantics as the \fItarget_preserve_*\fR options. .PD .TP