diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 65eb499be..0cdcf0377 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -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. . diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index 8d3b54043..56a2be2e6 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -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 . diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index 989ad9e5d..54bcabb61 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -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. . diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 69241f788..a8ce9a793 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -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. diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 55fa1bc12..02163a150 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -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 diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 6b1118e00..d5a667e07 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -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 . diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index 3b1518846..a3fec6f6a 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -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 . diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index 91dc18fc0..66c1c6de8 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -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 . diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 58a2c2805..30c39aedc 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -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 diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index e87a63ca9..d1b2c98e5 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -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 diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index 52f4ad3bc..af50c2a9e 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -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 . diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 9dcab7109..961c10956 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -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 . diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index f8d91408d..193d3f7df 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -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 diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index 07fd308da..8e4dc3fb3 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -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 . diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index 636ddbb36..85303ba2a 100644 --- a/docs/man/borg-init.1 +++ b/docs/man/borg-init.1 @@ -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 . diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 9d1a6f43d..23f0d822f 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -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 . diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 54bda6ad7..488cbc344 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -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 . diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index e5b78ed42..76e8efc55 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -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 . diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index 5f84da4bd..3d7fe21bb 100644 --- a/docs/man/borg-key-migrate-to-repokey.1 +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -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 . diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index d06888743..843fef71a 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -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 . diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index b426c0046..eb65a0565 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -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 diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 598b0003b..299adc9ab 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -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 diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index a0eacab34..08355ed74 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -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 diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 0e2783972..c5f084093 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -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 . diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index d7b8ccfb7..7eb5ff623 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -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 . diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index f6fcb4cda..eacd14848 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -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 . diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index c70e76125..ecfb80701 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -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 . diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index a44022207..446f11c6e 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -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. . diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 90ac6734d..69a952a3b 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -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 . diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index 48b75891f..a3deb73c1 100644 --- a/docs/man/borg-upgrade.1 +++ b/docs/man/borg-upgrade.1 @@ -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 . diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 81986810f..5393e4f74 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -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 . diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 3a9d5fceb..c5c9b5650 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -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. . diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index c78700329..4aeffe0f4 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -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 diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index 5843fccc9..e6c2717a0 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -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. \ No newline at end of file +tamper-resistant as well, unless the attacker has access to the keys. It is also very +slow. \ No newline at end of file diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc index 07ce07a5b..41fededf1 100644 --- a/docs/usage/common-options.rst.inc +++ b/docs/usage/common-options.rst.inc @@ -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) diff --git a/docs/usage/compact.rst.inc b/docs/usage/compact.rst.inc index 90fb93529..01ae8e0fd 100644 --- a/docs/usage/compact.rst.inc +++ b/docs/usage/compact.rst.inc @@ -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`` diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index e48e41148..effab7abe 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -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. diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index a33a9ae17..060f5e76d 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -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 diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc index 495f20fca..c0e86b0cc 100644 --- a/docs/usage/extract.rst.inc +++ b/docs/usage/extract.rst.inc @@ -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 diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 88c9bf70c..ccc1d2dd0 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -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 diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index b4f6db468..709ca0bc7 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -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. diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index f813f5583..1b297fd1c 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -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