diff --git a/README.md b/README.md index fd17a82..ff6435a 100644 --- a/README.md +++ b/README.md @@ -78,10 +78,10 @@ btrbk is in AUR: https://aur.archlinux.org/packages/btrbk/ Synopsis ======== -Please consult the [btrbk(1) man-page] provided with this package for a +Please consult the [btrbk(1)] man-page provided with this package for a full description of the command line options. - [btrbk(1) man-page]: http://www.digint.ch/btrbk/doc/btrbk.html + [btrbk(1)]: http://www.digint.ch/btrbk/doc/btrbk.html Configuration File @@ -90,7 +90,7 @@ Configuration File Before running `btrbk`, you will need to create a configuration file. You might want to take a look at `btrbk.conf.example` provided with this package. For a detailed description, please consult the -[btrbk.conf(5) man-page]. +[btrbk.conf(5)] man-page. When playing around with config-files, it is highly recommended to check the output using the `dryrun` command before executing the @@ -102,7 +102,7 @@ This will read all btrfs information on the source/target filesystems and show what actions would be performed (without writing anything to the disks). - [btrbk.conf(5) man-page]: http://www.digint.ch/btrbk/doc/btrbk.conf.html + [btrbk.conf(5)]: http://www.digint.ch/btrbk/doc/btrbk.conf.html Example: laptop with usb-disk for backups @@ -262,6 +262,35 @@ from 192.168.0.42. The source filesystem is never altered because of `snapshot_preserve_daily all`. +Example: encrypted backup to non-btrfs target +--------------------------------------------- + +If your backup server does not support btrfs, you can send your +subvolumes to a raw file. + +Note: this is an _experimental_ feature! + +/etc/btrbk/btrbk.conf: + + raw_target_compress xz + raw_target_encrypt gpg + gpg_keyring /etc/btrbk/gpg/pubring.gpg + gpg_recipient btrbk@mydomain.com + + volume /mnt/btr_pool + subvolume home + target raw ssh://myserver.mydomain.com/backup + ssh_user btrbk + incremental no + +This will create a GnuPG encrypted, compressed file +`/backup/home.YYYYMMDD.btrfs_.xz.gpg` on the target +host. + +While incremental backups are also supported for raw targets, this is +not recommended (see [btrbk.conf(5)] for details). + + Setting up SSH ============== diff --git a/doc/btrbk.1 b/doc/btrbk.1 index 77d15d4..aa2dc37 100644 --- a/doc/btrbk.1 +++ b/doc/btrbk.1 @@ -1,4 +1,4 @@ -.TH "btrbk" "1" "2015-09-02" "btrbk v0.20.0" "" +.TH "btrbk" "1" "2015-09-29" "btrbk v0.21.0-dev" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -21,12 +21,17 @@ from one source to multiple destinations. Snapshots as well as backup subvolume names are created in form: .PP .RS 4 -.YYYYMMDD[_N] +.[_N] .RE .PP -Where YYYY is the year, MM is the month, and DD is the day of -creation, and, if multiple backups are created on the same day, N will -be incremented on each backup, starting at 1. +Where is identical to the source subvolume name, +unless the configuration option \fIsnapshot_name\fR is set. The + is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the +\fItimestamp_format\fR configuration option), where "YYYY" is the +year, "MM" is the month, "DD" is the day, "hh" is the hour and "mm" is +the minute of the creation time (local time of the host running +btrbk). If multiple snapshots/backups are created on the same +date/time, N will be incremented on each backup, starting at 1. .SH OPTIONS .PP \-h, \-\-help diff --git a/doc/btrbk.conf.5 b/doc/btrbk.conf.5 index f3a8b48..11f96a7 100644 --- a/doc/btrbk.conf.5 +++ b/doc/btrbk.conf.5 @@ -1,4 +1,4 @@ -.TH "btrbk.conf" "5" "2015-09-02" "btrbk v0.20.0" "" +.TH "btrbk.conf" "5" "2015-09-29" "btrbk v0.21.0-dev" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -19,8 +19,7 @@ defined either globally or within a section. The options specified always apply to the last section encountered, superseding the values set in upper-level sections. This means that global options must be set before any sections are defined. -.PP -The sections are: +.SH SECTIONS .PP \fBvolume\fR | .RS 4 @@ -33,17 +32,19 @@ filesystem mounted with the \fIsubvolid=0\fR option. \fBsubvolume\fR .RS 4 Subvolume to be backed up, relative to the \fI\fR -specified in the \fIvolume\fR section. +specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR +sections are allowed within \fIvolume\fR sections. .RE .PP -\fBtarget\fR | +\fBtarget\fR | .RS 4 Target type and directory where the backup subvolumes are to be -created. \fI\fR must be an absolute path and point -to a btrfs volume (or subvolume). Currently the the only valid -\fI\fR is \[lq]send\-receive\[rq]. +created. See the TARGET TYPES section for supported +\fI\fR. Multiple \fItarget\fR sections are allowed within +\fIsubvolume\fR sections. +.RE .PP -For the \fIvolume\fR and \fItarget\fR sections, you can also specify a +For the \fIvolume\fR and \fItarget\fR sections, you can specify a ssh-url instead of a local directory. The syntax for \fI\fR is: .PP .RS 4 @@ -56,8 +57,67 @@ Note that btrfs is very picky on file names (mainly for security reasons), only the characters [0-9] [a-z] [A-Z] and "._+-@" are allowed. .RE +.SH TARGET TYPES .PP -The configuration options are: +\fBsend-receive\fR +.RS 4 +Backup to a btrfs filesystem, using "btrfs send/receive". The +\fI\fR must be an absolute path and point to a btrfs +volume (or subvolume). See btrfs-send(8), btrfs-receive(8). +.RE +.PP +\fBraw\fR \fI*experimental*\fR +.RS 4 +Backup to a raw (filesystem independent) file from the output of +btrfs-send(8), with optional compression and encryption. +.PP +Additional options for raw target: +.PP +.RS 4 +raw_target_compress gzip|bzip2|xz|no +.PD 0 +.PP +raw_target_encrypt gpg|no +.PP +gpg_keyring +.PP +gpg_recipient +.RE +.PD +.PP +The target file name is: +.PP +.RS 4 +--[@].btrfs[.gz|.bz2|.xz][.gpg] +.RE +.PP +It is recommended to set "incremental no" for raw backups, for the +following reasons: +.IP \[bu] 2 +The target preserve mechanism is disabled for raw \fIincremental\fR +backups, since deleting of any intermediate backup would destroy the +consistency of all subsequent backups (btrbk will never delete any +backup in a raw incremental chain). +.IP \[bu] +No rotation of incremental backups: if \fIincremental\fR is set, a +full backup must be triggered manually from time to time in order to +be able to delete old backups. +.RE +.SH OPTIONS +.PP +\fBtimestamp_format\fR short|long +.RS 4 +Timestamp format used as postfix for new snapshot subvolume names. +defaults to \[lq]short\[rq]. +.IP \[bu] 2 +\fIshort\fR: YYYYMMDD[_N] (e.g. "20150825", "20150825_1") +.IP \[bu] +\fIlong\fR: YYYYMMDDhhmm[_N] (e.g. "20150825T1531") +.PP +Note that a postfix "_N" is only appended to the timestamp if a +snapshot/backup already exists with the timestamp of current +date/time. +.RE .PP \fBsnapshot_dir\fR .RS 4