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

documentation: cosmetics: groff: consistently use minus "\-" instead of hyphen "-" where applicable

pull/88/head
Axel Burri 2016-05-03 15:54:35 +02:00
parent cb6dcbe58e
commit 65ebf949d1
3 changed files with 46 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/btrbk.1
View File

@ -23,10 +23,10 @@ backups from one source to multiple destinations.
Snapshots as well as backup subvolume names are created in form: Snapshots as well as backup subvolume names are created in form:
.PP .PP
.RS 4 .RS 4
<snapshot-name>.<timestamp>[_N] <snapshot\-name>.<timestamp>[_N]
.RE .RE
.PP .PP
Where <snapshot-name> is identical to the source subvolume name, Where <snapshot\-name> is identical to the source subvolume name,
unless the configuration option \fIsnapshot_name\fR is set. The unless the configuration option \fIsnapshot_name\fR is set. The
<timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the <timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the
\fItimestamp_format\fR configuration option), where "YYYY" is the \fItimestamp_format\fR configuration option), where "YYYY" is the
@ -90,13 +90,13 @@ and trace.
.PP .PP
\-t, \-\-table \-t, \-\-table
.RS 4 .RS 4
Print output in table format (shortcut for "--format=table"). Print output in table format (shortcut for "\-\-format=table").
.RE .RE
.PP .PP
\-\-format table|long|raw \-\-format table|long|raw
.RS 4 .RS 4
Print output in specified format. If set to "raw", prints Print output in specified format. If set to "raw", prints
space-separated key="value" pairs (machine-readable). Affects output space-separated key="value" pairs (machine readable). Affects output
format for \fBrun\fR, \fBdryrun\fR, \fBlist\fR and \fBtree\fR format for \fBrun\fR, \fBdryrun\fR, \fBlist\fR and \fBtree\fR
commands. Useful for further exporting/scripting. commands. Useful for further exporting/scripting.
.RE .RE
@ -181,12 +181,12 @@ using btrbk after swapping your backup disk with the archive disk.
Note that this feature needs a \fBlinux kernel >=4.4\fR to work 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 correctly! Kernels >=4.1 and <4.4 have a bug when re-sending
subvolumes (the archived subvolumes will have incorrect received_uuid, subvolumes (the archived subvolumes will have incorrect received_uuid,
see <http://thread.gmane.org/gmane.comp.file-systems.btrfs/48798>), so see <http://thread.gmane.org/gmane.comp.file\-systems.btrfs/48798>),
make sure you run a recent kernel. so make sure you run a recent kernel.
.PP .PP
Known bugs: If you want to use nested subvolumes on the target 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 filesystem, you need to create them by hand (e.g. by running "btrfs
subvolume create <target>/dir"). Check the output of --dry-run if subvolume create <target>/dir"). Check the output of \-\-dry\-run if
unsure. unsure.
.RE .RE
.PP .PP
@ -266,7 +266,7 @@ Print new files since subvolume <from> for subvolume <to>.
.RE .RE
.PP .PP
.B config .B config
print|print-all print|print\-all
.RS 4 .RS 4
Prints the parsed configuration file. Use the \fI\-\-format\fR command Prints the parsed configuration file. Use the \fI\-\-format\fR command
line option to switch between different output formats. line option to switch between different output formats.
@ -274,30 +274,30 @@ line option to switch between different output formats.
.SH FILTER STATEMENTS .SH FILTER STATEMENTS
Filter arguments are accepted in form: Filter arguments are accepted in form:
.PP .PP
[hostname:]<volume-directory> [hostname:]<volume\-directory>
.RS 4 .RS 4
Matches all subvolumes and targets of a \fIvolume\fR configuration Matches all subvolumes and targets of a \fIvolume\fR configuration
section. section.
.RE .RE
.PP .PP
[hostname:]<volume-directory>/<subvolume-name> [hostname:]<volume\-directory>/<subvolume\-name>
.RS 4 .RS 4
Matches the specified subvolume and all targets of a \fIsubvolume\fR Matches the specified subvolume and all targets of a \fIsubvolume\fR
configuration section. configuration section.
.RE .RE
.PP .PP
[hostname:]<target-directory> [hostname:]<target\-directory>
.RS 4 .RS 4
Matches all targets of a \fItarget\fR configuration section. Matches all targets of a \fItarget\fR configuration section.
.RE .RE
.PP .PP
[hostname:]<target-directory>/<snapshot-name> [hostname:]<target\-directory>/<snapshot\-name>
.RS 4 .RS 4
Matches a single target of a \fItarget\fR section within a Matches a single target of a \fItarget\fR section within a
\fIsubvolume\fR section with given <snapshot-name>. \fIsubvolume\fR section with given <snapshot\-name>.
.RE .RE
.PP .PP
<group-name> <group\-name>
.RS 4 .RS 4
Matches the \fIgroup\fR configuration option of a \fIvolume\fR, Matches the \fIgroup\fR configuration option of a \fIvolume\fR,
\fIsubvolume\fR or \fItarget\fR section. \fIsubvolume\fR or \fItarget\fR section.

60
doc/btrbk.conf.5
View File

@ -21,22 +21,22 @@ superseding the values set in upper-level sections. This means that
global options must be set before any sections are defined. global options must be set before any sections are defined.
.SH SECTIONS .SH SECTIONS
.PP .PP
\fBvolume\fR <volume-directory>|<url> \fBvolume\fR <volume\-directory>|<url>
.RS 4 .RS 4
Directory of a btrfs volume containing the source subvolume(s) to be 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 backed up. \fI<volume\-directory>\fR must be an absolute path and
to a btrfs volume (or subvolume). Usually the mount point of a btrfs point to a btrfs volume (or subvolume). Usually the mount point of a
filesystem mounted with the \fIsubvolid=0\fR option. btrfs filesystem mounted with the \fIsubvolid=0\fR option.
.RE .RE
.PP .PP
\fBsubvolume\fR <subvolume-name> \fBsubvolume\fR <subvolume\-name>
.RS 4 .RS 4
Subvolume to be backed up, relative to the \fI<volume-directory>\fR Subvolume to be backed up, relative to the \fI<volume\-directory>\fR
specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR
sections are allowed within \fIvolume\fR sections. sections are allowed within \fIvolume\fR sections.
.RE .RE
.PP .PP
\fBtarget\fR <type> <target-directory>|<url> \fBtarget\fR <type> <target\-directory>|<url>
.RS 4 .RS 4
Target type and directory where the backup subvolumes are to be Target type and directory where the backup subvolumes are to be
created. See the TARGET TYPES section for supported created. See the TARGET TYPES section for supported
@ -49,7 +49,7 @@ resulting configuration).
.RE .RE
.PP .PP
For the \fIvolume\fR and \fItarget\fR sections, you can specify a For the \fIvolume\fR and \fItarget\fR sections, you can specify a
ssh-url instead of a local directory. The syntax for \fI<url>\fR is: ssh\-url instead of a local directory. The syntax for \fI<url>\fR is:
.PP .PP
.RS 4 .RS 4
.nf .nf
@ -63,14 +63,14 @@ convenience, "ssh://<hostname>/<directory>" can also be specified as
"<hostname>:<directory>". "<hostname>:<directory>".
.PP .PP
Note that btrfs is very picky on file names (mainly for security Note that btrfs is very picky on file names (mainly for security
reasons), only the characters [0-9] [a-z] [A-Z] and "._+-@" are reasons), only the characters [0\-9] [a\-z] [A\-Z] and "._+\-@" are
allowed. allowed.
.RE .RE
.SH OPTIONS .SH OPTIONS
.PP .PP
\fBtransaction_log\fR <file> \fBtransaction_log\fR <file>
.RS 4 .RS 4
If set, all transactions (snapshot create, subvolume send-receive, If set, all transactions (snapshot create, subvolume send\-receive,
subvolume delete) as well as abort messages are logged to <file>, in a subvolume delete) as well as abort messages are logged to <file>, in a
space-separated table format: "localtime type status duration space-separated table format: "localtime type status duration
target_url source_url parent_url message". target_url source_url parent_url message".
@ -84,7 +84,7 @@ syslog facility name, like \[lq]daemon\[rq] or \[lq]local7\[rq]. The
program name used in the messages is "btrbk". program name used in the messages is "btrbk".
.RE .RE
.PP .PP
\fBtimestamp_format\fR short|long|long-iso \fBtimestamp_format\fR short|long|long\-iso
.RS 4 .RS 4
Timestamp format used as postfix for new snapshot subvolume Timestamp format used as postfix for new snapshot subvolume
names. Defaults to \[lq]short\[rq]. names. Defaults to \[lq]short\[rq].
@ -93,24 +93,24 @@ names. Defaults to \[lq]short\[rq].
YYYYMMDD[_N] (e.g. "20150825", "20150825_1") YYYYMMDD[_N] (e.g. "20150825", "20150825_1")
.IP \fBlong\fR 10 .IP \fBlong\fR 10
YYYYMMDD<T>hhmm[_N] (e.g. "20150825T1531") YYYYMMDD<T>hhmm[_N] (e.g. "20150825T1531")
.IP \fBlong-iso\fR 10 .IP \fBlong\-iso\fR 10
YYYYMMDD<T>hhmmss\[t+-]hhmm[_N] (e.g. "20150825T153123+0200") YYYYMMDD<T>hhmmss\[t+-]hhmm[_N] (e.g. "20150825T153123+0200")
.PP .PP
Note that a postfix "_N" is appended to the timestamp if a snapshot or Note that a postfix "_N" is appended to the timestamp if a snapshot or
backup already exists with the timestamp of current date/time. backup already exists with the timestamp of current date/time.
.PP .PP
Use \[lq]long-iso\[rq] if you want to make sure that btrbk never Use \[lq]long\-iso\[rq] if you want to make sure that btrbk never
creates ambiguous time stamps (which can happen if multiple snapshots creates ambiguous time stamps (which can happen if multiple snapshots
are created during a daylight saving time clock change). are created during a daylight saving time clock change).
.PP .PP
Note that using \[lq]long-iso\[rq] has implications on the scheduling, Note that using \[lq]long\-iso\[rq] has implications on the
see RETENTION POLICY (caveats) below. scheduling, see RETENTION POLICY (caveats) below.
.RE .RE
.PP .PP
\fBsnapshot_dir\fR <directory> \fBsnapshot_dir\fR <directory>
.RS 4 .RS 4
Directory in which the btrfs snapshots are created, relative to Directory in which the btrfs snapshots are created, relative to
\fI<volume-directory>\fR of the \fIvolume\fR section. Note that btrbk \fI<volume\-directory>\fR of the \fIvolume\fR section. Note that btrbk
does not autmatically create this directory, and the snapshot creation does not autmatically create this directory, and the snapshot creation
will fail if it is not present. will fail if it is not present.
.RE .RE
@ -119,7 +119,7 @@ will fail if it is not present.
.RS 4 .RS 4
Base name of the created snapshot (and backup). This option is only Base name of the created snapshot (and backup). This option is only
valid in the \fIsubvolume\fR section. Defaults to valid in the \fIsubvolume\fR section. Defaults to
\fI<subvolume-name>\fR. \fI<subvolume\-name>\fR.
.RE .RE
.PP .PP
\fBsnapshot_create\fR always|onchange|ondemand|no \fBsnapshot_create\fR always|onchange|ondemand|no
@ -183,7 +183,7 @@ Defines on what day a backup/snapshot is considered as a weekly
backup. Defaults to \[lq]sunday\[rq]. backup. Defaults to \[lq]sunday\[rq].
.RE .RE
.PP .PP
\fBgroup\fR <group-name>[,<group-name>]... \fBgroup\fR <group\-name>[,<group\-name>]...
.RS 4 .RS 4
Add the current section (volume, subvolume or target) to a Add the current section (volume, subvolume or target) to a
user-defined group, which can be used as filter for several btrbk user-defined group, which can be used as filter for several btrbk
@ -199,9 +199,9 @@ which is usually not desired.
.PP .PP
\fBssh_user\fR <username> \fBssh_user\fR <username>
.RS 4 .RS 4
Remote username for ssh. Defaults to \[lq]root\[rq]. Note that you will Remote username for ssh. Defaults to \[lq]root\[rq]. Note that you
have to make sure that the remote user is able to run /sbin/btrfs will have to make sure that the remote user is able to run
(which needs root privileges). "/sbin/btrfs" (which needs root privileges).
.RE .RE
.PP .PP
\fBssh_port\fR <port> \fBssh_port\fR <port>
@ -219,7 +219,7 @@ Enables or disables the compression of ssh connections. Defaults to
\fBssh_cipher_spec\fR <cipher_spec> \fBssh_cipher_spec\fR <cipher_spec>
.RS 4 .RS 4
Selects the cipher specification for encrypting the session Selects the cipher specification for encrypting the session
(comma-separated list of ciphers in order of preference). See the "-c (comma-separated list of ciphers in order of preference). See the "\-c
cipher_spec" option in ssh(1) for more information. Defaults to cipher_spec" option in ssh(1) for more information. Defaults to
\[lq]default\[rq] (the ciphers specified in \fIssh_config\fR). \[lq]default\[rq] (the ciphers specified in \fIssh_config\fR).
.RE .RE
@ -263,8 +263,8 @@ With the following semantics:
Defines how many hours back hourly backups should be preserved. The Defines how many hours back hourly backups should be preserved. The
first backup of an hour is considered an hourly backup. Note that if first backup of an hour is considered an hourly backup. Note that if
you use <hourly> scheduling, make sure to also set you use <hourly> scheduling, make sure to also set
\fItimestamp_format\fR to \[lq]long\[rq] or \[lq]long-iso\[rq], or the \fItimestamp_format\fR to \[lq]long\[rq] or \[lq]long\-iso\[rq], or
scheduler will interpret the time as "00:00" (midnight). the scheduler will interpret the time as "00:00" (midnight).
.RE .RE
.PP .PP
.B daily .B daily
@ -311,27 +311,27 @@ 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 with different local time on the clients, in order to make sure the
backups from all the remote hosts are preserved for "midnight", and 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 not at "00:00 UTC" (which would be "14:00" in Honolulu). If you want
this behaviour, do NOT use "timestamp_format long-iso". this behaviour, do NOT use "timestamp_format long\-iso".
.IP \[bu] 2 .IP \[bu] 2
If "timestamp_format long-iso" is set, running btrbk from different If "timestamp_format long\-iso" is set, running btrbk from different
time zones leads to different interpretation of "first in day, week, 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 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 every host, e.g. by setting the TZ environment variable (see
tzset(3)). tzset(3)).
.SH TARGET TYPES .SH TARGET TYPES
.PP .PP
\fBsend-receive\fR \fBsend\-receive\fR
.RS 4 .RS 4
Backup to a btrfs filesystem, using "btrfs send/receive". This is the Backup to a btrfs filesystem, using "btrfs send/receive". This is the
recommended (standard) target type. The \fI<target-directory>\fR must recommended (standard) target type. The \fI<target\-directory>\fR must
be an absolute path and point to a btrfs volume (or subvolume), or to 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). a directory within a subvolume. See btrfs\-send(8), btrfs\-receive(8).
.RE .RE
.PP .PP
\fBraw\fR \fI*experimental*\fR \fBraw\fR \fI*experimental*\fR
.RS 4 .RS 4
Backup to a raw (filesystem independent) file from the output of Backup to a raw (filesystem independent) file from the output of
btrfs-send(8), with optional compression and encryption. btrfs\-send(8), with optional compression and encryption.
.PP .PP
Note that the target preserve mechanism is currently disabled for raw Note that the target preserve mechanism is currently disabled for raw
backups (btrbk does not delete any raw files)! backups (btrbk does not delete any raw files)!

4
doc/ssh_filter_btrbk.1
View File

@ -1,4 +1,4 @@
.TH "ssh_filter_btrbk" "1" "2016-04-23" "btrbk v0.23.0" "" .TH "ssh_filter_btrbk" "1" "2016-05-03" "btrbk v0.23.1-dev" ""
.\" disable hyphenation .\" disable hyphenation
.nh .nh
.\" disable justification (adjust text to left margin only) .\" disable justification (adjust text to left margin only)
@ -51,7 +51,7 @@ to \[lq]all\[rq], and for backup targets if
.PP .PP
\-i, \-\-info \-i, \-\-info
.RS 4 .RS 4
Allow informative commands: "btrfs subvolume find-new", "btrfs Allow informative commands: "btrfs subvolume find\-new", "btrfs
filesystem usage". This is used by btrbk \fIinfo\fR and \fIdiff\fR filesystem usage". This is used by btrbk \fIinfo\fR and \fIdiff\fR
commands. commands.
.RE .RE