build_man

This commit is contained in:
Thomas Waldmann 2020-04-12 19:55:57 +02:00
parent 56c599e6dc
commit 6b3c7165aa
33 changed files with 130 additions and 90 deletions

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BENCHMARK-CRUD 1 "2019-11-01" "" "borg backup tool"
.TH BORG-BENCHMARK-CRUD 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BENCHMARK 1 "2019-11-01" "" "borg backup tool"
.TH BORG-BENCHMARK 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-benchmark \- benchmark command
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BREAK-LOCK 1 "2019-11-01" "" "borg backup tool"
.TH BORG-BREAK-LOCK 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHECK 1 "2019-11-01" "" "borg backup tool"
.TH BORG-CHECK 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.
@ -40,24 +40,25 @@ The check command verifies the consistency of a repository and the corresponding
First, the underlying repository data files are checked:
.INDENT 0.0
.IP \(bu 2
For all segments the segment magic (header) is checked
For all segments, the segment magic header is checked.
.IP \(bu 2
For all objects stored in the segments, all metadata (e.g. crc and size) and
For all objects stored in the segments, all metadata (e.g. CRC and size) and
all data is read. The read data is checked by size and CRC. Bit rot and other
types of accidental damage can be detected this way.
.IP \(bu 2
If we are in repair mode and a integrity error is detected for a segment,
we try to recover as many objects from the segment as possible.
In repair mode, if an integrity error is detected in a segment, try to recover
as many objects from the segment as possible.
.IP \(bu 2
In repair mode, it makes sure that the index is consistent with the data
stored in the segments.
In repair mode, make sure that the index is consistent with the data stored in
the segments.
.IP \(bu 2
If you use a remote repo server via ssh:, the repo check is executed on the
repo server without causing significant network traffic.
If checking a remote repo via \fBssh:\fP, the repo check is executed on the server
without causing significant network traffic.
.IP \(bu 2
The repository check can be skipped using the \fB\-\-archives\-only\fP option.
.IP \(bu 2
A repository check can be time consuming. Partial checks are possible with the \fB\-\-max\-duration\fP option.
A repository check can be time consuming. Partial checks are possible with the
\fB\-\-max\-duration\fP option.
.UNINDENT
.sp
Second, the consistency and correctness of the archive metadata is verified:
@ -66,46 +67,46 @@ Second, the consistency and correctness of the archive metadata is verified:
Is the repo manifest present? If not, it is rebuilt from archive metadata
chunks (this requires reading and decrypting of all metadata and data).
.IP \(bu 2
Check if archive metadata chunk is present. if not, remove archive from
manifest.
Check if archive metadata chunk is present; if not, remove archive from manifest.
.IP \(bu 2
For all files (items) in the archive, for all chunks referenced by these
files, check if chunk is present.
If a chunk is not present and we are in repair mode, replace it with a same\-size
replacement chunk of zeros.
If a previously lost chunk reappears (e.g. via a later backup) and we are in
repair mode, the all\-zero replacement chunk will be replaced by the correct chunk.
This requires reading of archive and file metadata, but not data.
files, check if chunk is present. In repair mode, if a chunk is not present,
replace it with a same\-size replacement chunk of zeroes. If a previously lost
chunk reappears (e.g. via a later backup), in repair mode the all\-zero replacement
chunk will be replaced by the correct chunk. This requires reading of archive and
file metadata, but not data.
.IP \(bu 2
If we are in repair mode and we checked all the archives: delete orphaned
chunks from the repo.
In repair mode, when all the archives were checked, orphaned chunks are deleted
from the repo. One cause of orphaned chunks are input file related errors (like
read errors) in the archive creation process.
.IP \(bu 2
if you use a remote repo server via ssh:, the archive check is executed on
the client machine (because if encryption is enabled, the checks will require
decryption and this is always done client\-side, because key access will be
required).
If checking a remote repo via \fBssh:\fP, the archive check is executed on the
client machine because it requires decryption, and this is always done client\-side
as key access is needed.
.IP \(bu 2
The archive checks can be time consuming, they can be skipped using the
The archive checks can be time consuming; they can be skipped using the
\fB\-\-repository\-only\fP option.
.UNINDENT
.sp
The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check into multiple partial checks.
After the given number of seconds the check is interrupted. The next partial check will continue where the
previous one stopped, until the complete repository has been checked. Example: Assuming a full check took 7
hours, then running a daily check with \-\-max\-duration=3600 (1 hour) would result in one full check per week.
The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check
into multiple partial checks. After the given number of seconds the check is
interrupted. The next partial check will continue where the previous one stopped,
until the complete repository has been checked. Example: Assuming a full check took 7
hours, then running a daily check with \-\-max\-duration=3600 (1 hour) resulted in one
full check per week.
.sp
Attention: Partial checks can only do way less checks than a full check (only the CRC32 checks on segment file
entries are done) and cannot be combined with \fB\-\-repair\fP\&. Partial checks may therefore be useful only with very
large repositories where a full check would take too long. Doing a full repository check aborts a partial check;
the next partial check will start from the beginning.
Attention: Partial checks can only do way less checking than a full check (only the
CRC32 checks on segment file entries are done), and cannot be combined with the
\fB\-\-repair\fP option. Partial checks may therefore be useful only with very large
repositories where a full check took too long. Doing a full repository check aborts a
partial check; the next partial check will restart from the beginning.
.sp
The \fB\-\-verify\-data\fP option will perform a full integrity verification (as opposed to
checking the CRC32 of the segment) of data, which means reading the data from the
repository, decrypting and decompressing it. This is a cryptographic verification,
which will detect (accidental) corruption. For encrypted repositories it is
tamper\-resistant as well, unless the attacker has access to the keys.
.sp
It is also very slow.
tamper\-resistant as well, unless the attacker has access to the keys. It is also very
slow.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMMON 1 "2019-11-01" "" "borg backup tool"
.TH BORG-COMMON 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.
@ -63,6 +63,9 @@ Output one JSON object per log line instead of formatted text.
.BI \-\-lock\-wait \ SECONDS
wait at most SECONDS for acquiring a repository/cache lock (default: 1).
.TP
.B \-\-bypass\-lock
Bypass locking mechanism
.TP
.B \-\-show\-version
show/log the borg version
.TP

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPACT 1 "2019-11-01" "" "borg backup tool"
.TH BORG-COMPACT 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-compact \- compact segment files in the repository
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPRESSION 1 "2019-11-01" "" "borg backup tool"
.TH BORG-COMPRESSION 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CONFIG 1 "2019-11-01" "" "borg backup tool"
.TH BORG-CONFIG 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-config \- get, set, and delete values in a repository or cache config file
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CREATE 1 "2019-11-01" "" "borg backup tool"
.TH BORG-CREATE 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.
@ -201,7 +201,10 @@ do not store ctime into archive
do not store birthtime (creation date) into archive
.TP
.B \-\-nobsdflags
do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive
deprecated, use \fB\-\-noflags\fP instead
.TP
.B \-\-noflags
do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive
.TP
.BI \-\-files\-cache \ MODE
operate files cache in MODE. default: ctime,size,inode

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DELETE 1 "2019-11-01" "" "borg backup tool"
.TH BORG-DELETE 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.
@ -40,9 +40,10 @@ This command deletes an archive from the repository or the complete repository.
Important: When deleting archives, repository disk space is \fBnot\fP freed until
you run \fBborg compact\fP\&.
.sp
If you delete the complete repository, the local cache for it (if any) is
also deleted. Alternatively, you can delete just the local cache with the
\fB\-\-cache\-only\fP option.
When you delete a complete repository, the security info and local cache for it
(if any) are also deleted. Alternatively, you can delete just the local cache
with the \fB\-\-cache\-only\fP option, or keep the security info with the
\fB\-\-keep\-security\-info\fP option.
.sp
When using \fB\-\-stats\fP, you will get some statistics about how much data was
deleted \- the "Deleted data" deduplicated size there is most interesting as
@ -85,6 +86,9 @@ delete only the local cache for the given repository
.B \-\-force
force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
.TP
.B \-\-keep\-security\-info
keep the local security info when deleting a repository
.TP
.B \-\-save\-space
work slower, but using less space
.UNINDENT

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DIFF 1 "2019-11-01" "" "borg backup tool"
.TH BORG-DIFF 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXPORT-TAR 1 "2019-11-01" "" "borg backup tool"
.TH BORG-EXPORT-TAR 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXTRACT 1 "2019-11-01" "" "borg backup tool"
.TH BORG-EXTRACT 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.
@ -81,7 +81,10 @@ do not actually change any files
only obey numeric user and group identifiers
.TP
.B \-\-nobsdflags
do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE)
deprecated, use \fB\-\-noflags\fP instead
.TP
.B \-\-noflags
do not extract/set flags (e.g. NODUMP, IMMUTABLE)
.TP
.B \-\-stdout
write all extracted data to stdout

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INFO 1 "2019-11-01" "" "borg backup tool"
.TH BORG-INFO 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INIT 1 "2019-11-01" "" "borg backup tool"
.TH BORG-INIT 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2019-11-01" "" "borg backup tool"
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-EXPORT 1 "2019-11-01" "" "borg backup tool"
.TH BORG-KEY-EXPORT 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-IMPORT 1 "2019-11-01" "" "borg backup tool"
.TH BORG-KEY-IMPORT 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2019-11-01" "" "borg backup tool"
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY 1 "2019-11-01" "" "borg backup tool"
.TH BORG-KEY 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-LIST 1 "2019-11-01" "" "borg backup tool"
.TH BORG-LIST 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.
@ -53,6 +53,9 @@ paths to list; patterns are supported
.SS optional arguments
.INDENT 0.0
.TP
.B \-\-consider\-checkpoints
Show checkpoint archives in the repository contents list (default: hidden).
.TP
.B \-\-short
only print file/directory names, nothing else
.TP

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-MOUNT 1 "2019-11-01" "" "borg backup tool"
.TH BORG-MOUNT 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.
@ -93,6 +93,9 @@ paths to extract; patterns are supported
.SS optional arguments
.INDENT 0.0
.TP
.B \-\-consider\-checkpoints
Show checkpoint archives in the repository contents list (default: hidden).
.TP
.B \-f\fP,\fB \-\-foreground
stay in foreground, do not daemonize
.TP

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PATTERNS 1 "2019-11-01" "" "borg backup tool"
.TH BORG-PATTERNS 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.
@ -127,6 +127,9 @@ selector prefix is also supported for patterns loaded from a file. Due to
whitespace removal paths with whitespace at the beginning or end can only be
excluded using regular expressions.
.sp
To test your exclusion patterns without performing an actual backup you can
run \fBborg create \-\-list \-\-dry\-run ...\fP\&.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PLACEHOLDERS 1 "2019-11-01" "" "borg backup tool"
.TH BORG-PLACEHOLDERS 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PRUNE 1 "2019-11-01" "" "borg backup tool"
.TH BORG-PRUNE 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RECREATE 1 "2019-11-01" "" "borg backup tool"
.TH BORG-RECREATE 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RENAME 1 "2019-11-01" "" "borg backup tool"
.TH BORG-RENAME 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-SERVE 1 "2019-11-01" "" "borg backup tool"
.TH BORG-SERVE 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UMOUNT 1 "2019-11-01" "" "borg backup tool"
.TH BORG-UMOUNT 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UPGRADE 1 "2019-11-01" "" "borg backup tool"
.TH BORG-UPGRADE 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-upgrade \- upgrade a repository from a previous version
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-WITH-LOCK 1 "2019-11-01" "" "borg backup tool"
.TH BORG-WITH-LOCK 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG 1 "2019-11-01" "" "borg backup tool"
.TH BORG 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.
@ -465,9 +465,6 @@ in systemd.nspawn containers on some architectures (e.g. ARM).
Using this does not affect data safety, but might result in a more bursty
write to disk behaviour (not continuously streaming to disk).
.UNINDENT
.TP
.B TMPDIR
where temporary files are stored (might need a lot of temporary space for some operations), see \fI\%tempfile\fP for details
.UNINDENT
.TP
.B Some automatic "answerers" (if set, they automatically answer confirmation questions):
@ -492,31 +489,46 @@ For "recreate is an experimental feature."
Note: answers are case sensitive. setting an invalid answer value might either give the default
answer or ask you interactively, depending on whether retries are allowed (they by default are
allowed). So please test your scripts interactively before making them a non\-interactive script.
.UNINDENT
.INDENT 0.0
.TP
.B Directories and files:
.INDENT 7.0
.TP
.B BORG_BASE_DIR
Default to \(aq$HOME\(aq, \(aq~$USER\(aq, \(aq~\(aq (in that order)\(aq.
If we refer to ~ below, we in fact mean BORG_BASE_DIR.
.TP
.B BORG_CONFIG_DIR
Default to \(aq~/.config/borg\(aq. This directory contains the whole config directories.
Defaults to \fB$HOME\fP or \fB~$USER\fP or \fB~\fP (in that order).
If you want to move all borg\-specific folders to a custom path at once, all you need to do is
to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt accordingly
(assuming you didn\(aqt set them to a different custom value).
.TP
.B BORG_CACHE_DIR
Default to \(aq~/.cache/borg\(aq. This directory contains the local cache and might need a lot
of space for dealing with big repositories.
Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
\fI\%XDG env var\fP \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
This directory contains the local cache and might need a lot
of space for dealing with big repositories. Make sure you\(aqre aware of the associated
security aspects of the cache location: \fIcache_security\fP
.TP
.B BORG_CONFIG_DIR
Defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
\fI\%XDG env var\fP \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
This directory contains all borg configuration directories, see the FAQ
for a security advisory about the data in this directory: \fIhome_config_borg\fP
.TP
.B BORG_SECURITY_DIR
Default to \(aq~/.config/borg/security\(aq. This directory contains information borg uses to
track its usage of NONCES ("numbers used once" \- usually in encryption context) and other
security relevant data.
Defaults to \fB$BORG_CONFIG_DIR/security\fP\&.
This directory contains information borg uses to track its usage of NONCES ("numbers used
once" \- usually in encryption context) and other security relevant data.
.TP
.B BORG_KEYS_DIR
Default to \(aq~/.config/borg/keys\(aq. This directory contains keys for encrypted repositories.
Defaults to \fB$BORG_CONFIG_DIR/keys\fP\&.
This directory contains keys for encrypted repositories.
.TP
.B BORG_KEY_FILE
When set, use the given filename as repository key file.
.TP
.B TMPDIR
This is where temporary files are stored (might need a lot of temporary space for some
operations), see \fI\%tempfile\fP for details.
.UNINDENT
.TP
.B Building:
@ -542,10 +554,10 @@ will be linked against the system libzstd instead of a bundled implementation. (
Please note:
.INDENT 0.0
.IP \(bu 2
be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data\(aqs security/safety
Be very careful when using the "yes" sayers, the warnings with prompt exist for your / your data\(aqs security/safety.
.IP \(bu 2
also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions
(e.g. mode 600, root:root).
Also be very careful when putting your passphrase into a script, make sure it has appropriate file permissions (e.g.
mode 600, root:root).
.UNINDENT
.SS File systems
.sp
@ -871,5 +883,7 @@ Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#s
.UNINDENT
.SH AUTHOR
The Borg Collective
orphan:
.\" Generated by docutils manpage writer.
.

View File

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORGFS 1 "2019-11-01" "" "borg backup tool"
.TH BORGFS 1 "2020-04-12" "" "borg backup tool"
.SH NAME
borgfs \- Mount archive or an entire repository as a FUSE filesystem
.
@ -96,6 +96,9 @@ paths to extract; patterns are supported
.B \-V\fP,\fB \-\-version
show version number and exit
.TP
.B \-\-consider\-checkpoints
Show checkpoint archives in the repository contents list (default: hidden).
.TP
.B \-f\fP,\fB \-\-foreground
stay in foreground, do not daemonize
.TP