upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-03-28 21:33:48 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Merge pull request #5107 from ThomasWaldmann/update-docs

Browse source 
update docs
This commit is contained in:
TW 2020-04-12 19:59:52 +02:00 committed by GitHub
commit 27bf0220ac
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
42 changed files with 219 additions and 146 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/man/borg-benchmark-crud.1
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.
.

2
docs/man/borg-benchmark.1
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
.

2
docs/man/borg-break-lock.1
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.
.

73
docs/man/borg-check.1
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.

5
docs/man/borg-common.1
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

2
docs/man/borg-compact.1
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
.

2
docs/man/borg-compression.1
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
.

2
docs/man/borg-config.1
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
.

7
docs/man/borg-create.1
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

12
docs/man/borg-delete.1
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

2
docs/man/borg-diff.1
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
.

2
docs/man/borg-export-tar.1
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
.

7
docs/man/borg-extract.1
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

2
docs/man/borg-info.1
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
.

2
docs/man/borg-init.1
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
.

2
docs/man/borg-key-change-passphrase.1
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
.

2
docs/man/borg-key-export.1
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
.

2
docs/man/borg-key-import.1
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
.

2
docs/man/borg-key-migrate-to-repokey.1
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
.

2
docs/man/borg-key.1
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
.

5
docs/man/borg-list.1
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

5
docs/man/borg-mount.1
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

5
docs/man/borg-patterns.1
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

2
docs/man/borg-placeholders.1
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
.

2
docs/man/borg-prune.1
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
.

2
docs/man/borg-recreate.1
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
.

2
docs/man/borg-rename.1
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
.

2
docs/man/borg-serve.1
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.
.

2
docs/man/borg-umount.1
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
.

2
docs/man/borg-upgrade.1
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
.

2
docs/man/borg-with-lock.1
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
.

50
docs/man/borg.1
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.
.

5
docs/man/borgfs.1
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

71
docs/usage/check.rst.inc
View file

@ -89,55 +89,56 @@ The check command verifies the consistency of a repository and the corresponding
First, the underlying repository data files are checked:
- For all segments the segment magic (header) is checked
- For all objects stored in the segments, all metadata (e.g. crc and size) and
- For all segments, the segment magic header is checked.
- 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.
- 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, it makes sure that the index is consistent with the data
stored in the segments.
- If you use a remote repo server via ssh:, the repo check is executed on the
repo server without causing significant network traffic.
- In repair mode, if an integrity error is detected in a segment, try to recover
as many objects from the segment as possible.
- In repair mode, make sure that the index is consistent with the data stored in
the segments.
- If checking a remote repo via ``ssh:``, the repo check is executed on the server
without causing significant network traffic.
- The repository check can be skipped using the ``--archives-only`` option.
- A repository check can be time consuming. Partial checks are possible with the ``--max-duration`` option.
- A repository check can be time consuming. Partial checks are possible with the
``--max-duration`` option.
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).
- 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.
- 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.
- If we are in repair mode and we checked all the archives: delete orphaned
chunks from the repo.
- 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).
- The archive checks can be time consuming, they can be skipped using the
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.
- 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.
- If checking a remote repo via ``ssh:``, 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.
- The archive checks can be time consuming; they can be skipped using the
``--repository-only`` option.
The ``--max-duration`` 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 ``--max-duration`` 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.
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 ``--repair``. 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
``--repair`` 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.
The ``--verify-data`` 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.
It is also very slow.
tamper-resistant as well, unless the attacker has access to the keys. It is also very
slow.

1
docs/usage/common-options.rst.inc
View file

@ -8,6 +8,7 @@
-p, --progress show progress information
--log-json Output one JSON object per log line instead of formatted text.
--lock-wait SECONDS wait at most SECONDS for acquiring a repository/cache lock (default: 1).
--bypass-lock Bypass locking mechanism
--show-version show/log the borg version
--show-rc show/log the return code (rc)
--umask M set umask to M (local and remote, default: 0077)

33
docs/usage/compact.rst.inc
View file

@ -12,19 +12,21 @@ borg compact
.. class:: borg-options-table
+-------------------------------------------------------+-----------------------+-------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+-----------------------+-------------------------------------------+
| | ``REPOSITORY`` | repository to compact |
+-------------------------------------------------------+-----------------------+-------------------------------------------+
| **optional arguments** |
+-------------------------------------------------------+-----------------------+-------------------------------------------+
| | ``--cleanup-commits`` | cleanup commit-only 17-byte segment files |
+-------------------------------------------------------+-----------------------+-------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+-----------------------+-------------------------------------------+
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| | ``REPOSITORY`` | repository to compact |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| **optional arguments** |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| | ``--cleanup-commits`` | cleanup commit-only 17-byte segment files |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| | ``--threshold PERCENT`` | set minimum threshold for saved space in PERCENT (Default: 10) |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
.. raw:: html
@ -41,7 +43,8 @@ borg compact
optional arguments
--cleanup-commits cleanup commit-only 17-byte segment files
--cleanup-commits cleanup commit-only 17-byte segment files
--threshold PERCENT set minimum threshold for saved space in PERCENT (Default: 10)
:ref:`common_options`
@ -62,6 +65,8 @@ client or also from the server.
Depending on the amount of segments that need compaction, it may take a while,
so consider using the ``--progress`` option.
A segment is compacted if the amount of saved space is above the percentage value
given by the ``--threshold`` option. If ommitted, a threshold of 10% is used.
When using ``--verbose``, borg will output an estimate of the freed space.
After upgrading borg (server) to 1.2+, you can use ``borg compact --cleanup-commits``

7
docs/usage/create.rst.inc
View file

@ -71,7 +71,9 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--nobirthtime`` | do not store birthtime (creation date) into archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--nobsdflags`` | do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive |
| | ``--nobsdflags`` | deprecated, use ``--noflags`` instead |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@ -137,7 +139,8 @@ borg create
--atime do store atime into archive
--noctime do not store ctime into archive
--nobirthtime do not store birthtime (creation date) into archive
--nobsdflags do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive
--nobsdflags deprecated, use ``--noflags`` instead
--noflags do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive
--files-cache MODE operate files cache in MODE. default: ctime,size,inode
--read-special open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.

10
docs/usage/delete.rst.inc
View file

@ -29,6 +29,8 @@ borg delete
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--keep-security-info`` | keep the local security info when deleting a repository |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--save-space`` | work slower, but using less space |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
@ -69,6 +71,7 @@ borg delete
-s, --stats print statistics for the deleted archive
--cache-only delete only the local cache for the given repository
--force force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
--keep-security-info keep the local security info when deleting a repository
--save-space work slower, but using less space
@ -91,9 +94,10 @@ This command deletes an archive from the repository or the complete repository.
Important: When deleting archives, repository disk space is **not** freed until
you run ``borg compact``.
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
``--cache-only`` 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 ``--cache-only`` option, or keep the security info with the
``--keep-security-info`` option.
When using ``--stats``, you will get some statistics about how much data was
deleted - the "Deleted data" deduplicated size there is most interesting as

7
docs/usage/extract.rst.inc
View file

@ -27,7 +27,9 @@ borg extract
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--numeric-owner`` | only obey numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--nobsdflags`` | do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE) |
| | ``--nobsdflags`` | deprecated, use ``--noflags`` instead |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--noflags`` | do not extract/set flags (e.g. NODUMP, IMMUTABLE) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--stdout`` | write all extracted data to stdout |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@ -70,7 +72,8 @@ borg extract
--list output verbose list of items (files, dirs, ...)
-n, --dry-run do not actually change any files
--numeric-owner only obey numeric user and group identifiers
--nobsdflags do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE)
--nobsdflags deprecated, use ``--noflags`` instead
--noflags do not extract/set flags (e.g. NODUMP, IMMUTABLE)
--stdout write all extracted data to stdout
--sparse create holes in output sparse file from all-zero chunks

10
docs/usage/help.rst.inc
View file

@ -96,6 +96,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.
To test your exclusion patterns without performing an actual backup you can
run ``borg create --list --dry-run ...``.
Examples::
# Exclude '/home/user/file.o' but not '/home/user/file.odt':
@ -134,6 +137,13 @@ Examples::
A root path starts with the prefix `R`, followed by a path (a plain path, not a
file pattern). An include rule starts with the prefix +, an exclude rule starts
with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
.. note::
Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
``--exlude-from`` ONLY excludes are defined.
Inclusion patterns are useful to include paths that are contained in an excluded
path. The first matching pattern is used so if an include pattern matches before
an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches

3
docs/usage/list.rst.inc
View file

@ -21,6 +21,8 @@ borg list
+-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). |
+-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--short`` | only print file/directory names, nothing else |
+-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--format FORMAT``, ``--list-format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") |
@ -73,6 +75,7 @@ borg list
optional arguments
--consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden).
--short only print file/directory names, nothing else
--format FORMAT, --list-format FORMAT specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}")
--json Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.

3
docs/usage/mount.rst.inc
View file

@ -23,6 +23,8 @@ borg mount
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-f``, ``--foreground`` | stay in foreground, do not daemonize |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-o`` | Extra mount options |
@ -75,6 +77,7 @@ borg mount
optional arguments
--consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden).
-f, --foreground stay in foreground, do not daemonize
-o Extra mount options