.TH "btrbk" "1" "2015-10-25" "btrbk v0.21.0" "" .\" 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] [\-r|\-\-resume\-only] [\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel ] [\-t|\-\-table] [\-\-format ] [\-\-progress] [] .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 target volumes. 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 backup, 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 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 backups. Skips deletion of old backups, even if specified in the configuration file. .RE .PP \-r, \-\-resume-only .RS 4 Resume only. Skips snapshot creation, only resumes missing backups. This only makes sense if the \fIresume_missing\fR option is set to \[lq]yes\[rq] in the configuration file. .RE .PP \-v, \-\-verbose .RS 4 Verbose output. Sets "\-l info", and prints detailed scheduler information on "run" and "dryrun" commands. .RE .PP \-q, \-\-quiet .RS 4 Quiet operation. If set, btrbk does not print the summary after executing the "run" command. .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, \fBdryrun\fR, \fBlist\fR and \fBtree\fR commands. Useful for further exporting/scripting. .RE .PP \-\-progress .RS 4 Show progress bar on send-receive operation. .RE .SH COMMANDS .PP .B run [filter...] .RS 4 Perform backup operations as specified in the configuration file. If the optional [filter...] arguments are present, backups are only performed for the subvolumes/targets matching a \fIFILTER STATEMENT\fR (see below). .PP First, btrbk reads information from the source and target btrfs filesystems in order to perform sanity checks and identify parent/child and received-from relationships. .PP If the checks succeed, btrbk creates snapshots for all the source subvolumes specified in the configuration file. .PP Then, for each specified target, btrbk creates the backups as follows: If the \fIresume_missing\fR option is set (the default), btrbk transfers all missing snapshots needed to satisfy the configured \fItarget_preserve_{daily,weekly,monthly}\fR retention policy, always incrementally from the latest common parent subvolume found. If no common parent subvolume is found, a full backup is created for the first transfer. Note that the latest snapshot (the one created in the first step) is always transferred, regardless of the retention policy. .PP As a last step, unless the -p (preserve backups) option is set, snapshots and backup subvolumes that are not preserved by their configured retention policy will be deleted. Note that the latest snapshot as well as the latest backup is always preserved, regardless of 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 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 snapshots and backups. .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). .RE .PP .B origin .RS 4 Print origin information for the given backup subvolume, showing the parent-child relationship as well as the received-from information. .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:", "{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 "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://www.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