From 25e94a082a07d054a7d12471dd26d78bcbe2ebc2 Mon Sep 17 00:00:00 2001 From: Axel Burri Date: Sun, 8 Feb 2015 13:43:29 +0100 Subject: [PATCH] documentation: added btrbk(1) and btrbk.conf(5) man pages --- doc/btrbk.1 | 119 +++++++++++++++++++++++++++++++++++++++++++++++ doc/btrbk.conf.5 | 116 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 doc/btrbk.1 create mode 100644 doc/btrbk.conf.5 diff --git a/doc/btrbk.1 b/doc/btrbk.1 new file mode 100644 index 0000000..580a0e5 --- /dev/null +++ b/doc/btrbk.1 @@ -0,0 +1,119 @@ +.TH "btrbk" "1" "2015-02-08" "btrbk v0.10" "" +.SH NAME +btrbk \- backup tool for btrfs volumes +.SH SYNOPSIS +\fBbtrbk\fR [\-\-version] [\-\-help] [\-c ] [\-v] [\-q] [\-l ] [] +.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: +.IP +.YYYYMMDD[_N] +.PP +Where YYYY is the year, MM is the month, and DD is the day of +creation, and, if multiple backups are created on the same day, N will +be incremented on each backup, starting at 1. +.SH OPTIONS +.TP +\-\-version +Prints the btrbk version. +.TP +\-\-help +Prints the synopsis and a list of the commands. +.TP +\-c +Read the configuration from . +.TP +\-v +Verbose output. Identical to: \-l info. +.TP +\-q +Quiet operation. If set, btrbk does not print the summary after +executing the "run" command. +.TP +\-l +Set the level of verbosity. Accepted levels are warn, info, debug, +and trace. +.SH COMMANDS +.PP +.B run +.RS 4 +Perform backup operations as specified in the configuration +file: +.PP +First, btrbk reads information from the source/target btrfs volumes in +order to do sanity checks and find out about parent/child as well as +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 a new backup subvolume, +incremental from the latest common snapshot / backup subvolume +found. If no common parent subvolume is found, a full backup is +created. +.PP +In a last step, previous snapshots and backup subvolumes that are not +preserved by the current retention policy will be deleted. +.RE +.PP +.B dryrun +.RS 4 +Don't run btrfs commands, just show the snapshots and backup +subvolumes that what 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 info +.RS 4 +Print filesystem usage information for all source/target volumes. +.RE +.PP +.B tree +.RS 4 +Print the snapshots and their corresponding backup subvolumes as a +tree. +.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 +.SH FILES +.TP +/etc/btrbk.conf +.PD 0 +.TP +/etc/btrbk/btrbk.conf +Default configuration file. The file format and configuration options +are described in +.BR btrbk.conf (5). +.PD +.SH EXIT STATUS +.sp +\fBbtrbk\fR returns a zero exit status if it succeeds. Non zero is +returned in case of failure. +.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 diff --git a/doc/btrbk.conf.5 b/doc/btrbk.conf.5 new file mode 100644 index 0000000..eacb25d --- /dev/null +++ b/doc/btrbk.conf.5 @@ -0,0 +1,116 @@ +.TH "btrbk.conf" "5" "2015-02-08" "btrbk v0.10" "" +.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 other options can be +defined for each backup. +.PP +The options specified always apply to the last section encountered, +overriding the same option of the next higher section. This means that +global options must be set before any sections are defined. +.PP +The sections are: +.TP +\fBvolume\fR | +Directory of a btrfs volume (or subvolume) containing the source +subvolume(s) to be backuped (usually the mount-point of a btrfs +filesystem mounted with the \fIsubvolid=0\fR option). +.TP +\fBsubvolume\fR +Subvolume to be backuped, relative to the \fI\fR +specified in the \fIvolume\fR section. +.TP +\fBtarget\fR | +Target type and directory where the backup subvolumes are to be +created. In the current version of btrbk, the only valid \fI\fR +is \(lqsend\-receive\(rq. +.PP +For the \fIvolume\fR and \fItarget\fR sections, you can also specify a +ssh-url instead of a local directory. The syntax for \fI\fR is: +.IP +ssh://host.xz/path/to/volume +.PP +The configuration options are: +.TP +\fBsnapshot_dir\fR +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. +.TP +\fBsnapshot_create_always\fR yes|no +If set, the snapshots are always created, even if the backup subvolume +cannot be created (e.g. if the target subvolume cannot be +reached). Defaults to \(lqno\(rq. Useful for subvolumes on laptops to +make sure the snapshots are created even if you are on the road. +.TP +\fBincremental\fR yes|no|strict +Perform incremental backups. Defaults to \(lqyes\(rq. If set to +\(lqstrict\(rq, non-incremental (initial) backups are never created. +.TP +\fBtarget_preserve_daily\fR all| +How many days of backups should be preserved. Defaults to \(lqall\(rq. +.TP +\fBtarget_preserve_weekly\fR all| +Defines for how many weeks back weekly backups should be +preserved. Every backup created at \fIpreserve_day_of_week\fR (or +the next backup in this week if none was made on the exact day) is +considered as a weekly backup. Defaults to \(lq0\(rq. +.TP +\fBtarget_preserve_monthly\fR all| +Defines for how many months back monthly backups should be +preserved. Every last weekly backup in a month is considered a +monthly backup. Defaults to \(lqall\(rq. +.TP +\fBsnapshot_preserve_daily\fR +.PD 0 +.TP +\fBsnapshot_preserve_weekly\fR +.TP +\fBsnapshot_preserve_monthly\fR +Define retention policy for the snapshots, with same semantics as the +\fItarget_preserve_*\fR options. +.PD +.TP +\fBpreserve_day_of_week\fR monday|tuesday|...|sunday +Defines on what day a backup/snapshot is considered as a weekly +backup. Defaults to \(lqsunday\(rq. +.TP +\fBssh_identity\fR +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. +.TP +\fBssh_user\fR +Remote username for ssh. Defaults to \(lqroot\(rq. Note that you will +have to make sure that the remote user is able to run /sbin/btrfs +(which needs root privileges). +.TP +\fBbtrfs_commit_delete\fR after|each|no +If set, make sure the deletion of snapshot and backup subvolumes are +committed to disk when btrbk terminates. Defaults to \(lqno\(rq. +.TP +\fBreceive_log\fR |sidecar|no +Dump verbose output of \fIbtrfs receive\fR to a specified file. If set +to \(lqsidecar\(rq, the file will be created in the backup directory, +named \fI.btrbk.log\fR. Note that this log file can +become very big, as every change of every file is being +logged. Consider this as a debugging feature. Defaults to \(lqno\(rq. +.PP +Lines that contain a hash character (#) in the first column are +treated as comments. +.SH AVAILABILITY +Please refer to the btrbk project page +\fBhttp://www.digint.ch/btrbk\fR for further +details. +.SH SEE ALSO +.BR btrbk (1) +.SH AUTHOR +Axel Burri