diff --git a/doc/.gitignore b/doc/.gitignore index f31951c..284cd8c 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,2 +1 @@ -*.[1-8] *.[1-8].gz diff --git a/doc/btrbk.1 b/doc/btrbk.1 new file mode 100644 index 0000000..f89ab39 --- /dev/null +++ b/doc/btrbk.1 @@ -0,0 +1,561 @@ +'\" t +.\" Title: btrbk +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.7.1 +.\" Date: 2019-04-24 +.\" Manual: Btrbk Manual +.\" Source: Btrbk 0.28.0 +.\" Language: English +.\" +.TH "BTRBK" "1" "2019-04-24" "Btrbk 0.28.0" "Btrbk Manual" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +btrbk \- backup tool for btrfs subvolumes +.SH "SYNOPSIS" +.sp +.nf +btrbk [\-h|\-\-help] [\-\-version] + [\-c|\-\-config ] [\-n|\-\-dry\-run] [\-\-exclude ] + [\-p|\-\-preserve] [\-\-preserve\-snapshots] [\-\-preserve\-backups] + [\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel ] + [\-t|\-\-table] [\-\-format ] + [\-S|\-\-print\-schedule] [\-\-progress] + [\-\-lockfile ] + [\-\-override =] + [] +.fi +.br +.SH "DESCRIPTION" +.sp +\fBbtrbk\fP is a backup tool for btrfs subvolumes, taking advantage of +btrfs specific capabilities to create atomic snapshots and transfer +them incrementally to a target btrfs filesystem. It is able to perform +backups from one source to multiple destinations. +.sp +For most operations, \fBbtrbk\fP requires \fIroot privileges\fP to run +correctly. Alternatively, consider using "btrfs\-progs\-sudo" or +"btrfs\-progs\-btrbk" backends, both of which allows you to run btrbk as +a regular user. Refer to configuration option \fIbackend\fP in +btrbk.conf(5) for more details. +.SS "Snapshots and Backups" +.sp +Snapshots as well as backup subvolumes are created in form: +.sp +.if n .RS 4 +.nf +.[_N] +.fi +.if n .RE +.sp +Where \fI\fP is identical to the source subvolume name, +unless the configuration option \fIsnapshot_name\fP is set. The + is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the +\fItimestamp_format\fP 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 snapshot, starting at 1. +.sp +Note that \fIsnapshot\fP is a btrfs terminology for a \(lqread\-only +subvolume\(rq (showing a parent\-uuid, see btrfs\-subvolume(8)); \fIbackup\fP +is a btrbk terminology for a \(lqread\-only subvolume created with +send/receive\(rq (showing a received\-uuid). +.SH "OPTIONS" +.sp +\-h, \-\-help +.RS 4 +Prints the synopsis and a list of the commands. +.RE +.sp +\-\-version +.RS 4 +Prints the btrbk version. +.RE +.sp +\-c, \-\-config +.RS 4 +Read the configuration from . +.RE +.sp +\-n, \-\-dry\-run +.RS 4 +Don\(cqt run anything that would alter the filesystem, just show the +snapshots and backup subvolumes that would be created/deleted by +the \fBrun\fP, \fBsnapshot\fP, \fBresume\fP, \fBprune\fP, \fBarchive\fP and \fBclean\fP +commands. Use in conjunction with \fI\-l debug\fP to see the btrfs +commands that would be executed. +.RE +.sp +\-\-exclude +.RS 4 +Exclude configured sections matching \fI\fP. See +FILTER STATEMENTS below +.RE +.sp +\-p, \-\-preserve +.RS 4 +Preserve all snapshots and backups. Skips deletion of any +snapshots and backups, even if specified in the configuration file +(shortcut for "\-\-preserve\-snapshots \-\-preserve\-backups"). +.RE +.sp +\-\-preserve\-snapshots +.RS 4 +Preserve all snapshots. Skips deletion of any snapshots, even if +specified in the configuration file. +.RE +.sp +\-\-preserve\-backups +.RS 4 +Preserve all backups. Skips deletion of any backups, even if +specified in the configuration file. +.RE +.sp +\-\-wipe +.RS 4 +Ignore configured snapshot retention policy, delete all but latest +snapshots instead. All snapshots needed for incremental backup +(latest common) are also preserved. Useful if you are getting low +on disk space (ENOSPC). +.RE +.sp +\-v, \-\-verbose +.RS 4 +Verbose output (shortcut for "\-\-loglevel=info"). +.RE +.sp +\-q, \-\-quiet +.RS 4 +Quiet operation. If set, btrbk does not print the summary after +executing the \fBrun\fP, \fBsnapshot\fP, \fBresume\fP, \fBprune\fP, or \fBarchive\fP +commands. +.RE +.sp +\-l, \-\-loglevel +.RS 4 +Set the level of verbosity. Accepted levels are warn, info, debug, +and trace. +.RE +.sp +\-t, \-\-table +.RS 4 +Print output in table format (shortcut for "\-\-format=table"). +.RE +.sp +\-\-format table|long|raw +.RS 4 +Print output in specified format. If set to "raw", prints +space\-separated key="value" pairs (machine readable). Affects +output format for \fBrun\fP, \fBsnapshot\fP, \fBresume\fP, \fBprune\fP, \fBarchive\fP +and \fBlist\fP commands. Useful for further exporting/scripting. +.RE +.sp +\-S, \-\-print\-schedule +.RS 4 +Print detailed scheduler information on \fBrun\fP, \fBsnapshot\fP, +\fBresume\fP, \fBprune\fP and \fBarchive\fP commands. Use the \fI\-\-format\fP +command line option to switch between different output formats. +.RE +.sp +\-\-progress +.RS 4 +Show progress bar on send\-receive operation. +.RE +.sp +\-\-lockfile +.RS 4 +Create lockfile on startup; checks lockfile before running +any btrfs commands (using perl "flock"), and exits if the lock is +held by another btrbk instance. Overrides configuration option +"lockfile". Ignored on dryrun (\fI\-n\fP, \fI\-\-dry\-run\fP). +.RE +.sp +\-\-override = +.RS 4 +Override a configuration option with +. Globally, for ALL contexts. Use with care! +.RE +.SH "COMMANDS" +.SS "Actions" +.sp +The following commands are used to create snapshots and/or +backups. All actions can operate in dry\-run mode (\fI\-n\fP, \fI\-\-dry\-run\fP). +Use the \fI\-\-format\fP command line option to switch between different +output formats. +.sp +See section RETENTION POLICY in \fBbtrbk.conf\fP(5) for information on +configuring the retention policy. +.sp +\fBrun\fP [filter...] +.RS 4 +Perform snapshot and backup operations as specified in the +configuration file. If the optional [filter...] arguments are +present, snapshots and backups are only performed for the +subvolumes/targets matching a filter statement (see +FILTER STATEMENTS below). +.sp +\fBStep 0: Read Data\fP +.RS 4 +Read information from the source and target btrfs filesystems in +order to perform sanity checks and identify parent/child and +received\-from relationships. +.RE +.sp +\fBStep 1: Create Snapshots\fP +.RS 4 +If the checks succeed, btrbk creates snapshots for the source +subvolumes specified in the configuration file, according to the +\fIsnapshot_create\fP option. +.RE +.sp +\fBStep 2: Create Backups\fP +.RS 4 +For each specified target, btrbk creates the backups as follows: +After comparing the backups to the source snapshots, btrbk +transfers all missing snapshots needed to satisfy the configured +target retention policy, incrementally from the latest common +parent subvolume found. If no common parent subvolume is found (or +if the \fIincremental\fP option is set to \(lqno\(rq), a full +(non\-incremental) backup is created. +.RE +.sp +\fBStep 3: Delete Backups\fP +.RS 4 +Unless the \-p, \-\-preserve or \-\-preserve\-backups option is set, +backup subvolumes that are not preserved by their configured +retention policy will be deleted. Note that the latest +snapshot/backup pair are always preserved, regardless of the +retention policy. +.RE +.sp +\fBStep 4: Delete Snapshots\fP +.RS 4 +Unless the \-p, \-\-preserve or \-\-preserve\-snapshots option is set, +snapshots that are not preserved by their configured retention +policy will be deleted. Note that the latest snapshot (the one +created in step 1) as well as the latest snapshot/backup pair are +always preserved, regardless of the retention policy. +.RE +.RE +.sp +\fBdryrun\fP [filter...] +.RS 4 +Don\(cqt run any btrfs commands that would alter the filesystem, just +show the snapshots and backup subvolumes that would be +created/deleted by the \fBrun\fP command. Use in conjunction with \fI\-l +debug\fP to see the btrfs commands that would be executed. +.RE +.sp +\fBsnapshot\fP [filter...] +.RS 4 +Snapshot only: skips backup creation and deletion (steps 2 and +3). Use in conjunction with \-p, \-\-preserve (or +\-\-preserve\-snapshots) if you also want to skip snapshot deletion +(step 4). +.sp +Note that snapshot deletion is skipped if the target is not +accessible, as it is still required in order to determine the latest +snapshot/backup pair (which is always preserved, regardless of the +retention policy). +.RE +.sp +\fBresume\fP [filter...] +.RS 4 +Resume backups: skips snapshot creation (step 1), transfers and +deletes snapshots/backups in order to satisfy their configured +retention policy. Use in conjunction with \-p, \-\-preserve, +\-\-preserve\-backups, \-\-preserve\-snapshots if you want to skip +backup and/or snapshot deletion (steps 3, 4). +.RE +.sp +\fBprune\fP [filter...] +.RS 4 +Prune snapshots and backups: skips snapshot and backup creation +(steps 1, 2), only deletes snapshots and backups in order to +satisfy their configured retention policy. Useful for cleaning the +disk after changing the retention policy. Use in conjunction with +\-\-preserve\-backups, \-\-preserve\-snapshots if you want to skip +backup or snapshot deletion (steps 3, 4). +.sp +Note that deletion is skipped if source or target is not accessible, +as it is still required in order to determine the latest +snapshot/backup pair (which is always preserved, regardless of the +retention policy). +.RE +.sp +\fBarchive\fP +.RS 4 +Recursively copy all subvolumes created by btrbk from to + directory, optionally rescheduled using +\fIarchive_preserve_*\fP configuration options. Also creates directory +tree on . Useful for creating extra archive copies +(clones) from your backup disks. Note that you can continue using +btrbk after swapping your backup disk with the archive disk. +.sp +If you want to use nested subvolumes on the target filesystem, you +need to create them by hand (e.g. by running "btrfs subvolume create +/dir"). Check the output of \-\-dry\-run if unsure. +.sp +Note that this feature needs a \fBlinux kernel >=4.4\fP to work correctly! +.RE +.sp +\fBclean\fP [filter...] +.RS 4 +Delete incomplete (garbled) backups. Incomplete backups can be +left behind on network errors or kill signals while a send/receive +operation is ongoing, and are identified by the "received_uuid" +flag not being set on a target (backup) subvolume. +.RE +.sp +The following table gives a quick overview of the action commands and +resulting snapshot creation (S+), backup creation (B+), snapshot +deletion (S\-), and backup deletion (B\-): +.sp +.if n .RS 4 +.nf +Command Option S+ B+ S\- B\- +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +run x x x x +run \-\-preserve x x +run \-\-preserve\-snapshots x x x +run \-\-preserve\-backups x x x +snapshot x x +snapshot \-\-preserve x +resume x x x +resume \-\-preserve x +resume \-\-preserve\-snapshots x x +resume \-\-preserve\-backups x x +prune x x +prune \-\-preserve\-snapshots x +prune \-\-preserve\-backups x +.fi +.if n .RE +.SS "Informative Commands" +.sp +The following commands are informative only, and will not alter the +file system. +.sp +\fBstats\fP [filter...] +.RS 4 +Print statistics of snapshot and backup subvolumes. Optionally +filtered by [filter...] arguments (see FILTER +STATEMENTS below). +.RE +.sp +\fBlist\fP [filter...] +.RS 4 +Print information defined by in a tabular +form. Optionally filtered by [filter...] arguments (see +FILTER STATEMENTS below). +.sp +Available subcommands: +.sp +\fBsnapshots\fP +.RS 4 +List all snapshots (and corresponding backups). Note +that all snapshots related to configured subvolumes are +listed, not only the ones created by btrbk. +.RE +.sp +\fBbackups\fP +.RS 4 +List all backups (and corresponding snapshots). +.RE +.sp +\fBlatest\fP +.RS 4 +List most recent common snapshot/backup pair, or most +recent snapshot if no common found. +.RE +.sp +\fBconfig\fP +.RS 4 +List configured source/snapshot/target relations. +.RE +.sp +\fBsource\fP +.RS 4 +List configured source/snapshot relations. +.RE +.sp +\fBvolume\fP +.RS 4 +List configured volume sections. +.RE +.sp +\fBtarget\fP +.RS 4 +List configured targets. +.RE +.sp +Use the \fI\-\-format\fP command line option to switch between +different output formats. +.RE +.sp +\fBusage\fP [filter...] +.RS 4 +Print filesystem usage information for all source/target volumes, +optionally filtered by [filter...] arguments (see +FILTER STATEMENTS below). Note that the +"free" value is an estimate of the amount of data that can still +be written to the file system. +.RE +.sp +\fBorigin\fP +.RS 4 +Print the subvolume origin tree: Shows the parent\-child +relationships as well as the received\-from information. Use the +\fI\-\-format\fP command line option to switch between different output +formats. +.RE +.sp +\fBdiff\fP +.RS 4 +Print new files since subvolume for subvolume . +.RE +.sp +\fBconfig\fP print|print\-all +.RS 4 +Prints the parsed configuration file. Use the \fI\-\-format\fP command +line option to switch between different output formats. +.RE +.SH "FILTER STATEMENTS" +.sp +Filter arguments are accepted in form: +.sp + +.RS 4 +Matches the \fIgroup\fP configuration option of \fIvolume\fP, \fIsubvolume\fP +or \fItarget\fP sections. +.RE +.sp +[:] +.RS 4 +Matches the \fIhostname\fP portion from \fI\fP of \fIvolume\fP or +\fItarget\fP sections. +.RE +.sp +| +.RS 4 +Matches \fIvolume\fP, \fIsubvolume\fP or \fItarget\fP sections by either +relative or absolute path (if starting with "/" or "ssh://" or +":/"), accepting wildcard character "*". Relative paths +are matched against the end of the pathname. Either: +.sp + +.RS 4 +Matches \fIvolume\fP sections. +.RE +.sp +/ +.RS 4 +Matches \fIsubvolume\fP sections. +.RE +.sp +// +.RS 4 +Matches \fIsubvolume\fP sections defining snapshots with the +configured \fIsnapshot_dir\fP and \fIsnapshot_name\fP. +.RE +.sp + +.RS 4 +Matches \fItarget\fP sections. +.RE +.sp +/ +.RS 4 +Matches \fItarget\fP sections within \fIsubvolume\fP sections defining +snapshots with the configured \fIsnapshot_name\fP. +.RE +.sp +Accepted formats for \fI\fP are: +.sp +.if n .RS 4 +.nf +ssh://[:]/ +: +.fi +.if n .RE +.RE +.sp +Note that for \fBrun\fP and \fBsnapshot\fP commands, a filter matching a +\fItarget\fP configuration section also enables snapshot creation of the +surrounding \fIsubvolume\fP section. If this is not desired, consider +running \fBsnapshot\fP and \fBresume\fP commands separately. +.SH "FILES" +.sp +\f(CR/etc/btrbk.conf\fP, \f(CR/etc/btrbk/btrbk.conf\fP +.RS 4 +Default configuration file. The file format and configuration +options are described in \fBbtrbk.conf\fP(5). +.RE +.SH "EXIT STATUS" +.sp +\fBbtrbk\fP returns the following error codes: +.sp +0 +.RS 4 +No problems occurred. +.RE +.sp +1 +.RS 4 +Generic error code. +.RE +.sp +2 +.RS 4 +Parse error: when parsing command\-line options or configuration +file. +.RE +.sp +3 +.RS 4 +Lockfile error: if lockfile is present on startup. +.RE +.sp +10 +.RS 4 +Backup abort: At least one backup task aborted. +.RE +.sp +255 +.RS 4 +Script error. +.RE +.SH "AVAILABILITY" +.sp +Please refer to the btrbk project page \fB\c +.URL "https://digint.ch/btrbk/" "" "\fP" +for further details. +.SH "SEE ALSO" +.sp +\fBbtrbk.conf\fP(5), +\fBbtrfs\fP(8) +.sp +For more information about btrfs and incremental backups, see the web +site at \c +.URL "https://btrfs.wiki.kernel.org/index.php/Incremental_Backup" "" "" +.SH "AUTHOR" +.sp +Axel Burri <\c +.MTO "axel\(attty0.ch" "" ">" \ No newline at end of file diff --git a/doc/btrbk.conf.5 b/doc/btrbk.conf.5 new file mode 100644 index 0000000..489008d --- /dev/null +++ b/doc/btrbk.conf.5 @@ -0,0 +1,744 @@ +'\" t +.\" Title: btrbk.conf +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.7.1 +.\" Date: 2019-04-24 +.\" Manual: Btrbk Manual +.\" Source: Btrbk 0.28.0 +.\" Language: English +.\" +.TH "BTRBK.CONF" "5" "2019-04-24" "Btrbk 0.28.0" "Btrbk Manual" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +btrbk.conf \- btrbk configuration file +.SH "SYNOPSIS" +.sp +.nf +/etc/btrbk.conf +/etc/btrbk/btrbk.conf +.fi +.br +.SH "DESCRIPTION" +.sp +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 most other options can be +defined either globally or within a section. +.sp +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. +.sp +Blank lines are ignored. A hash character (#) starts a comment +extending until end of line. +.sp +Whitespace or unicode characters are not allowed for file +names. Allowed characters are: +.sp +.if n .RS 4 +.nf +[0\-9] [a\-z] [A\-Z] and "._+\-@" +.fi +.if n .RE +.sp +This is for sanity/safety/security reasons, we apologize for the +inconvenience. +.SH "SECTIONS" +.sp +\fBvolume\fP | +.RS 4 +Directory of a btrfs volume containing the source subvolume(s) to +be backed up. \fI\fP 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=5\fP option. +.RE +.sp +\fBsubvolume\fP +.RS 4 +Subvolume to be backed up, relative to the \fI\fP +specified in the \fIvolume\fP section. Multiple \fIsubvolume\fP sections +are allowed within \fIvolume\fP sections. Accepts wildcard character +"*". +.sp +If set to ".", the subvolume at \fI\fP is used as backup +source, and the snapshots will be created within the source subvolume +itself (see \fIsnapshot_dir\fP option below), which is not recommended. +Note that if this subvolume is btrfs root (id=5), it needs to have a +valid UUID, which is not the case for file systems created with +btrfs\-progs < 4.16. +.RE +.sp +\fBtarget\fP [send\-receive|raw] | +.RS 4 +Target directory where the backup subvolumes are to be +created. The optional target type defaults to \(lqsend\-receive\(rq, +see TARGET TYPES below for details. +.sp +Multiple \fItarget\fP sections are allowed, in any context: a \fItarget\fP +defined in \fIvolume\fP or global context will be used for all underlying +\fIsubvolume\fP sections (hint: run "btrbk list" or "btrbk config print" +to see the resulting configuration). +.RE +.sp +If a \fI\fP is specified, btrbk actions (shell commands) are executed +remotely via ssh, using the SSH Options described +below. Accepted formats are: +.sp +.if n .RS 4 +.nf +ssh://[:]/ +: +.fi +.if n .RE +.sp +If you are connecting to virtual machines, consider configuring +several \fIvolume\fP sections for a \fI\fP, with distinct \fI\fP +numbers for each machine. +.SH "OPTIONS" +.sp +The options described here can be specified in \fIglobal context\fP as +well as \fIvolume\fP, \fIsubvolume\fP and \fItarget\fP sections, unless stated +otherwise. +.SS "Basic Options" +.sp +\fBtimestamp_format\fP short|long|long\-iso +.RS 4 +Timestamp format used as postfix for new snapshot subvolume +names. Defaults to \(lqshort\(rq. +.sp +\fBshort\fP +.RS 4 +\f(CRYYYYMMDD[_N]\fP (e.g. "20150825", "20150825_1") +.RE +.sp +\fBlong\fP +.RS 4 +\f(CRYYYYMMDDhhmm[_N]\fP (e.g. "20150825T1531") +.RE +.sp +\fBlong\-iso\fP +.RS 4 +\f(CRYYYYMMDDhhmmss±hhmm[_N]\fP (e.g. "20150825T153123+0200") +.RE +.sp +Note that a postfix "_N" is appended to the timestamp if a snapshot or +backup already exists with the timestamp of current date/time. +.sp +Use \(lqlong\-iso\(rq if you want to make sure that btrbk never +creates ambiguous time stamps (which can happen if multiple +snapshots are created during a daylight saving time clock +change). +.sp +Note that using \(lqlong\-iso\(rq has implications on the scheduling, see +RETENTION POLICY (caveats) below. +.RE +.sp +\fBsnapshot_dir\fP +.RS 4 +Directory in which the btrfs snapshots are created, relative to +\fI\fP of the \fIvolume\fP section. Note that btrbk does +not autmatically create this directory, and the snapshot creation +will fail if it is not present. +.RE +.sp +\fBsnapshot_name\fP +.RS 4 +Base name of the created snapshot (and backup). This option is +only valid in the \fIsubvolume\fP section. Defaults to +\fI\fP. +.RE +.sp +\fBsnapshot_create\fP always|onchange|ondemand|no +.RS 4 +If set to \(lqalways\(rq, snapshots are always created. If set to +\(lqonchange\(rq, snapshots are only created if the source subvolume +has changed since the last snapshot (more precisely: if the btrfs +generation has been increased since the last snapshot). If set to +\(lqondemand\(rq, snapshots are only created if at least one target +subvolume is reachable (useful if you are tight on disk space and +you only need btrbk for backups to an external disk which is not +always connected). If set to \(lqno\(rq, the snapshots are never +created (useful if another instance of btrbk is taking care of +snapshot creation). Defaults to \(lqalways\(rq. +.RE +.sp +\fBincremental\fP yes|no|strict +.RS 4 +If set, incremental backups are created. If set to \(lqstrict\(rq, +non\-incremental (initial) backups are never created, and +incremental backups are restricted to \fIrelated parents\fP (by +parent\-uuid relationship). Defaults to \(lqyes\(rq. +.sp +Note that even if the parent\-uuid chain is broken, snapshots and +backups can still share data (which is especially true for backups +created with \fIincremental\fP option enabled), and are perfectly suitable +as parents for incremental send\-receive operations. But as btrbk can +not be certain about this, such operations are disallowed in +"incremental strict" mode. +.RE +.sp +\fBnoauto\fP yes|no +.RS 4 +If set, the context is skipped by all btrbk actions unless +explicitely enabled by a matching btrbk \fI\fP command line +argument (e.g. "btrbk run myfilter"). +.RE +.SS "Grouping Options" +.sp +\fBgroup\fP []... +.RS 4 +Add the current section (volume, subvolume or target) to +user\-defined groups, which can be used as filter for most btrbk +commands. This option can be set multiple times within the same +context. +.RE +.SS "Retention Policy Options" +.sp +\fBpreserve_day_of_week\fP monday|tuesday|...|sunday +.RS 4 +Defines on what day a snapshot/backup is considered to be a +"weekly" backup. Weekly, monthly and yearly backups are preserved +on this day of week (see RETENTION POLICY +below). Defaults to \(lqsunday\(rq. +.RE +.sp +\fBpreserve_hour_of_day\fP [0..23] +.RS 4 +Defines after what time (in full hours since midnight) a +snapshot/backup is considered to be a "daily" backup. Daily, +weekly, monthly and yearly backups are preserved on this hour (see +RETENTION POLICY below). If you set this +option, make sure to also set \fItimestamp_format\fP to \(lqlong\(rq or +\(lqlong\-iso\(rq (backups and snapshots having no time information +will ignore this option). Defaults to \(lq0\(rq. +.RE +.sp +\fBsnapshot_preserve\fP no| +.RS 4 +Set retention policy for snapshots (see +RETENTION POLICY below). If set to \(lqno\(rq, +preserve snapshots according to \fIsnapshot_preserve_min\fP +only. Defaults to \(lqno\(rq. +.RE +.sp +\fBsnapshot_preserve_min\fP all|latest|{h,d,w,m,y} +.RS 4 +Preserve all snapshots for a minimum amount of hours (h), days +(d), weeks (w), months (m) or years (y), regardless of how many +there are. If set to \(lqall\(rq, preserve all snapshots forever. If +set to \(lqlatest\(rq, preserve latest snapshot. Defaults to \(lqall\(rq. +.RE +.sp +\fBtarget_preserve\fP no| +.RS 4 +Set retention policy for backups (see +RETENTION POLICY below). If set to \(lqno\(rq, +preserve backups according to \fItarget_preserve_min\fP only. Defaults +to \(lqno\(rq. +.RE +.sp +\fBtarget_preserve_min\fP all|latest|no|{h,d,w,m,y} +.RS 4 +Preserve all backups for a minimum amount of hours (h), days (d), +weeks (w), months (m) or years (y), regardless of how many there +are. If set to \(lqall\(rq, preserve all backups forever. If set to +\(lqlatest\(rq, always preserve the latest backup (useful in +conjunction with "target_preserve no", if you want to keep the +latest backup only). If set to \(lqno\(rq, only the backups following +the \fItarget_preserve\fP policy are created. Defaults to \(lqall\(rq. +.RE +.sp +\fBarchive_preserve\fP no| +.RS 4 +Set retention policy for archives ("btrbk archive" command), with +same semantics as \fItarget_preserve\fP. +.RE +.sp +\fBarchive_preserve_min\fP all|latest|no|{h,d,w,m,y} +.RS 4 +Set retention policy for archives ("btrbk archive" command), with +same semantics as \fItarget_preserve_min\fP. +.RE +.sp +\fBarchive_exclude\fP +.RS 4 +Exclude subvolumes matching from archiving. The pattern +accepts wildcard character "*", and is matched against the end of +the pathname. +.RE +.SS "SSH Options" +.sp +\fBssh_identity\fP +.RS 4 +Absolute path to a ssh identity file (private key). Note that if +the private key is password protected, btrbk will prompt for user +input, which is usually not desired. +.RE +.sp +\fBssh_user\fP +.RS 4 +Remote username for ssh. Defaults to \(lqroot\(rq. Make sure the +remote user is able to run "btrfs" with root privileges (see +option \fIbackend\fP for details). +.RE +.sp +\fBssh_compression\fP yes|no +.RS 4 +Enables or disables the compression of ssh connections. Defaults +to \(lqno\(rq. +.RE +.sp +\fBssh_cipher_spec\fP +.RS 4 +Selects the cipher specification for encrypting the session +(comma\-separated list of ciphers in order of preference). See the +"\-c cipher_spec" option in ssh(1) for more information. Defaults +to \(lqdefault\(rq (the ciphers specified in \fIssh_config\fP). +.RE +.sp +Previous versions btrbk allowed you to set a \fBssh_port\fP option, this +has been dropped in favor of the \f(CRssh://hostname:port\fP notation in the +\fIvolume\fP and \fItarget\fP sections. If you want to set a +global port for all SSH connections to remote hosts, set the \(lqPort\(rq +option in ssh_config(5). +.SS "Data Stream Options" +.sp +\fBstream_compress\fP |no +.RS 4 +Compress the btrfs send stream before transferring it from/to +remote locations. Defaults to \(lqno\(rq. If enabled, make sure that +\fI\fP is available on the source and target +hosts. Supported \fI\fP: gzip, pigz, bzip2, pbzip2, +xz, lzo, lz4. +.RE +.sp +\fBstream_compress_level\fP default| +.RS 4 +Compression level for the specified \fI\fP. Refer to +the related man\-page for details (usually [1..9], where 1 means +fastest compression). Defaults to \(lqdefault\(rq (the default +compression level of \fI\fP). +.RE +.sp +\fBstream_compress_threads\fP default| +.RS 4 +Number of threads to use for . Only supported +for "pigz", "pbzip2" and recent versions of "xz". +.RE +.sp +\fBstream_buffer\fP |no +.RS 4 +Add a buffer to the btrfs send stream (in front of "btrfs +receive"), with a maximum size of \fI\fP. This can give a speed +improvement (measured up to 20%) on both local or remote +operations, but also increases system load. A suffix of "k", "m", +"g", or "%" can be added to \fI\fP to denote kilobytes (*1024), +megabytes, gigabytes, or a percentage of total physical +memory. Defaults to \(lqno\(rq. +.sp +If enabled, make sure that the "mbuffer" command is available on the +target host. Note that versions of mbuffer < 20180505 suffered from +nasty bugs (infinite loops, hangs); if your main concern is a stable +backup process, leave this option disabled. +.RE +.sp +\fBrate_limit\fP |no +.RS 4 +Limit the transfer to a maximum of \fI\fP bytes per second. A +suffix of "k", "m", "g", or "t" can be added to denote kilobytes +(*1024), megabytes, and so on. Defaults to \(lqno\(rq. If enabled for +remote sources, make sure that the "pv" command is available on +the source host. +.RE +.SS "System Options" +.sp +\fBtransaction_log\fP |no +.RS 4 +If set, all transactions (snapshot create, subvolume send\-receive, +subvolume delete) as well as abort messages are logged to , +in a space\-separated table format: "localtime type status +target_url source_url parent_url message". +.RE +.sp +\fBtransaction_syslog\fP |no +.RS 4 +If set, all transactions (as described in \fItransaction_log\fP above) +are logged to syslog. The program name used in the messages is +"btrbk". Accepted parameters for \fI\fP: user, mail, +daemon, auth, lpr, news, cron, authpriv, local0..local7. +.RE +.sp +\fBlockfile\fP |no +.RS 4 +Create lockfile on startup; checks lockfile before running +any btrfs commands (using perl "flock"), and exits if the lock is +held by another btrbk instance. Ignored on dryrun (\fI\-n\fP, +\fI\-\-dry\-run\fP). See also \fI\-\-lockfile\fP command\-line option. +.RE +.sp +\fBbackend\fP btrfs\-progs|btrfs\-progs\-btrbk|btrfs\-progs\-sudo +.RS 4 +Backend filesystem utilities to be used for btrfs specific +operations. Defaults to \(lqbtrfs\-progs\(rq. +.sp +btrfs\-progs +.RS 4 +Default backend, btrfs commands are called as specified in +btrfs(8) (e.g. "btrfs subvolume show"). +.RE +.sp +btrfs\-progs\-btrbk +.RS 4 +btrfs commands are separated by a dash instead of a whitespace +(e.g. "btrfs\-subvolume\-show" instead of "btrfs subvolume +show"). Useful for setting suid or file capabilities (setcap) on +specific btrfs commands, as implemented in +.URL "https://github.com/digint/btrfs\-progs\-btrbk" "" "." +.RE +.sp +btrfs\-progs\-sudo +.RS 4 +btrfs commands are prefixed with "sudo \-n" (e.g. "sudo \-n btrfs +subvolume show" instead of "btrfs subvolume show"). Make sure to +have appropriate (root) permissions for the "btrfs" command groups +and the "readlink" command in /etc/sudoers. +.RE +.sp +For convenience, it is also possible to set \fBbackend_local\fP or +\fBbackend_remote\fP options, which will override the backend only for +local or remote sources/targets (e.g. "backend_remote +btrfs\-progs\-btrbk"). +.RE +.SS "Btrfs Specific Options" +.sp +\fBbtrfs_commit_delete\fP after|each|no +.RS 4 +If set, make sure the deletion of snapshot and backup subvolumes +are committed to disk when btrbk terminates. Defaults to \(lqno\(rq. +.RE +.sp +\fBincremental_clones\fP +.RS 4 +Maximum number of clone sources allowed for incremental send. If +set, btrbk adds "\-c " to the btrfs\-send(8) command for +all present snapshot/backup pairs (correlated subvolumes matching +matching \fIreceived_uuid\fP, printed by "btrbk stats"). Set this to a +high number if you want to make sure that no common data is missed +on incremental backups, in expense of btrfs\-send +performance. Defaults to 0. +.RE +.sp +\fBincremental_resolve\fP mountpoint|directory +.RS 4 +Specifies where to search for the best common parent for +incremental backups. If set to \(lqmountpoint\(rq, use parents in the +filesystem tree below mount points of source +"/" and target +"". If set to \(lqdirectory\(rq, use parents +strictly below source/target directories. Set this to +\(lqdirectory\(rq if you get access problems (when not running btrbk +as root). Defaults to \(lqmountpoint\(rq. +.RE +.sp +\fBsnapshot_qgroup_destroy\fP yes|no \fI*experimental*\fP +.RS 4 + +.RE +.sp +\fBtarget_qgroup_destroy\fP yes|no \fI*experimental*\fP +.RS 4 + +.RE +.sp +\fBarchive_qgroup_destroy\fP yes|no \fI*experimental*\fP +.RS 4 +Whenever a subvolume is deleted, also destroy corresponding +default qgroup "\f(CR0/\fP". Only useful if you have enabled +btrfs quota support. See also: +.URL "https://bugzilla.kernel.org/show_bug.cgi?id=91751" "" "" +.RE +.SH "RETENTION POLICY" +.sp +btrbk uses separate retention policies for snapshots and backups, +which are defined by the \fIsnapshot_preserve_min\fP, \fIsnapshot_preserve\fP, +\fItarget_preserve_min\fP, \fItarget_preserve\fP, \fIpreserve_day_of_week\fP and +\fIpreserve_hour_of_day\fP configuration options. +.sp +Within this section, any statement about "backups" is always valid for +backups as well as snapshots, referring to \fItarget_preserve\fP or +\fIsnapshot_preserve\fP respectively. +.sp +The format for \fI\fP is: +.sp +.if n .RS 4 +.nf +[h] [d] [w] [m] [y] +.fi +.if n .RE +.sp +With the following semantics: +.sp +\fBhourly\fP +.RS 4 +Defines how many hours back hourly backups should be +preserved. The first backup of an hour is considered an hourly +backup. Note that if you use scheduling, make sure to +also set \fItimestamp_format\fP to \(lqlong\(rq or \(lqlong\-iso\(rq, or the +scheduler will interpret the time as "00:00" (midnight). +.RE +.sp +\fBdaily\fP +.RS 4 +Defines how many days back daily backups should be preserved. The +first backup of a day (starting at \fIpreserve_hour_of_day\fP) is +considered a daily backup. +.RE +.sp +\fBweekly\fP +.RS 4 +Defines how many weeks back weekly backups should be +preserved. The first daily backup created at +\fIpreserve_day_of_week\fP (or the first backup in this week if none +was made on the exact day) is considered as a weekly backup. +.RE +.sp +\fBmonthly\fP +.RS 4 +Defines how many months back monthly backups should be +preserved. Every first weekly backup in a month is considered a +monthly backup. +.RE +.sp +\fByearly\fP +.RS 4 +Defines for how many years back yearly backups should be +preserved. Every first monthly backup in a year is considered a +yearly backup. +.RE +.sp +Use an asterisk for \(lqall\(rq (e.g. "target_preserve 60d *m" +states: "preserve daily backups for 60 days back, and all monthly +backups"). +.sp +The reference time (which defines the beginning of a day, week, month +or year) for all date/time calculations is the local time of the host +running btrbk. +.sp +Hint: Run btrbk with the \fI\-S\fP, \fI\-\-print\-schedule\fP option to get a +comprehensive output of the scheduler results. +.sp +Caveats: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +If you run a setup with several btrbk instances (e.g. one +snapshot\-only instance per remote client, and a separate fetch\-only +instance on the backup server), it makes perfectly sense to run +btrbk with different local time on the clients, in order to make +sure the backups from all the remote hosts are preserved for +"midnight", and not at "00:00 UTC" (which would be "14:00" in +Honolulu). If you want this behaviour, do NOT use "timestamp_format +long\-iso". +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +If "timestamp_format long\-iso" is set, running btrbk from different +time zones leads to different interpretation of "first in day, week, +month, or year". Make sure to run btrbk with the same time zone on +every host, e.g. by setting the TZ environment variable (see +tzset(3)). +.RE +.SH "TARGET TYPES" +.sp +\fBsend\-receive\fP +.RS 4 +Backup to a btrfs filesystem, using "btrfs send/receive". This is +the recommended (standard) target type. The \fI\fP +must be an absolute path and point to a btrfs volume (or +subvolume), or to a directory within a subvolume. See +btrfs\-send(8), btrfs\-receive(8). +.RE +.sp +\fBraw\fP \fI*experimental*\fP +.RS 4 +Backup to a raw (filesystem independent) file from the output of +btrfs\-send(8), with optional compression and encryption. +.sp +Note that the target preserve mechanism is currently disabled for +incremental raw backups (btrbk does not delete any incremental raw +files)! +.sp +Raw backups consist of two files: the main data file containing the +btrfs send stream, and a sidecar file ".info" containing metadata: +.sp +.if n .RS 4 +.nf +.[_N].btrfs[.gz|.bz2|.xz][.gpg] +.[_N].btrfs[.gz|.bz2|.xz][.gpg].info +.fi +.if n .RE +.sp +For \fIincremental\fP backups ("incremental yes"), please note that: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +As soon as a single \fIincremental\fP backup file is lost or corrupted, +all later incremental backups become invalid, as there is no common +parent for the subsequent incremental images anymore. This might be +a good compromise for a vacation backup plan, but for the long term +make sure that a non\-incremental backup is triggered from time to +time. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +There is currently no support for rotation of incremental backups: +if \fIincremental\fP is set, a full backup must be triggered manually +from time to time in order to be able to delete old backups. +.RE +.sp +Additional options for raw targets: +.sp +\fBraw_target_compress\fP |no +.RS 4 +Compression algorithm to use for raw backup target. Supported +\fI\fP: gzip, pigz, bzip2, pbzip2, xz, lzo, lz4. +.RE +.sp +\fBraw_target_compress_level\fP default| +.RS 4 +Compression level for the specified . +.RE +.sp +\fBraw_target_compress_threads\fP default| +.RS 4 +Number of threads to use for . +.RE +.sp +\fBraw_target_split\fP |no +.RS 4 +Split the raw backup file into pieces of size \fI\fP. +.RE +.sp +\fBraw_target_block_size\fP +.RS 4 +Block size to use for writing the raw backup file. Defaults to +\(lq128K\(rq. +.RE +.sp +\fBraw_target_encrypt\fP gpg|openssl_enc|no +.RS 4 +If enabled, encrypt the target raw file using gpg or openssl_enc. +.RE +.sp +Additional options for "raw_target_encrypt gpg": +.sp +\fBgpg_keyring\fP +.RS 4 +Keyring to use for gpg, e.g. "\f(CR/etc/btrbk/gpg/pubring.kbx\fP". +.RE +.sp +\fBgpg_recipient\fP +.RS 4 +Encrypt for user id \fI\fP (email address). +.RE +.sp +Additional options for "raw_target_encrypt openssl_enc" (\fIvery +experimental\fP): +.sp +\fBopenssl_ciphername\fP\~ +.RS 4 +Defaults to \(lqaes\-256\-cbc\(rq. +.RE +.sp +\fBopenssl_iv_size\fP |no +.RS 4 +Depends on selected cipher. +.RE +.sp +\fBopenssl_keyfile\fP |no +.RS 4 +Point to a key file in hex (absolute path). Example key file +creation (256bit key): +.sp +.if n .RS 4 +.nf + # dd if=/dev/urandom bs=1 count=32 \(rs + | od \-x \-A n \(rs + | tr \-d "[:space:]" > /path/to/keyfile +.fi +.if n .RE +.RE +.sp +\fBkdf_backend\fP |no +.RS 4 +KDF backend to be executed, +e.g. "\f(CR/usr/share/btrbk/scripts/kdf_pbkdf2.py\fP". +.RE +.sp +\fBkdf_keysize\fP +.RS 4 +Defaults to \(lq32\(rq. +.RE +.sp +\fBkdf_keygen\fP once|each +.RS 4 +Defaults to \(lqonce\(rq. +.RE +.RE +.SH "AVAILABILITY" +.sp +Please refer to the btrbk project page \fB\c +.URL "https://digint.ch/btrbk/" "" "\fP" +for further details. +.SH "SEE ALSO" +.sp +\fBbtrbk\fP(1) +.SH "AUTHOR" +.sp +Axel Burri <\c +.MTO "axel\(attty0.ch" "" ">" \ No newline at end of file diff --git a/doc/ssh_filter_btrbk.1 b/doc/ssh_filter_btrbk.1 new file mode 100644 index 0000000..9045871 --- /dev/null +++ b/doc/ssh_filter_btrbk.1 @@ -0,0 +1,208 @@ +'\" t +.\" Title: ssh_filter_btrbk +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.7.1 +.\" Date: 2019-04-24 +.\" Manual: Btrbk Manual +.\" Source: Btrbk 0.28.0 +.\" Language: English +.\" +.TH "SSH_FILTER_BTRBK" "1" "2019-04-24" "Btrbk 0.28.0" "Btrbk Manual" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +ssh_filter_btrbk \- ssh command filter script for btrbk +.SH "SYNOPSIS" +.sp +.nf +ssh_filter_btrbk.sh [\-s|\-\-source] [\-t|\-\-target] [\-d|\-\-delete] + [\-i|\-\-info] [\-\-snapshot] [\-\-send] [\-\-receive] + [\-p|\-\-restrict\-path ] [\-l|\-\-log] [\-\-sudo] +.fi +.br +.SH "DESCRIPTION" +.sp +\fBssh_filter_btrbk.sh\fP restricts SSH commands to commands used by +\fIbtrbk\fP. It examines the SSH_ORIGINAL_COMMAND environment variable +(set by sshd) and executes it only if it contains commands used by +\fIbtrbk\fP. +.sp +The accepted commands are specified by the "\-\-source", "\-\-target", +"\-\-delete" and "\-\-info" options. +.sp +The following commands are always allowed: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +"btrfs subvolume show" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +"btrfs subvolume list" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +"readlink" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +"cat /proc/self/mountinfo" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +pipes through "gzip", "pigz", "bzip2", "pbzip2", "xz", "lzop", +"lz4" (stream_compress) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +pipes through "mbuffer" (stream_buffer) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +pipes through "pv \-L" (rate_limit) +.RE +.sp +Example line in /root/.ssh/authorized_keys on a backup target host: +.sp +.if n .RS 4 +.nf +command="ssh_filter_btrbk.sh \-\-target \-\-delete \-\-restrict\-path /mnt/btr_backup" ssh\-rsa AAAAB3NzaC1...hwumXFRQBL btrbk@mydomain.com +.fi +.if n .RE +.SH "OPTIONS" +.sp +\-s, \-\-source +.RS 4 +Allow commands for backup source: "btrfs subvolume snapshot", +"btrfs send". Equivalent to "\-\-snapshot \-\-send". +.RE +.sp +\-t, \-\-target +.RS 4 +Allow commands for backup target: "btrfs receive". +.RE +.sp +\-d, \-\-delete +.RS 4 +Allow commands for subvolume deletion: "btrfs subvolume +delete". This is used for backup source if +\fIsnapshot_preserve_daily\fP is not set to \(lqall\(rq, and for backup +targets if \fItarget_preserve_daily\fP is not set to \(lqall\(rq. +.RE +.sp +\-i, \-\-info +.RS 4 +Allow informative commands: "btrfs subvolume find\-new", "btrfs +filesystem usage". This is used by btrbk \fIinfo\fP and \fIdiff\fP +commands. +.RE +.sp +\-\-snapshot +.RS 4 +Allow btrfs snapshot command: "btrfs subvolume snapshot". +.RE +.sp +\-\-send +.RS 4 +Allow btrfs send command: "btrfs send". +.RE +.sp +\-\-receive +.RS 4 +Allow btrfs receive command: "btrfs receive". +.RE +.sp +\-p, \-\-restrict\-path +.RS 4 +Restrict btrfs commands to . +.RE +.sp +\-l, \-\-log +.RS 4 +Log ACCEPT and REJECT messages to the system log. +.RE +.sp +\-\-sudo +.RS 4 +Allow btrfs commands to be called via sudo. Enable this if you +have "backend btrfs\-progs\-sudo" in your btrbk configuration file. +.RE +.SH "AVAILABILITY" +.sp +Please refer to the btrbk project page \fB\c +.URL "https://digint.ch/btrbk/" "" "\fP" +for further details. +.SH "SEE ALSO" +.sp +\fBbtrbk\fP(1), +\fBbtrbk.conf\fP(5), +\fBbtrfs\fP(8) +.SH "AUTHOR" +.sp +Axel Burri <\c +.MTO "axel\(attty0.ch" "" ">" \ No newline at end of file