ambiser
/
btrbk
mirror of https://github.com/digint/btrbk
9
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

documentation: added btrbk(1) and btrbk.conf(5) man pages

pull/30/head
Axel Burri 2015-02-08 13:43:29 +01:00
parent ceabbf38d3
commit 25e94a082a
2 changed files with 235 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
doc/btrbk.1 Normal file
View File

@ -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 <file>] [\-v] [\-q] [\-l <level>] <command> [<args>]
.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
<source_name>.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 <file>
Read the configuration from <file>.
.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 <level>
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
<subvolume>
.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
<from> <to>
.RS 4
Print new files since subvolume <from> for subvolume <to>.
.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 <axel@tty0.ch>

116
doc/btrbk.conf.5 Normal file
View File

@ -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 <volume-directory>|<url>
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-name>
Subvolume to be backuped, relative to the \fI<volume-directory>\fR
specified in the \fIvolume\fR section.
.TP
\fBtarget\fR <type> <volume-directory>|<url>
Target type and directory where the backup subvolumes are to be
created. In the current version of btrbk, the only valid \fI<type>\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<url>\fR is:
.IP
ssh://host.xz/path/to/volume
.PP
The configuration options are:
.TP
\fBsnapshot_dir\fR <directory>
Directory in which the btrfs snapshots are created. Relative to
\fI<volume-directory>\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|<number>
How many days of backups should be preserved. Defaults to \(lqall\(rq.
.TP
\fBtarget_preserve_weekly\fR all|<number>
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|<number>
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 <file>
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 <username>
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 <file>|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<backup_subvolume>.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 <axel@tty0.ch>