From c4ced9d6e40313594bbcf6f76890fa0aaad73a31 Mon Sep 17 00:00:00 2001 From: Axel Burri Date: Mon, 9 Oct 2017 14:52:15 +0200 Subject: [PATCH] documentation: convert all groff files (man pages) to asciidoc - btrbk.conf.5 to btrbk.conf.5.asciidoc - btrbk.1 to btrbk.1.asciidoc - ssh_filter_btrbk.1 to ssh_filter_btrbk.1.asciidoc --- ChangeLog | 1 + doc/btrbk.1 | 421 -------------------------- doc/btrbk.1.asciidoc | 363 +++++++++++++++++++++++ doc/btrbk.conf.5 | 508 -------------------------------- doc/btrbk.conf.5.asciidoc | 436 +++++++++++++++++++++++++++ doc/ssh_filter_btrbk.1 | 107 ------- doc/ssh_filter_btrbk.1.asciidoc | 108 +++++++ 7 files changed, 908 insertions(+), 1036 deletions(-) delete mode 100644 doc/btrbk.1 create mode 100644 doc/btrbk.1.asciidoc delete mode 100644 doc/btrbk.conf.5 create mode 100644 doc/btrbk.conf.5.asciidoc delete mode 100644 doc/ssh_filter_btrbk.1 create mode 100644 doc/ssh_filter_btrbk.1.asciidoc diff --git a/ChangeLog b/ChangeLog index 5ea274c..e38a469 100644 --- a/ChangeLog +++ b/ChangeLog @@ -21,6 +21,7 @@ btrbk-current * Remove "duration" column from transaction_log/transaction_syslog. * Resolve ancestors (recursive on parent_uuid chain) when searching for latest common subvolume. + * Generate man pages from asciidoc (remove raw groff sources). * Bugfix: ssh_filter_btrbk: accept mbuffer command (stream_buffer). * Bugfix: print correct (end-)time in transaction_log. * Bugfix: check path when expanding wildcards (close #181). diff --git a/doc/btrbk.1 b/doc/btrbk.1 deleted file mode 100644 index b379545..0000000 --- a/doc/btrbk.1 +++ /dev/null @@ -1,421 +0,0 @@ -.TH "btrbk" "1" "2017-08-21" "btrbk v0.26.0-dev" "" -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.SH NAME -btrbk \- backup tool for btrfs volumes -.SH SYNOPSIS -.nf -\fBbtrbk\fR [\-h|\-\-help] [\-\-version] [\-c|\-\-config ] - [\-n|\-\-dry\-run] [\-p|\-\-preserve] - [\-\-preserve\-snapshots] [\-\-preserve\-backups] - [\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel ] - [\-t|\-\-table] [\-\-format ] - [\-\-progress] [\-\-print\-schedule] - [] -.fi -.SH DESCRIPTION -\fBbtrbk\fR 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. -.PP -Snapshots as well as backup subvolume names are created in form: -.PP -.RS 4 -.[_N] -.RE -.PP -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 snapshot, starting at 1. -.SH OPTIONS -.PP -\-h, \-\-help -.RS 4 -Prints the synopsis and a list of the commands. -.RE -.PP -\-\-version -.RS 4 -Prints the btrbk version. -.RE -.PP -\-n, \-\-dry\-run -.RS 4 -Don't run anything that would alter the filesystem, just show the -snapshots and backup subvolumes that would be created/deleted by the -\fBrun\fR, \fBsnapshot\fR, \fBresume\fR, \fBprune\fR, \fBarchive\fR -and \fBclean\fR commands. Use in conjunction with \fI\-l debug\fR to -see the btrfs commands that would be executed. -.RE -.PP -\-c, \-\-config -.RS 4 -Read the configuration from . -.RE -.PP -\-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 -.PP -\-\-preserve-snapshots -.RS 4 -Preserve all snapshots. Skips deletion of any snapshots, even if -specified in the configuration file. -.RE -.PP -\-\-preserve-backups -.RS 4 -Preserve all backups. Skips deletion of any backups, even if specified -in the configuration file. -.RE -.PP -\-\-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 -.PP -\-v, \-\-verbose -.RS 4 -Verbose output (shortcut for "\-\-loglevel=info"). -.RE -.PP -\-q, \-\-quiet -.RS 4 -Quiet operation. If set, btrbk does not print the summary after -executing the \fBrun\fR, \fBsnapshot\fR, \fBresume\fR, \fBprune\fR, or -\fBarchive\fR commands. -.RE -.PP -\-l, \-\-loglevel -.RS 4 -Set the level of verbosity. Accepted levels are warn, info, debug, -and trace. -.RE -.PP -\-t, \-\-table -.RS 4 -Print output in table format (shortcut for "\-\-format=table"). -.RE -.PP -\-\-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\fR, \fBsnapshot\fR, \fBresume\fR, \fBprune\fR, -\fBarchive\fR and \fBlist\fR commands. Useful for further -exporting/scripting. -.RE -.PP -\-\-progress -.RS 4 -Show progress bar on send-receive operation. -.RE -.PP -\-\-print\-schedule -.RS 4 -Print detailed scheduler information on \fBrun\fR, \fBsnapshot\fR, -\fBresume\fR, \fBprune\fR and \fBarchive\fR commands. Use the -\fI\-\-format\fR command line option to switch between different -output formats. -.RE -.PP -\-\-override = -.RS 4 -Override a configuration option with -. Globally, for ALL contexts. Use with care! -.RE -.PP -\-\-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\fR, \fI\-\-dry\-run\fR). -.RE -.SH COMMANDS -.PP -.B run -[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 \fIFILTER STATEMENT\fR (see below). -.PP -.B Step 0: Read Data -.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 -.PP -.B Step 1: Create Snapshots -.RS 4 -If the checks succeed, btrbk creates snapshots for the source -subvolumes specified in the configuration file, according to the -\fIsnapshot_create\fR option. -.RE -.PP -.B Step 2: Create Backups -.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\fR option is set to \[lq]no\[rq]), a full -(non-incremental) backup is created. -.RE -.PP -.B Step 3: Delete Backups -.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 -.PP -.B Step 4: Delete Snapshots -.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 -.PP -See section RETENTION POLICY in -.BR btrbk.conf (5) -for information on configuring the retention policy. -.PP -Use the \fI\-\-format\fR command line option to switch between -different output formats. -.RE -.PP -.B dryrun -[filter...] -.RS 4 -Don't run any btrfs commands that would alter the filesystem, just -show the snapshots and backup subvolumes that would be created/deleted -by the \fBrun\fR command. Use in conjunction with \fI\-l debug\fR to -see the btrfs commands that would be executed. -.RE -.PP -.B snapshot -[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). -.RE -.PP -.B resume -[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 -.PP -.B prune -[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). -.RE -.PP -.B archive - -.I *experimental* -.RS 4 -Recursively copy all subvolumes created by btrbk from to - directory, optionally rescheduled using -\fIarchive_preserve_*\fR configuration options. Also creates directory -tree on (see bugs below). 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. -.PP -Note that this feature needs a \fBlinux kernel >=4.4\fR to work -correctly! Kernels >=4.1 and <4.4 have a bug when re-sending -subvolumes (the archived subvolumes will have incorrect received_uuid, -see ), -so make sure you run a recent kernel. -.PP -Known bugs: 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. -.RE -.PP -.B stats -[filter...] -.RS 4 -Print statistics of snapshot and backup subvolumes. Optionally -filtered by [filter...] arguments (see \fIFILTER STATEMENTS\fR below). -.RE -.PP -.B list - [filter...] -.RS 4 -Print information defined by in a tabular form. Optionally -filtered by [filter...] arguments (see \fIFILTER STATEMENTS\fR -below). -.PP -Available subcommands: -.TP 11 -.B snapshots -All snapshots (and corresponding backups). -.PD 0 -.TP 11 -.B backups -All backups (and corresponding snapshots). -.TP 11 -.B latest -Most recent common snapshot/backup pair, or most recent snapshot if no -common found. -.TP 11 -.B config -Configured source/snapshot/target relations. -.TP 11 -.B source -Configured source/snapshot relations. -.TP 11 -.B volume -Configured volume sections. -.TP 11 -.B target -Configured targets. -.PD -.PP -Use the \fI\-\-format\fR command line option to switch between -different output formats. -.RE -.PP -.B clean -[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 -.PP -.B usage -[filter...] -.RS 4 -Print filesystem usage information for all source/target volumes, -optionally filtered by [filter...] arguments (see \fIFILTER -STATEMENTS\fR below). Note that the "free" value is an estimate of the -amount of data that can still be written to the file system. -.RE -.PP -.B origin - -.RS 4 -Print the subvolume origin tree: Shows the parent-child relationships -as well as the received-from information. Use the \fI\-\-format\fR -command line option to switch between different output formats. -.RE -.PP -.B diff - -.RS 4 -Print new files since subvolume for subvolume . -.RE -.PP -.B config -print|print\-all -.RS 4 -Prints the parsed configuration file. Use the \fI\-\-format\fR command -line option to switch between different output formats. -.RE -.SH FILTER STATEMENTS -Filter arguments are accepted in form: -.PP -[hostname:] -.RS 4 -Matches all subvolumes and targets of a \fIvolume\fR configuration -section. -.RE -.PP -[hostname:]/ -.RS 4 -Matches the specified subvolume and all targets of a \fIsubvolume\fR -configuration section. -.RE -.PP -[hostname:] -.RS 4 -Matches all targets of a \fItarget\fR configuration section. -.RE -.PP -[hostname:]/ -.RS 4 -Matches a single target of a \fItarget\fR section within a -\fIsubvolume\fR section with given . -.RE -.PP - -.RS 4 -Matches the \fIgroup\fR configuration option of a \fIvolume\fR, -\fIsubvolume\fR or \fItarget\fR section. -.RE -.PP -For convenience, [hostname:] can be specified as either "hostname:" or -"ssh://hostname/". -.SH FILES -.PP -/etc/btrbk.conf -.br -/etc/btrbk/btrbk.conf -.RS 4 -Default configuration file. The file format and configuration options -are described in -.BR btrbk.conf (5). -.RE -.PD -.SH EXIT STATUS -\fBbtrbk\fR returns the following error codes: -.IP "0" 4 -No problems occurred. -.IP "1" 4 -Generic error code. -.IP "2" 4 -Parse error: when parsing command-line options or configuration file. -.IP "3" 4 -Lockfile error: if lockfile is present on startup. -.IP "10" 4 -Backup abort: At least one backup task aborted. -.IP "255" 4 -Script error. -.SH AVAILABILITY -Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR -for further details. -.SH SEE ALSO -.BR btrbk.conf (5), -.BR btrfs (1) -.PP -For more information about btrfs and incremental backups, see the web -site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup -.SH AUTHOR -Axel Burri diff --git a/doc/btrbk.1.asciidoc b/doc/btrbk.1.asciidoc new file mode 100644 index 0000000..7a29229 --- /dev/null +++ b/doc/btrbk.1.asciidoc @@ -0,0 +1,363 @@ +btrbk(1) +======== +:date: 2017-10-09 +:revision: 0.26.0-dev +:man manual: Btrbk Manual +:man source: Btrbk + + +NAME +---- + +btrbk - backup tool for btrfs volumes + + +SYNOPSIS +-------- + +[literal] +btrbk [-h|--help] [--version] [-c|--config ] + [-n|--dry-run] [-p|--preserve] + [--preserve-snapshots] [--preserve-backups] + [-v|--verbose] [-q|--quiet] [-l|--loglevel ] + [-t|--table] [--format ] + [--progress] [--print-schedule] + [] + + +DESCRIPTION +----------- + +*btrbk* 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. + +Snapshots as well as backup subvolume names are created in form: + + .[_N] + +Where '' is identical to the source subvolume name, +unless the configuration option 'snapshot_name' is set. The + is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the +'timestamp_format' 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. + + +OPTIONS +------- + +-h, --help:: + Prints the synopsis and a list of the commands. + +--version:: + Prints the btrbk version. + +-n, --dry-run:: + Don't run anything that would alter the filesystem, just show the + snapshots and backup subvolumes that would be created/deleted by + the *run*, *snapshot*, *resume*, *prune*, *archive* and *clean* + commands. Use in conjunction with '-l debug' to see the btrfs + commands that would be executed. + +-c, --config :: + Read the configuration from . + +-p, --preserve:: + 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"). + +--preserve-snapshots:: + Preserve all snapshots. Skips deletion of any snapshots, even if + specified in the configuration file. + +--preserve-backups:: + Preserve all backups. Skips deletion of any backups, even if + specified in the configuration file. + +--wipe:: + 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). + +-v, --verbose:: + Verbose output (shortcut for "--loglevel=info"). + +-q, --quiet:: + Quiet operation. If set, btrbk does not print the summary after + executing the *run*, *snapshot*, *resume*, *prune*, or *archive* + commands. + +-l, --loglevel :: + Set the level of verbosity. Accepted levels are warn, info, debug, + and trace. + +-t, --table:: + Print output in table format (shortcut for "--format=table"). + +--format table|long|raw:: + Print output in specified format. If set to "raw", prints + space-separated key="value" pairs (machine readable). Affects + output format for *run*, *snapshot*, *resume*, *prune*, *archive* + and *list* commands. Useful for further exporting/scripting. + +--progress:: + Show progress bar on send-receive operation. + +--print-schedule:: + Print detailed scheduler information on *run*, *snapshot*, + *resume*, *prune* and *archive* commands. Use the '--format' + command line option to switch between different output formats. + +--override =:: + Override a configuration option with + . Globally, for ALL contexts. Use with care! + +--lockfile :: + 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 ('-n', '--dry-run'). + + +COMMANDS +-------- + +=== Actions + +The following commands are used to create snapshots and/or +backups. All actions can operate in dry-run mode ('-n', +'--dry-run'). + +*run* [filter...]:: + 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,FILTER STATEMENTS>> below). ++ +*Step 0: Read Data*;; + Read information from the source and target btrfs filesystems in + order to perform sanity checks and identify parent/child and + received-from relationships. ++ +*Step 1: Create Snapshots*;; + If the checks succeed, btrbk creates snapshots for the source + subvolumes specified in the configuration file, according to the + 'snapshot_create' option. ++ +*Step 2: Create Backups*;; + 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 'incremental' option is set to ``no''), a full + (non-incremental) backup is created. ++ +*Step 3: Delete Backups*;; + 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. ++ +*Step 4: Delete Snapshots*;; + 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. ++ +See section RETENTION POLICY in `btrbk.conf`(5) +for information on configuring the retention policy. + +Use the '--format' command line option to switch between +different output formats. + +*dryrun* [filter...]:: + Don't run any btrfs commands that would alter the filesystem, just + show the snapshots and backup subvolumes that would be + created/deleted by the *run* command. Use in conjunction with '-l + debug' to see the btrfs commands that would be executed. + +*snapshot* [filter...]:: + 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). + +*resume* [filter...]:: + 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). + +*prune* [filter...]:: + 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). + +*archive* _*experimental*_:: + Recursively copy all subvolumes created by btrbk from to + directory, optionally rescheduled using + 'archive_preserve_*' configuration options. Also creates directory + tree on (see bugs below). 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. ++ +Note that this feature needs a *linux kernel >=4.4* to work correctly! +Kernels >=4.1 and <4.4 have a bug when re-sending subvolumes (the +archived subvolumes will have incorrect received_uuid, see +), so +make sure you run a recent kernel. ++ +Known bugs: 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. + + +=== Informative Commands + +The following commands are informative only, and will not alter the +file system. + +*stats* [filter...]:: + Print statistics of snapshot and backup subvolumes. Optionally + filtered by [filter...] arguments (see <<_filter_statements,FILTER + STATEMENTS>> below). + +*list* [filter...]:: + Print information defined by in a tabular + form. Optionally filtered by [filter...] arguments (see + <<_filter_statements,FILTER STATEMENTS>> below). ++ +Available subcommands: ++ +-- +[horizontal] +*snapshots*;; All snapshots (and corresponding backups). +*backups*;; All backups (and corresponding snapshots). +*latest*;; Most recent common snapshot/backup pair, or most recent + snapshot if no common found. +*config*;; Configured source/snapshot/target relations. +*source*;; Configured source/snapshot relations. +*volume*;; Configured volume sections. +*target*;; Configured targets. +-- ++ +Use the '--format' command line option to switch between +different output formats. + + +*clean* [filter...]:: + 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. + +*usage* [filter...]:: + Print filesystem usage information for all source/target volumes, + optionally filtered by [filter...] arguments (see + <<_filter_statements,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. + +*origin* :: + Print the subvolume origin tree: Shows the parent-child + relationships as well as the received-from information. Use the + '--format' command line option to switch between different output + formats. + +*diff* :: + Print new files since subvolume for subvolume . + +*config* print|print-all:: + Prints the parsed configuration file. Use the '--format' command + line option to switch between different output formats. + + +FILTER STATEMENTS +----------------- + +Filter arguments are accepted in form: + +[hostname:]:: + Matches all subvolumes and targets of a 'volume' configuration + section. + +[hostname:]/:: + Matches the specified subvolume and all targets of a 'subvolume' + configuration section. + +[hostname:]:: + Matches all targets of a 'target' configuration section. + +[hostname:]/:: + Matches a single target of a 'target' section within a 'subvolume' + section with given . + +:: +Matches the 'group' configuration option of a 'volume', +'subvolume' or 'target' section. + +For convenience, [hostname:] can be specified as either "hostname:" or +"ssh://hostname/". + + +FILES +----- + ++/etc/btrbk.conf+:: ++/etc/btrbk/btrbk.conf+:: + Default configuration file. The file format and configuration + options are described in *btrbk.conf*(5). + + +EXIT STATUS +----------- + +*btrbk* returns the following error codes: + +[horizontal] +0:: No problems occurred. +1:: Generic error code. +2:: Parse error: when parsing command-line options or configuration + file. +3:: Lockfile error: if lockfile is present on startup. +10:: Backup abort: At least one backup task aborted. +255:: Script error. + + +AVAILABILITY +------------ + +Please refer to the btrbk project page ** for +further details. + + +SEE ALSO +-------- + +*btrbk.conf*(5), +*btrfs*(8) + +For more information about btrfs and incremental backups, see the web +site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup + + +AUTHOR +------ + +Axel Burri diff --git a/doc/btrbk.conf.5 b/doc/btrbk.conf.5 deleted file mode 100644 index 9570b06..0000000 --- a/doc/btrbk.conf.5 +++ /dev/null @@ -1,508 +0,0 @@ -.TH "btrbk.conf" "5" "2017-09-28" "btrbk v0.26.0-dev" "" -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.SH NAME -btrbk.conf \- btrbk configuration file -.SH SYNOPSIS -.B /etc/btrbk.conf -.br -.B /etc/btrbk/btrbk.conf -.SH DESCRIPTION -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. -.PP -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 -Blank lines are ignored. A hash character (#) starts a comment -extending until end of line. -.SH SECTIONS -.PP -\fBvolume\fR | -.RS 4 -Directory of a btrfs volume containing the source subvolume(s) to be -backed up. \fI\fR must be an absolute path and -point to a btrfs volume (or subvolume). Usually the mount point of a -btrfs filesystem mounted with the \fIsubvolid=0\fR option. -.RE -.PP -\fBsubvolume\fR -.RS 4 -Subvolume to be backed up, relative to the \fI\fR -specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR -sections are allowed within \fIvolume\fR sections. Accepts wildcard -character "*". -.RE -.PP -\fBtarget\fR | -.RS 4 -Target type and directory where the backup subvolumes are to be -created. See the TARGET TYPES section for supported -\fI\fR. Multiple \fItarget\fR sections are allowed within -\fIsubvolume\fR sections. A \fItarget\fR section defined in the global -context or in a \fIvolume\fR section is propagated (multiplied) to all -underlying \fIsubvolume\fR sections, unless a target with the same -declaration already exists (hint: run "btrbk config print" to see the -resulting configuration). -.RE -.PP -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 -.nf -ssh://host.xz/path/to/volume -.fi -.RE -.PP -If a \fI\fR is specified, all access to the filesystem is -performed via ssh, using the "ssh_" options described below. For -convenience, "ssh:///" can also be specified as -":". -.PP -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 OPTIONS -.PP -\fBtransaction_log\fR |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 -.PP -\fBtransaction_syslog\fR |no -.RS 4 -If set, all transactions (as described in \fItransaction_log\fR above) -are logged to syslog. The program name used in the messages is -"btrbk". Accepted parameters for \fI\fR: user, mail, daemon, -auth, lpr, news, cron, authpriv, local0..local7. -.RE -.PP -\fBtimestamp_format\fR short|long|long\-iso -.RS 4 -Timestamp format used as postfix for new snapshot subvolume -names. Defaults to \[lq]short\[rq]. -.PP -.IP \fBshort\fR 10 -YYYYMMDD[_N] (e.g. "20150825", "20150825_1") -.IP \fBlong\fR 10 -YYYYMMDDhhmm[_N] (e.g. "20150825T1531") -.IP \fBlong\-iso\fR 10 -YYYYMMDDhhmmss\[t+-]hhmm[_N] (e.g. "20150825T153123+0200") -.PP -Note that a postfix "_N" is appended to the timestamp if a snapshot or -backup already exists with the timestamp of current date/time. -.PP -Use \[lq]long\-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). -.PP -Note that using \[lq]long\-iso\[rq] has implications on the -scheduling, see RETENTION POLICY (caveats) below. -.RE -.PP -\fBsnapshot_dir\fR -.RS 4 -Directory in which the btrfs snapshots are created, relative to -\fI\fR of the \fIvolume\fR section. Note that btrbk -does not autmatically create this directory, and the snapshot creation -will fail if it is not present. -.RE -.PP -\fBsnapshot_name\fR -.RS 4 -Base name of the created snapshot (and backup). This option is only -valid in the \fIsubvolume\fR section. Defaults to -\fI\fR. -.RE -.PP -\fBsnapshot_create\fR always|onchange|ondemand|no -.RS 4 -If set to \[lq]always\[rq], snapshots are always created. If set to -\[lq]onchange\[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 -\[lq]ondemand\[rq], snapshots are only created if the 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 \[lq]no\[rq], the snapshots are never created -(useful if another instance of btrbk is taking care of snapshot -creation). Defaults to \[lq]always\[rq]. -.RE -.PP -\fBincremental\fR yes|no|strict -.RS 4 -If set, incremental backups are created. If set to \[lq]strict\[rq], -non-incremental (initial) backups are never created. Defaults to -\[lq]yes\[rq]. -.RE -.PP -\fBsnapshot_preserve\fR no| -.RS 4 -Set retention policy for snapshots (see RETENTION POLICY below). If -set to \[lq]no\[rq], preserve snapshots according to -\fIsnapshot_preserve_min\fR only. Defaults to \[lq]no\[rq]. -.RE -.PP -\fBsnapshot_preserve_min\fR 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 \[lq]all\[rq], preserve all snapshots forever. If set -to \[lq]latest\[rq], preserve latest snapshot. Defaults to -\[lq]all\[rq]. -.RE -.PP -\fBtarget_preserve\fR no| -.RS 4 -Set retention policy for backups (see RETENTION POLICY below). If set -to \[lq]no\[rq], preserve backups according to -\fItarget_preserve_min\fR only. Defaults to \[lq]no\[rq]. -.RE -.PP -\fBtarget_preserve_min\fR 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 \[lq]all\[rq], preserve all backups forever. If set to -\[lq]latest\[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 \[lq]no\[rq], only the backups following the -\fItarget_preserve\fR policy are created. Defaults to \[lq]all\[rq]. -.RE -.PP -\fBarchive_preserve\fR no| -.PD 0 -.PP -\fBarchive_preserve_min\fR all|latest|no|{h,d,w,m,y} -.PD -.RS 4 -Set retention policy for archives ("btrbk archive" command), with same -semantics as \fItarget_preserve\fR, \fItarget_preserve_min\fR. -.RE -.PP -\fBpreserve_day_of_week\fR monday|tuesday|...|sunday -.RS 4 -Defines on what day a backup/snapshot is considered as a weekly -backup. Defaults to \[lq]sunday\[rq]. -.RE -.PP -\fBgroup\fR [,]... -.RS 4 -Add the current section (volume, subvolume or target) to a -user-defined group, which can be used as filter for several btrbk -commands. -.RE -.PP -\fBssh_identity\fR -.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 -.PP -\fBssh_user\fR -.RS 4 -Remote username for ssh. Defaults to \[lq]root\[rq]. Note that you -will have to make sure that the remote user is able to run -"/sbin/btrfs" (which needs root privileges). -.RE -.PP -\fBssh_port\fR -.RS 4 -Port to connect to on the remote host. Defaults to \[lq]default\[rq] -(the port specified in \fIssh_config\fR, which defaults to 22). -.RE -.PP -\fBssh_compression\fR yes|no -.RS 4 -Enables or disables the compression of ssh connections. Defaults to -\[lq]no\[rq]. -.RE -.PP -\fBssh_cipher_spec\fR -.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 -\[lq]default\[rq] (the ciphers specified in \fIssh_config\fR). -.RE -.PP -\fBstream_compress\fR |no -.RS 4 -Compress the btrfs send stream before transferring it from/to remote -locations. Defaults to \[lq]no\[rq]. If enabled, make sure that - is available on the source and target -hosts. Supported \fI\fR: gzip, pigz, bzip2, pbzip2, -xz, lzo, lz4. -.RE -.PP -\fBstream_compress_level\fR default| -.RS 4 -Compression level for the specified . Refer to the -related man-page for details (usually [1..9], where 1 means fastest -compression). Defaults to \[lq]default\[rq] (the default compression -level of ). -.RE -.PP -\fBstream_compress_threads\fR default| -.RS 4 -Number of threads to use for . Only supported for -"pigz", "pbzip2" and recent versions of "xz". -.RE -.PP -\fBstream_buffer\fR |no \fI*experimental*\fR -.RS 4 -Add a buffer to the btrfs send stream (in front of "btrfs receive"), -with a maximum size of \fI\fR. 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\fR to denote kilobytes (*1024), megabytes, gigabytes, or -a percentage of total physical memory. Defaults to \[lq]no\[rq]. If -enabled, make sure that the "mbuffer" command is available on the -target host. -.RE -.PP -\fBrate_limit\fR |no -.RS 4 -Limit the transfer to a maximum of \fI\fR bytes per second. A -suffix of "k", "m", "g", or "t" can be added to denote kilobytes -(*1024), megabytes, and so on. Defaults to \[lq]no\[rq]. If enabled -for remote sources, make sure that the "pv" command is available on -the source host. -.RE -.PP -\fBlockfile\fR |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\fR, -\fI\-\-dry\-run\fR). See also \fI\-\-lockfile\fR command-line option. -.RE -.PP -\fBbtrfs_commit_delete\fR 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 \[lq]no\[rq]. -.RE -.PP -\fBbackend\fR btrfs-progs|btrfs-progs-btrbk|btrfs-progs-sudo -.RS 4 -Backend filesystem utilities to be used for btrfs specific operations. The -default \[lq]btrfs-progs\[rq] simply executes btrfs(8) commands groups -(e.g. "btrfs subvolume show"). -.IP \[bu] 2 -If set -to \[lq]btrfs-progs-btrbk\[rq], specific btrfs(8) commands groups -needs to be 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 -. -.IP \[bu] 2 -If set to \[lq]btrfs-progs-sudo\[rq], btrfs commands are prefixed with -"sudo -n" (e.g. "sudo -n btrfs subvolume show" instead of "btrfs -subvolume show"). Make sure to have apropriate (root) permissions for -"btrfs" command groups in /etc/sudoers. -.PP -For convenience, it is also possible to set \fIbackend_local\fR or -\fIbackend_remote\fR options, which will override the backend only for -local or remote sources/targets (e.g. "backend_remote -btrfs-progs-btrbk"). -.RE -.PP -\fBsnapshot_qgroup_destroy\fR yes|no \fI*experimental*\fR -.PD 0 -.PP -\fBtarget_qgroup_destroy\fR yes|no \fI*experimental*\fR -.PP -\fBarchive_qgroup_destroy\fR yes|no \fI*experimental*\fR -.PD -.RS 4 -Whenever a subvolume is deleted, also destroy corresponding default -qgroup "0/". Only useful if you have enabled btrfs quota -support. See also: -.RE -.SH RETENTION POLICY -btrbk uses separate retention policies for snapshots and backups, -which are defined by the \fIsnapshot_preserve_min\fR, -\fIsnapshot_preserve\fR, \fItarget_preserve_min\fR, -\fItarget_preserve\fR, and the \fIpreserve_day_of_week\fR -configuration options. -.PP -Within this section, any statement about "backups" is always valid for -backups as well as snapshots, referring to \fItarget_preserve\fR or -\fIsnapshot_preserve\fR respectively. -.PP -The format for \fI\fR is: -.PP -.RS 4 -[h] [d] [w] [m] [y] -.RE -.PP -With the following semantics: -.PP -.B hourly -.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\fR to \[lq]long\[rq] or \[lq]long\-iso\[rq], or -the scheduler will interpret the time as "00:00" (midnight). -.RE -.PP -.B daily -.RS 4 -Defines how many days back daily backups should be preserved. The -first backup of a day is considered a daily backup. -.RE -.PP -.B weekly -.RS 4 -Defines how many weeks back weekly backups should be preserved. The -first daily backup created at \fIpreserve_day_of_week\fR (or the first -backup in this week if none was made on the exact day) is considered -as a weekly backup. -.RE -.PP -.B monthly -.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 -.PP -.B yearly -.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 -.PP -Use an asterisk for \[lq]all\[rq] (e.g. "target_preserve 60d *m" -states: "preserve daily backups for 60 days back, and all monthly -backups"). -.PP -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. -.PP -Caveats: -.IP \[bu] 2 -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". -.IP \[bu] 2 -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)). -.SH TARGET TYPES -.PP -\fBsend\-receive\fR -.RS 4 -Backup to a btrfs filesystem, using "btrfs send/receive". This is the -recommended (standard) target type. The \fI\fR 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 -.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 -Note that the target preserve mechanism is currently disabled for -incremental raw backups (btrbk does not delete any incremental raw -files)! -.PP -Additional options for raw targets: -.PP -.RS 4 -raw_target_compress gzip|pigz|bzip2|pbzip2|xz|lzo|lz4|no -.PD 0 -.PP -raw_target_compress_level default| -.PP -raw_target_compress_threads default| -.PP -raw_target_split |no -.PP -raw_target_block_size (defaults to 128K) -.PP -raw_target_encrypt gpg|openssl_enc|no -.RE -.PD -.PP -Additional options for "raw_target_encrypt gpg": -.PP -.RS 4 -gpg_keyring -.PD 0 -.PP -gpg_recipient -.RE -.PD -.PP -Additional options for "raw_target_encrypt openssl_enc" (\fIvery -experimental\fR): -.PP -.RS 4 -openssl_ciphername (defaults to "aes-256-cbc") -.PD 0 -.PP -openssl_iv_size |no (depends on selected cipher) -.PP -openssl_keyfile |no -.PP -kdf_backend |no -.PP -kdf_keysize (defaults to "32") -.PP -kdf_keygen once|each (defaults to "once") -.RE -.PD -.PP -Raw backups consist of two files: the main data file containing the -btrfs send stream, and a sidecar file ".info" containing metadata: -.RS 4 -.PP -.[_N].btrfs[.gz|.bz2|.xz][.gpg] -.[_N].btrfs[.gz|.bz2|.xz][.gpg].info -.RE -.PP -For \fIincremental\fR backups ("incremental yes"), please note that: -.IP 1. 4 -As soon as a single \fIincremental\fR 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. -.IP 2. 4 -There is currently no support for 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 AVAILABILITY -Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR -for further details. -.SH SEE ALSO -.BR btrbk (1) -.SH AUTHOR -Axel Burri diff --git a/doc/btrbk.conf.5.asciidoc b/doc/btrbk.conf.5.asciidoc new file mode 100644 index 0000000..960fa4f --- /dev/null +++ b/doc/btrbk.conf.5.asciidoc @@ -0,0 +1,436 @@ +btrbk.conf(5) +============= +:date: 2017-10-09 +:revision: 0.26.0-dev +:man manual: Btrbk Manual +:man source: Btrbk + + +NAME +---- + +btrbk.conf - btrbk configuration file + + +SYNOPSIS +-------- + +[literal] +/etc/btrbk.conf +/etc/btrbk/btrbk.conf + + +DESCRIPTION +----------- + +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. + +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. + +Blank lines are ignored. A hash character (#) starts a comment +extending until end of line. + + +SECTIONS +-------- + +*volume* |:: + Directory of a btrfs volume containing the source subvolume(s) + to be backed up. '' must be an absolute path + and point to a btrfs volume (or subvolume). Usually the mount + point of a btrfs filesystem mounted with the 'subvolid=0' + option. + +*subvolume* :: + Subvolume to be backed up, relative to the '' + specified in the 'volume' section. Multiple 'subvolume' sections + are allowed within 'volume' sections. Accepts wildcard character + "*". + +*target* |:: + Target type and directory where the backup subvolumes are to be + created. See the <<_target_types,TARGET TYPES>> section for + supported ''. Multiple 'target' sections are allowed within + 'subvolume' sections. A 'target' section defined in the global + context or in a 'volume' section is propagated (multiplied) to all + underlying 'subvolume' sections, unless a target with the same + declaration already exists (hint: run "btrbk config print" to see + the resulting configuration). + +For the 'volume' and 'target' sections, you can specify a ssh-url +instead of a local directory. The syntax for '' is: + + ssh://host.xz/path/to/volume + +If a '' is specified, all access to the filesystem is performed +via ssh, using the "ssh_" options described below. For convenience, +"+ssh:///+" can also be specified as +"+:+". + +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. + + +OPTIONS +------- + +*transaction_log* |no:: + 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". + +*transaction_syslog* |no:: + If set, all transactions (as described in 'transaction_log' above) + are logged to syslog. The program name used in the messages is + "btrbk". Accepted parameters for '': user, mail, + daemon, auth, lpr, news, cron, authpriv, local0..local7. + +*timestamp_format* short|long|long-iso:: + Timestamp format used as postfix for new snapshot subvolume + names. Defaults to ``short''. ++ +-- +*short*;; `YYYYMMDD[_N]` (e.g. "20150825", "20150825_1") +*long*;; `YYYYMMDDhhmm[_N]` (e.g. "20150825T1531") +*long-iso*;; `YYYYMMDDhhmmss±hhmm[_N]` (e.g. "20150825T153123+0200") +-- ++ +Note that a postfix "_N" is appended to the timestamp if a snapshot or +backup already exists with the timestamp of current date/time. ++ +Use ``long-iso'' 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). ++ +Note that using ``long-iso'' has implications on the scheduling, see +<<_retention_policy,RETENTION POLICY>> (caveats) below. + +*snapshot_dir* :: + Directory in which the btrfs snapshots are created, relative to + '' of the 'volume' section. Note that btrbk does + not autmatically create this directory, and the snapshot creation + will fail if it is not present. + +*snapshot_name* :: + Base name of the created snapshot (and backup). This option is + only valid in the 'subvolume' section. Defaults to + ''. + +*snapshot_create* always|onchange|ondemand|no:: + If set to ``always'', snapshots are always created. If set to + ``onchange'', 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 + ``ondemand'', snapshots are only created if the 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 ``no'', the snapshots are never created + (useful if another instance of btrbk is taking care of snapshot + creation). Defaults to ``always''. + +*incremental* yes|no|strict:: + If set, incremental backups are created. If set to ``strict'', + non-incremental (initial) backups are never created. Defaults to + ``yes''. + +*snapshot_preserve* no|:: + Set retention policy for snapshots (see + <<_retention_policy,RETENTION POLICY>> below). If set to ``no'', + preserve snapshots according to 'snapshot_preserve_min' + only. Defaults to ``no''. + +*snapshot_preserve_min* all|latest|{h,d,w,m,y}:: + 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 ``all'', preserve all snapshots forever. If + set to ``latest'', preserve latest snapshot. Defaults to ``all''. + +*target_preserve* no|:: + Set retention policy for backups (see + <<_retention_policy,RETENTION POLICY>> below). If set to ``no'', + preserve backups according to 'target_preserve_min' only. Defaults + to ``no''. + +*target_preserve_min* all|latest|no|{h,d,w,m,y}:: + 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 ``all'', preserve all backups forever. If set to + ``latest'', always preserve the latest backup (useful in + conjunction with "target_preserve no", if you want to keep the + latest backup only). If set to ``no'', only the backups following + the 'target_preserve' policy are created. Defaults to ``all''. + +*archive_preserve* no|:: {blank} +*archive_preserve_min* all|latest|no|{h,d,w,m,y}:: + Set retention policy for archives ("btrbk archive" command), with + same semantics as 'target_preserve', 'target_preserve_min'. + +*preserve_day_of_week* monday|tuesday|...|sunday":: + Defines on what day a backup/snapshot is considered as a weekly + backup. Defaults to ``sunday''. + +*group* [,]...:: + Add the current section (volume, subvolume or target) to a + user-defined group, which can be used as filter for several btrbk + commands. + +*ssh_identity* :: + 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. + +*ssh_user* :: + Remote username for ssh. Defaults to ``root''. Note that you will + have to make sure that the remote user is able to run + "/sbin/btrfs" (which needs root privileges). + +*ssh_port* :: + Port to connect to on the remote host. Defaults to ``default'' + (the port specified in 'ssh_config', which defaults to 22). + +*ssh_compression* yes|no:: + Enables or disables the compression of ssh connections. Defaults + to ``no''. + +*ssh_cipher_spec* :: + 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 ``default'' (the ciphers specified in 'ssh_config'). + +*stream_compress* |no:: + Compress the btrfs send stream before transferring it from/to + remote locations. Defaults to ``no''. If enabled, make sure that + is available on the source and target + hosts. Supported '': gzip, pigz, bzip2, pbzip2, + xz, lzo, lz4. + +*stream_compress_level* default|:: + Compression level for the specified . Refer to + the related man-page for details (usually [1..9], where 1 means + fastest compression). Defaults to ``default'' (the default + compression level of ). + +*stream_compress_threads* default|:: + Number of threads to use for . Only supported + for "pigz", "pbzip2" and recent versions of "xz". + +*stream_buffer* |no _*experimental*_:: + Add a buffer to the btrfs send stream (in front of "btrfs + receive"), with a maximum size of ''. 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 '' to denote kilobytes (*1024), + megabytes, gigabytes, or a percentage of total physical + memory. Defaults to ``no''. If enabled, make sure that the + "mbuffer" command is available on the target host. + +*rate_limit* |no:: + Limit the transfer to a maximum of '' bytes per second. A + suffix of "k", "m", "g", or "t" can be added to denote kilobytes + (*1024), megabytes, and so on. Defaults to ``no''. If enabled for + remote sources, make sure that the "pv" command is available on + the source host. + +*lockfile* |no:: + 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 ('-n', + '--dry-run'). See also '--lockfile' command-line option. + +*btrfs_commit_delete* after|each|no:: + If set, make sure the deletion of snapshot and backup subvolumes + are committed to disk when btrbk terminates. Defaults to ``no''. + +*backend* btrfs-progs|btrfs-progs-btrbk|btrfs-progs-sudo:: + Backend filesystem utilities to be used for btrfs specific + operations. The default ``btrfs-progs'' simply executes btrfs(8) + commands groups (e.g. "btrfs subvolume show"). ++ +-- +* If set to ``btrfs-progs-btrbk'', specific btrfs(8) commands groups + needs to be 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 + . +* If set to ``btrfs-progs-sudo'', btrfs commands are prefixed with + "sudo -n" (e.g. "sudo -n btrfs subvolume show" instead of "btrfs + subvolume show"). Make sure to have apropriate (root) permissions + for "btrfs" command groups in /etc/sudoers. +-- ++ +For convenience, it is also possible to set 'backend_local' or +'backend_remote' options, which will override the backend only for +local or remote sources/targets (e.g. "backend_remote +btrfs-progs-btrbk"). + +*snapshot_qgroup_destroy* yes|no _*experimental*_:: {blank} +*target_qgroup_destroy* yes|no _*experimental*_:: {blank} +*archive_qgroup_destroy* yes|no _*experimental*_:: + Whenever a subvolume is deleted, also destroy corresponding + default qgroup "0/". Only useful if you have enabled + btrfs quota support. See also: + + + +RETENTION POLICY +---------------- + +btrbk uses separate retention policies for snapshots and backups, +which are defined by the 'snapshot_preserve_min', 'snapshot_preserve', +'target_preserve_min', 'target_preserve', and the +'preserve_day_of_week' configuration options. + +Within this section, any statement about "backups" is always valid for +backups as well as snapshots, referring to 'target_preserve' or +'snapshot_preserve' respectively. + +The format for '' is: + + [h] [d] [w] [m] [y] + +With the following semantics: + +*hourly*:: + 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 'timestamp_format' to ``long'' or ``long-iso'', or the + scheduler will interpret the time as "00:00" (midnight). + +*daily*:: + Defines how many days back daily backups should be preserved. The + first backup of a day is considered a daily backup. + +*weekly*:: + Defines how many weeks back weekly backups should be + preserved. The first daily backup created at + 'preserve_day_of_week' (or the first backup in this week if none + was made on the exact day) is considered as a weekly backup. + +*monthly*:: + Defines how many months back monthly backups should be + preserved. Every first weekly backup in a month is considered a + monthly backup. + +*yearly*:: + Defines for how many years back yearly backups should be + preserved. Every first monthly backup in a year is considered a + yearly backup. + +Use an asterisk for ``all'' (e.g. "target_preserve 60d *m" +states: "preserve daily backups for 60 days back, and all monthly +backups"). + +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. + +Caveats: + +* 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". + +* 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)). + + +TARGET TYPES +------------ + +*send-receive*:: + Backup to a btrfs filesystem, using "btrfs send/receive". This is + the recommended (standard) target type. The '' + 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). + +*raw* _*experimental*_:: + Backup to a raw (filesystem independent) file from the output of + btrfs-send(8), with optional compression and encryption. ++ +-- +Note that the target preserve mechanism is currently disabled for +incremental raw backups (btrbk does not delete any incremental raw +files)! + +Additional options for raw targets: + +*raw_target_compress* gzip|pigz|bzip2|pbzip2|xz|lzo|lz4|no:: {blank} +*raw_target_compress_level* default|:: {blank} +*raw_target_compress_threads* default|:: {blank} +*raw_target_split* |no:: {blank} +*raw_target_block_size* (defaults to 128K):: {blank} +*raw_target_encrypt* gpg|openssl_enc|no:: {blank} + +Additional options for "raw_target_encrypt gpg": + +*gpg_keyring* :: {blank} +*gpg_recipient* :: {blank} + +Additional options for "raw_target_encrypt openssl_enc" ('very +experimental'): + +*openssl_ciphername* (defaults to ``aes-256-cbc''):: {blank} +*openssl_iv_size* |no (depends on selected cipher):: {blank} +*openssl_keyfile* |no:: {blank} +*kdf_backend* |no:: {blank} +*kdf_keysize* (defaults to ``32''):: {blank} +*kdf_keygen* once|each (defaults to ``once''):: {blank} + +Raw backups consist of two files: the main data file containing the +btrfs send stream, and a sidecar file ".info" containing metadata: + + .[_N].btrfs[.gz|.bz2|.xz][.gpg] + .[_N].btrfs[.gz|.bz2|.xz][.gpg].info + +For 'incremental' backups ("incremental yes"), please note that: + +* As soon as a single 'incremental' 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. + +* There is currently no support for rotation of incremental backups: + if 'incremental' is set, a full backup must be triggered manually + from time to time in order to be able to delete old backups. +-- + + +AVAILABILITY +------------ + +Please refer to the btrbk project page ** +for further details. + + +SEE ALSO +-------- + +*btrbk*(1) + + +AUTHOR +------ +Axel Burri diff --git a/doc/ssh_filter_btrbk.1 b/doc/ssh_filter_btrbk.1 deleted file mode 100644 index 0cb3e9d..0000000 --- a/doc/ssh_filter_btrbk.1 +++ /dev/null @@ -1,107 +0,0 @@ -.TH "ssh_filter_btrbk" "1" "2017-08-21" "btrbk v0.26.0-dev" "" -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.SH NAME -ssh_filter_btrbk.sh \- ssh command filter script for btrbk -.SH SYNOPSIS -.nf -\fBssh_filter_btrbk.sh\fR [\-s|\-\-source] [\-t|\-\-target] [\-d|\-\-delete] [\-i|\-\-info] - [\-p|\-\-restrict\-path ] [\-l|\-\-log] [\-\-sudo] -.fi -.SH DESCRIPTION -\fBssh_filter_btrbk.sh\fR restricts SSH commands to \fIbtrfs\fR -commands used by \fIbtrbk\fR. It examines the SSH_ORIGINAL_COMMAND -environment variable (set by sshd) and executes it only if it matches -commands used by \fIbtrbk\fR. The accepted commands are specified by -the "\-\-source", "\-\-target", "\-\-delete" and "\-\-info" options. -.PP -Note that the following btrfs commands are always allowed: "btrfs -subvolume show", "btrfs subvolume list". -.PP -Note that commands for stream compression (pipes through gzip, pigz, -bzip2, pbzip2, xz, lzop, lz4), rate limiting (pipes through "pv -L"), -and stream buffer (pipes through "mbuffer") are always allowed. -.PP -Example line in /root/.ssh/authorized_keys on a backup target host: -.PP -.RS 4 -.nf -command="ssh_filter_btrbk.sh \-\-target \-\-delete \-\-restrict\-path /mnt/btr_backup" ssh\-rsa AAAAB3NzaC1...hwumXFRQBL btrbk@mydomain.com -.fi -.RE -.SH OPTIONS -.PP -\-s, \-\-source -.RS 4 -Allow commands for backup source: "btrfs subvolume snapshot", "btrfs -send". Equivalent to "\-\-snapshot \-\-send". -.RE -.PP -\-t, \-\-target -.RS 4 -Allow commands for backup target: "btrfs receive", "realpath" and "cat -/proc/self/mounts". -.RE -.PP -\-d, \-\-delete -.RS 4 -Allow commands for subvolume deletion: "btrfs subvolume delete". This -is used for backup source if \fIsnapshot_preserve_daily\fR is not set -to \[lq]all\[rq], and for backup targets if -\fItarget_preserve_daily\fR is not set to \[lq]all\[rq]. -.RE -.PP -\-c, \-\-compress -.RS 4 -Allow commands for stream compression (pipes through gzip, pigz, -bzip2, pbzip2, xz, lzo, lz4). Needed if \fIstream_compress\fR is set. -.RE -.PP -\-i, \-\-info -.RS 4 -Allow informative commands: "btrfs subvolume find\-new", "btrfs -filesystem usage". This is used by btrbk \fIinfo\fR and \fIdiff\fR -commands. -.RE -.PP -\-\-snapshot -.RS 4 -Allow btrfs snapshot command: "btrfs subvolume snapshot". -.RE -.PP -\-\-send -.RS 4 -Allow btrfs send command: "btrfs send". -.RE -.PP -\-\-receive -.RS 4 -Allow btrfs receive command: "btrfs receive". -.RE -.PP -\-p, \-\-restrict\-path -.RS 4 -Restrict btrfs commands to . -.RE -.PP -\-l, \-\-log -.RS 4 -Log ACCEPT and REJECT messages to the system log. -.RE -.PP -\-\-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 -Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR -for further details. -.SH SEE ALSO -.BR btrbk (1), -.BR btrbk.conf (5), -.BR btrfs (1) -.SH AUTHOR -Axel Burri diff --git a/doc/ssh_filter_btrbk.1.asciidoc b/doc/ssh_filter_btrbk.1.asciidoc new file mode 100644 index 0000000..71e7040 --- /dev/null +++ b/doc/ssh_filter_btrbk.1.asciidoc @@ -0,0 +1,108 @@ +ssh_filter_btrbk(1) +=================== +:date: 2017-10-09 +:revision: 0.26.0-dev +:man manual: Btrbk Manual +:man source: Btrbk + + +NAME +---- + +ssh_filter_btrbk.sh - ssh command filter script for btrbk + + +SYNOPSIS +-------- + +[literal] +ssh_filter_btrbk.sh [-s|--source] [-t|--target] [-d|--delete] [-i|--info] + [-p|--restrict-path ] [-l|--log] [--sudo] + + +DESCRIPTION +----------- + +*ssh_filter_btrbk.sh* restricts SSH commands to 'btrfs' commands used +by 'btrbk'. It examines the SSH_ORIGINAL_COMMAND environment variable +(set by sshd) and executes it only if it matches commands used by +'btrbk'. The accepted commands are specified by the "--source", +"--target", "--delete" and "--info" options. + +Note that the following btrfs commands are always allowed: "btrfs +subvolume show", "btrfs subvolume list". + +Note that commands for stream compression (pipes through gzip, pigz, +bzip2, pbzip2, xz, lzop, lz4), rate limiting (pipes through "pv -L"), +and stream buffer (pipes through "mbuffer") are always allowed. + +Example line in /root/.ssh/authorized_keys on a backup target host: + + command="ssh_filter_btrbk.sh --target --delete --restrict-path /mnt/btr_backup" ssh-rsa AAAAB3NzaC1...hwumXFRQBL btrbk@mydomain.com + + +OPTIONS +------- + +-s, --source:: + Allow commands for backup source: "btrfs subvolume snapshot", + "btrfs send". Equivalent to "--snapshot --send". + +-t, --target:: + Allow commands for backup target: "btrfs receive", "realpath" and + "cat /proc/self/mounts". + +-d, --delete:: + Allow commands for subvolume deletion: "btrfs subvolume + delete". This is used for backup source if + 'snapshot_preserve_daily' is not set to ``all'', and for backup + targets if 'target_preserve_daily' is not set to ``all''. + +-c, --compress:: + Allow commands for stream compression (pipes through gzip, pigz, + bzip2, pbzip2, xz, lzo, lz4). Needed if 'stream_compress' is set. + +-i, --info:: + Allow informative commands: "btrfs subvolume find-new", "btrfs + filesystem usage". This is used by btrbk 'info' and 'diff' + commands. + +--snapshot:: + Allow btrfs snapshot command: "btrfs subvolume snapshot". + +--send:: + Allow btrfs send command: "btrfs send". + +--receive:: + Allow btrfs receive command: "btrfs receive". + +-p, --restrict-path :: + Restrict btrfs commands to . + +-l, --log:: + Log ACCEPT and REJECT messages to the system log. + +--sudo:: + Allow btrfs commands to be called via sudo. Enable this if you + have "backend btrfs-progs-sudo" in your btrbk configuration file. + + +AVAILABILITY +------------ + +Please refer to the btrbk project page ** for +further details. + + +SEE ALSO +-------- + +*btrbk*(1), +*btrbk.conf*(5), +*btrfs*(8) + + +AUTHOR +------ + +Axel Burri