mirror of https://github.com/digint/btrbk
documentation: disable hyphenation and justification in man-pages; use .PP and .RS 4 instead of .TP, which creates more predictable output
Axel Burri
parent
5b0e618632
commit
bed9fe1f66
53
doc/btrbk.1
53
doc/btrbk.1
|
|
@ -1,8 +1,14 @@
|
|||
.TH "btrbk" "1" "2015-09-02" "btrbk v0.20.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 [\-\-version] [\-\-help] [\-c <file>] [\-p] [\-v] [\-q] [\-l <level>] <command> [<args>]
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
\fBbtrbk\fR is a backup tool for btrfs subvolumes, taking advantage of
|
||||
btrfs specific capabilities to create atomic snapshots and transfer
|
||||
|
|
@ -10,45 +16,65 @@ 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
|
||||
.PP
|
||||
.RS 4
|
||||
<source_name>.YYYYMMDD[_N]
|
||||
.RE
|
||||
.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
|
||||
.PP
|
||||
\-\-version
|
||||
.RS 4
|
||||
Prints the btrbk version.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\-h, \-\-help
|
||||
.RS 4
|
||||
Prints the synopsis and a list of the commands.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\-c, \-\-config <file>
|
||||
.RS 4
|
||||
Read the configuration from <file>.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\-p, \-\-preserve
|
||||
.RS 4
|
||||
Preserve all backups. Skips deletion of old backups, even if specified
|
||||
in the configuration file.
|
||||
.TP
|
||||
.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.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\-v, \-\-verbose
|
||||
.RS 4
|
||||
Verbose output. Identical to: \-l info.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\-q, \-\-quiet
|
||||
.RS 4
|
||||
Quiet operation. If set, btrbk does not print the summary after
|
||||
executing the "run" command.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\-l, \-\-loglevel <level>
|
||||
.RS 4
|
||||
Set the level of verbosity. Accepted levels are warn, info, debug,
|
||||
and trace.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\-\-progress
|
||||
.RS 4
|
||||
Show progress bar on send-receive operation.
|
||||
.RE
|
||||
.SH COMMANDS
|
||||
.PP
|
||||
.B run
|
||||
|
|
@ -119,14 +145,15 @@ parent-child relationship as well as the received-from information.
|
|||
Print new files since subvolume <from> for subvolume <to>.
|
||||
.RE
|
||||
.SH FILES
|
||||
.TP
|
||||
.PP
|
||||
/etc/btrbk.conf
|
||||
.PD 0
|
||||
.TP
|
||||
.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
|
||||
.sp
|
||||
|
|
|
|||
|
|
@ -1,4 +1,8 @@
|
|||
.TH "btrbk.conf" "5" "2015-09-02" "btrbk v0.20.0" ""
|
||||
.\" disable hyphenation
|
||||
.nh
|
||||
.\" disable justification (adjust text to left margin only)
|
||||
.ad l
|
||||
.SH NAME
|
||||
btrbk.conf \- btrbk configuration file
|
||||
.SH SYNOPSIS
|
||||
|
|
@ -17,18 +21,23 @@ superseding the values set in upper-level sections. This means that
|
|||
global options must be set before any sections are defined.
|
||||
.PP
|
||||
The sections are:
|
||||
.TP
|
||||
.PP
|
||||
\fBvolume\fR <volume-directory>|<url>
|
||||
.RS 4
|
||||
Directory of a btrfs volume containing the source subvolume(s) to be
|
||||
backed up. \fI<volume-directory>\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.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBsubvolume\fR <subvolume-name>
|
||||
.RS 4
|
||||
Subvolume to be backed up, relative to the \fI<volume-directory>\fR
|
||||
specified in the \fIvolume\fR section.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBtarget\fR <type> <volume-directory>|<url>
|
||||
.RS 4
|
||||
Target type and directory where the backup subvolumes are to be
|
||||
created. \fI<volume-directory>\fR must be an absolute path and point
|
||||
to a btrfs volume (or subvolume). Currently the the only valid
|
||||
|
|
@ -36,26 +45,36 @@ to a btrfs volume (or subvolume). Currently the the only valid
|
|||
.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
|
||||
.PP
|
||||
.RS 4
|
||||
.nf
|
||||
ssh://host.xz/path/to/volume
|
||||
.fi
|
||||
.RE
|
||||
.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
|
||||
.PP
|
||||
The configuration options are:
|
||||
.TP
|
||||
.PP
|
||||
\fBsnapshot_dir\fR <directory>
|
||||
.RS 4
|
||||
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_name\fR <basename> Base name of the created snapshot (and
|
||||
backup). This option is only valid in the \fItarget\fR
|
||||
section. Defaults to \fI<subvolume-name>\fR.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBsnapshot_name\fR <basename>
|
||||
.RS 4
|
||||
Base name of the created snapshot (and backup). This option is only
|
||||
valid in the \fItarget\fR section. Defaults to \fI<subvolume-name>\fR.
|
||||
.RE
|
||||
.PP
|
||||
\fBsnapshot_create\fR always|ondemand|onchange|no
|
||||
.RS 4
|
||||
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
|
||||
|
|
@ -67,74 +86,101 @@ created. If set to \[lq]no\[rq], the snapshots are never created
|
|||
(useful in conjunction with the \fIresume_missing\fR option if another
|
||||
instance of btrbk is taking care of snapshot creation). Defaults to
|
||||
\[lq]always\[rq].
|
||||
.TP
|
||||
.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].
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBresume_missing\fR yes|no
|
||||
.RS 4
|
||||
If set, the backups in the target directory are compared to the source
|
||||
snapshots, and missing backups are created if needed (complying to the
|
||||
target preserve matrix). Defaults to \[lq]yes\[rq].
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBtarget_preserve_daily\fR all|<number>
|
||||
.RS 4
|
||||
How many days of backups should be preserved. Defaults to \[lq]all\[rq].
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBtarget_preserve_weekly\fR all|<number>
|
||||
.RS 4
|
||||
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 \[lq]0\[rq].
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBtarget_preserve_monthly\fR all|<number>
|
||||
.RS 4
|
||||
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 \[lq]all\[rq].
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBsnapshot_preserve_daily\fR
|
||||
.PD 0
|
||||
.TP
|
||||
.PP
|
||||
\fBsnapshot_preserve_weekly\fR
|
||||
.TP
|
||||
.PP
|
||||
\fBsnapshot_preserve_monthly\fR
|
||||
.RS 4
|
||||
Defines retention policy for the snapshots, with same semantics as the
|
||||
\fItarget_preserve_*\fR options.
|
||||
.RE
|
||||
.PD
|
||||
.TP
|
||||
.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].
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBssh_identity\fR <file>
|
||||
.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.
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBssh_user\fR <username>
|
||||
.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).
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBssh_port\fR <port>
|
||||
.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).
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBssh_compression\fR yes|no
|
||||
.RS 4
|
||||
Enables or disables the compression of ssh connections. Defaults to
|
||||
\[lq]no\[rq].
|
||||
.TP
|
||||
.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].
|
||||
.TP
|
||||
.RE
|
||||
.PP
|
||||
\fBbtrfs_progs_compat\fR yes|no \fI*experimental*\fR
|
||||
.RS 4
|
||||
Enable compatibility mode for btrfs-progs < 3.17 (\fIbtrfs
|
||||
--version\fR). This option can be set either globally or within a
|
||||
\fItarget\fR section. If enabled, the latest common snapshots are
|
||||
determined by subvolume names instead of \fIreceived_uuid\fR, which
|
||||
can lead to false guesses if the snapshot or target subvolumes are
|
||||
manipulated by hand (moved, deleted).
|
||||
.RE
|
||||
.PP
|
||||
Lines that contain a hash character (#) in the first column are
|
||||
treated as comments.
|
||||
|
|
|
|||
Loading…
Reference in New Issue