diff --git a/doc/.gitignore b/doc/.gitignore index 284cd8c..f31951c 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1 +1,2 @@ +*.[1-8] *.[1-8].gz diff --git a/doc/btrbk.1 b/doc/btrbk.1 deleted file mode 100644 index f89ab39..0000000 --- a/doc/btrbk.1 +++ /dev/null @@ -1,561 +0,0 @@ -'\" 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 deleted file mode 100644 index 489008d..0000000 --- a/doc/btrbk.conf.5 +++ /dev/null @@ -1,744 +0,0 @@ -'\" 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 deleted file mode 100644 index 9045871..0000000 --- a/doc/ssh_filter_btrbk.1 +++ /dev/null @@ -1,208 +0,0 @@ -'\" 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