upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-06-09 00:32:37 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

build_man

Browse source
This commit is contained in:
Thomas Waldmann 2020-06-06 02:01:49 +02:00
parent 29bd87d224
commit 93c3776e40
32 changed files with 92 additions and 70 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 "2020-03-07" "" "borg backup tool"
.TH BORG-BENCHMARK-CRUD 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-BENCHMARK 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-BREAK-LOCK 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.

2
docs/man/borg-change-passphrase.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHANGE-PASSPHRASE 1 "2020-03-07" "" "borg backup tool"
.TH BORG-CHANGE-PASSPHRASE 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-change-passphrase \- Change repository key file passphrase
.

51
docs/man/borg-check.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHECK 1 "2020-03-07" "" "borg backup tool"
.TH BORG-CHECK 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.
@ -40,20 +40,20 @@ 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.
.UNINDENT
@ -64,26 +64,24 @@ 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
@ -91,9 +89,8 @@ The \fB\-\-verify\-data\fP option will perform a full integrity verification (as
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 "2020-03-07" "" "borg backup tool"
.TH BORG-COMMON 1 "2020-06-06" "" "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-compression.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPRESSION 1 "2020-03-07" "" "borg backup tool"
.TH BORG-COMPRESSION 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-CONFIG 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-config \- get, set, and delete values in a repository or cache config file
.

2
docs/man/borg-create.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CREATE 1 "2020-03-07" "" "borg backup tool"
.TH BORG-CREATE 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.

2
docs/man/borg-delete.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DELETE 1 "2020-03-07" "" "borg backup tool"
.TH BORG-DELETE 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.

2
docs/man/borg-diff.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DIFF 1 "2020-03-07" "" "borg backup tool"
.TH BORG-DIFF 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-EXPORT-TAR 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.

2
docs/man/borg-extract.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXTRACT 1 "2020-03-07" "" "borg backup tool"
.TH BORG-EXTRACT 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.

2
docs/man/borg-info.1
View file

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

25
docs/man/borg-init.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INIT 1 "2020-03-07" "" "borg backup tool"
.TH BORG-INIT 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.
@ -43,7 +43,11 @@ Encryption can be enabled at repository init time. It cannot be changed later.
It is not recommended to work without encryption. Repository encryption protects
you e.g. against the case that an attacker has access to your backup repository.
.sp
But be careful with the key / the passphrase:
Borg relies on randomly generated key material and uses that for chunking, id
generation, encryption and authentication. The key material is encrypted using
the passphrase you give before it is stored on\-disk.
.sp
You need to be careful with the key / the passphrase:
.sp
If you want "passphrase\-only" security, use one of the repokey modes. The
key will be stored inside the repository (in its "config" file). In above
@ -81,6 +85,12 @@ a different keyboard layout.
You can change your passphrase for existing repos at any time, it won\(aqt affect
the encryption/decryption key or other secrets.
.SS Encryption modes
.sp
You can choose from the encryption modes seen in the table below on a per\-repo
basis. The mode determines encryption algorithm, hash/MAC algorithm and also the
key storage location.
.sp
Example: \fIborg init \-\-encryption repokey ...\fP
.\" nanorst: inline-fill
.
.TS
@ -126,7 +136,8 @@ _
.\" nanorst: inline-replace
.
.sp
\fIMarked modes\fP are new in Borg 1.1 and are not backwards\-compatible with Borg 1.0.x.
Modes \fImarked like this\fP in the above table are new in Borg 1.1 and are not
backwards\-compatible with Borg 1.0.x.
.sp
On modern Intel/AMD CPUs (except very cheap ones), AES is usually
hardware\-accelerated.
@ -159,8 +170,8 @@ from the other blake2 modes.
This mode is new and \fInot\fP compatible with Borg 1.0.x.
.sp
\fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk
ID hash. Not recommended, rather consider using an authenticated or
authenticated/encrypted mode. This mode has possible denial\-of\-service issues
ID hash. This mode is not recommended, you should rather consider using an authenticated
or authenticated/encrypted mode. This mode has possible denial\-of\-service issues
when running \fBborg create\fP on contents controlled by an attacker.
Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility
with 1.0.x is important. If compatibility with 1.0.x is not important, use
@ -203,9 +214,11 @@ $ borg init \-\-encryption=repokey\-blake2 /path/to/repo
$ borg init \-\-encryption=none /path/to/repo
# Remote repository (accesses a remote borg via ssh)
# repokey: stores the (encrypted) key into <REPO_DIR>/config
$ borg init \-\-encryption=repokey\-blake2 user@hostname:backup
# Remote repository (store the key your home dir)
# Remote repository (accesses a remote borg via ssh)
# keyfile: stores the (encrypted) key into ~/.config/borg/keys/
$ borg init \-\-encryption=keyfile user@hostname:backup
.ft P
.fi

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 "2020-03-07" "" "borg backup tool"
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-KEY-EXPORT 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-KEY-IMPORT 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-KEY 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.

2
docs/man/borg-list.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-LIST 1 "2020-03-07" "" "borg backup tool"
.TH BORG-LIST 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.

2
docs/man/borg-mount.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-MOUNT 1 "2020-03-07" "" "borg backup tool"
.TH BORG-MOUNT 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.

25
docs/man/borg-patterns.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PATTERNS 1 "2020-03-07" "" "borg backup tool"
.TH BORG-PATTERNS 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.
@ -37,17 +37,26 @@ currently active recursion root. You usually give the recursion root(s)
when invoking borg and these can be either relative or absolute paths.
.sp
So, when you give \fIrelative/\fP as root, the paths going into the matcher
will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as root,
they will look like \fI/absolute/.../file.ext\fP\&. This is meant when we talk
about "full path" below.
will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as
root, they will look like \fI/absolute/.../file.ext\fP\&. This is meant when
we talk about "full path" below.
.sp
File paths in Borg archives are always stored normalized and relative.
This means that e.g. \fBborg create /path/to/repo ../some/path\fP will
store all files as \fIsome/path/.../file.ext\fP and \fBborg create
/path/to/repo /home/user\fP will store all files as
\fIhome/user/.../file.ext\fP\&. Therefore, always use relative paths in your
patterns when matching archive content in commands like \fBextract\fP or
\fBmount\fP\&. Starting with Borg 1.2 this behaviour will be changed to
accept both absolute and relative paths.
.sp
File patterns support these styles: fnmatch, shell, regular expressions,
path prefixes and path full\-matches. By default, fnmatch is used for
\fB\-\-exclude\fP patterns and shell\-style is used for the experimental \fB\-\-pattern\fP
option.
\fB\-\-exclude\fP patterns and shell\-style is used for the experimental
\fB\-\-pattern\fP option.
.sp
If followed by a colon (\(aq:\(aq) the first two characters of a pattern are used as a
style selector. Explicit style selection is necessary when a
If followed by a colon (\(aq:\(aq) the first two characters of a pattern are
used as a style selector. Explicit style selection is necessary when a
non\-default style is desired or when the desired pattern starts with
two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
.INDENT 0.0

2
docs/man/borg-placeholders.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PLACEHOLDERS 1 "2020-03-07" "" "borg backup tool"
.TH BORG-PLACEHOLDERS 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-PRUNE 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-RECREATE 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-RENAME 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-SERVE 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-UMOUNT 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-UPGRADE 1 "2020-06-06" "" "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 "2020-03-07" "" "borg backup tool"
.TH BORG-WITH-LOCK 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.

2
docs/man/borgfs.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORGFS 1 "2020-03-07" "" "borg backup tool"
.TH BORGFS 1 "2020-06-06" "" "borg backup tool"
.SH NAME
borgfs \- Mount archive or an entire repository as a FUSE filesystem
.