From b419b6ad032bebc5e8e5525826f7508a88f1719f Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Thu, 20 Jul 2023 18:57:22 +0200 Subject: [PATCH] build_man / build_usage --- docs/man/borg-benchmark-crud.1 | 2 +- docs/man/borg-benchmark.1 | 2 +- docs/man/borg-break-lock.1 | 2 +- docs/man/borg-check.1 | 191 ++++++++++++--------- docs/man/borg-common.1 | 2 +- docs/man/borg-compact.1 | 2 +- docs/man/borg-compression.1 | 75 +++++++-- docs/man/borg-config.1 | 2 +- docs/man/borg-create.1 | 24 +-- docs/man/borg-delete.1 | 2 +- docs/man/borg-diff.1 | 4 +- docs/man/borg-export-tar.1 | 4 +- docs/man/borg-extract.1 | 4 +- docs/man/borg-import-tar.1 | 2 +- docs/man/borg-info.1 | 2 +- docs/man/borg-init.1 | 4 +- docs/man/borg-key-change-passphrase.1 | 2 +- docs/man/borg-key-export.1 | 2 +- docs/man/borg-key-import.1 | 2 +- docs/man/borg-key-migrate-to-repokey.1 | 2 +- docs/man/borg-key.1 | 2 +- docs/man/borg-list.1 | 8 +- docs/man/borg-mount.1 | 4 +- docs/man/borg-patterns.1 | 105 ++++++++---- docs/man/borg-placeholders.1 | 2 +- docs/man/borg-prune.1 | 2 +- docs/man/borg-recreate.1 | 4 +- docs/man/borg-rename.1 | 2 +- docs/man/borg-serve.1 | 2 +- docs/man/borg-umount.1 | 2 +- docs/man/borg-upgrade.1 | 2 +- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 34 +++- docs/man/borgfs.1 | 4 +- docs/usage/check.rst.inc | 164 +++++++++++------- docs/usage/create.rst.inc | 224 ++++++++++++------------- docs/usage/diff.rst.inc | 4 +- docs/usage/export-tar.rst.inc | 4 +- docs/usage/extract.rst.inc | 4 +- docs/usage/help.rst.inc | 148 ++++++++++------ docs/usage/init.rst.inc | 2 + docs/usage/list.rst.inc | 4 +- docs/usage/mount.rst.inc | 4 +- docs/usage/prune.rst.inc | 15 +- docs/usage/recreate.rst.inc | 4 +- 45 files changed, 654 insertions(+), 430 deletions(-) diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 34c1cb01e..5d801a74e 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK-CRUD" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-BENCHMARK-CRUD" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index a0127a4ed..beca9e957 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-BENCHMARK" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command .SH SYNOPSIS diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index dad46be9d..05ec89313 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BREAK-LOCK" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-BREAK-LOCK" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. .SH SYNOPSIS diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 4b524b926..f76e031a0 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CHECK" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-CHECK" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency .SH SYNOPSIS @@ -35,94 +35,123 @@ borg-check \- Check repository consistency borg [common options] check [options] [REPOSITORY_OR_ARCHIVE] .SH DESCRIPTION .sp -The check command verifies the consistency of a repository and the corresponding archives. +The check command verifies the consistency of a repository and its archives. +It consists of two major steps: +.INDENT 0.0 +.IP 1. 3 +Checking the consistency of the repository itself. This includes checking +the segment magic headers, and both the metadata and data of all objects in +the segments. The read data is checked by size and CRC. Bit rot and other +types of accidental damage can be detected this way. Running the repository +check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&. +When checking a remote repository, please note that the checks run on the +server and do not cause significant network traffic. +.IP 2. 3 +Checking consistency and correctness of the archive metadata and optionally +archive data (requires \fB\-\-verify\-data\fP). This includes ensuring that the +repository manifest exists, the archive metadata chunk is present, and that +all chunks referencing files (items) in the archive exist. This requires +reading archive and file metadata, but not data. To cryptographically verify +the file (content) data integrity pass \fB\-\-verify\-data\fP, but keep in mind +that this requires reading all data and is hence very time consuming. When +checking archives of a remote repository, archive checks run on the client +machine because they require decrypting data and therefore the encryption +key. +.UNINDENT .sp -check \-\-repair is a potentially dangerous function and might lead to data loss -(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL! +Both steps can also be run independently. Pass \fB\-\-repository\-only\fP to run the +repository checks only, or pass \fB\-\-archives\-only\fP to run the archive checks +only. +.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 full repository has been checked. Assuming a complete check +would take 7 hours, then running a daily check with \fB\-\-max\-duration=3600\fP +(1 hour) would result in one full repository check per week. Doing a full +repository check aborts any previous partial check; the next partial check will +restart from the beginning. With partial repository checks you can run neither +archive checks, nor enable repair mode. Consequently, if you want to use +\fB\-\-max\-duration\fP you must also pass \fB\-\-repository\-only\fP, and must not pass +\fB\-\-archives\-only\fP, nor \fB\-\-repair\fP\&. +.sp +\fBWarning:\fP Please note that partial repository checks (i.e. running it with +\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the +segment files. A full repository check (i.e. without \fB\-\-max\-duration\fP) can +also do a repository index check. Enabling partial repository checks excepts +archive checks for the same reason. Therefore partial checks may be useful with +very large repositories only where a full check would take too long. +.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. It is a complete +cryptographic verification and hence very time consuming, but will detect any +accidental and malicious corruption. Tamper\-resistance is only guaranteed for +encrypted repositories against attackers without access to the keys. You can +not use \fB\-\-verify\-data\fP with \fB\-\-repository\-only\fP\&. +.SS About repair mode +.sp +The check command is a readonly task by default. If any corruption is found, +Borg will report the issue and proceed with checking. To actually repair the +issues found, pass \fB\-\-repair\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fB\-\-repair\fP is a \fBPOTENTIALLY DANGEROUS FEATURE\fP and might lead to data +loss! This does not just include data that was previously lost anyway, but +might include more data for kinds of corruption it is not capable of +dealing with. \fBBE VERY CAREFUL!\fP +.UNINDENT +.UNINDENT .sp Pursuant to the previous warning it is also highly recommended to test the -reliability of the hardware running this software with stress testing software -such as memory testers. Unreliable hardware can also lead to data loss especially -when this command is run in repair mode. +reliability of the hardware running Borg with stress testing software. This +especially includes storage and memory testers. Unreliable hardware might lead +to additional data loss. .sp -First, the underlying repository data files are checked: +It is highly recommended to create a backup of your repository before running +in repair mode (i.e. running it with \fB\-\-repair\fP). +.sp +Repair mode will attempt to fix any corruptions found. Fixing corruptions does +not mean recovering lost data: Borg can not magically restore data lost due to +e.g. a hardware failure. Repairing a repository means sacrificing some data +for the sake of the repository as a whole and the remaining data. Hence it is, +by definition, a potentially lossy task. +.sp +In practice, repair mode hooks into both the repository and archive checks: .INDENT 0.0 -.IP \(bu 2 -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 -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 -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, make sure that the index is consistent with the data stored in -the segments. -.IP \(bu 2 -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. +.IP 1. 3 +When checking the repository\(aqs consistency, repair mode will try to recover +as many objects from segments with integrity errors as possible, and ensure +that the index is consistent with the data stored in the segments. +.IP 2. 3 +When checking the consistency and correctness of archives, repair mode might +remove whole archives from the manifest if their archive metadata chunk is +corrupt or lost. On a chunk level (i.e. the contents of files), repair mode +will replace corrupt or lost chunks with a same\-size replacement chunk of +zeroes. If a previously zeroed chunk reappears, repair mode will restore +this lost chunk using the new chunk. Lastly, repair mode will also delete +orphaned chunks (e.g. caused by read errors while creating the archive). .UNINDENT .sp -Second, the consistency and correctness of the archive metadata is verified: -.INDENT 0.0 -.IP \(bu 2 -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. -.IP \(bu 2 -For all files (items) in the archive, for all chunks referenced by these -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 -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 -In verify\-data mode, a complete cryptographic verification of the archive data -integrity is performed. This conflicts with \fB\-\-repository\-only\fP as this mode -only makes sense if the archive checks are enabled. The full details of this mode -are documented below. -.IP \(bu 2 -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 -\fB\-\-repository\-only\fP option. -.UNINDENT +Most steps taken by repair mode have a one\-time effect on the repository, like +removing a lost archive from the repository. However, replacing a corrupt or +lost chunk with an all\-zero replacement will have an ongoing effect on the +repository: When attempting to extract a file referencing an all\-zero chunk, +the \fBextract\fP command will distinctly warn about it. The FUSE filesystem +created by the \fBmount\fP command will reject reading such a \(dqzero\-patched\(dq +file unless a special mount option is given. .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 complete check took 7 -hours, then running a daily check with \-\-max\-duration=3600 (1 hour) resulted in one -completed check per week. -.sp -Attention: A partial \-\-repository\-only check can only do way less checking than a full -\-\-repository\-only check: only the non\-cryptographic checksum checks on segment file -entries are done, while a full \-\-repository\-only check would also do a repo index check. -A partial check cannot be combined with the \fB\-\-repair\fP option. 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 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. It is also very -slow. +As mentioned earlier, Borg might be able to \(dqheal\(dq a \(dqzero\-patched\(dq file in +repair mode, if all its previously lost chunks reappear (e.g. via a later +backup). This is achieved by Borg not only keeping track of the all\-zero +replacement chunks, but also by keeping metadata about the lost chunks. In +repair mode Borg will check whether a previously lost chunk reappeared and will +replace the all\-zero replacement chunk by the reappeared chunk. If all lost +chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file. +Consequently, if lost chunks were repaired earlier, it is advised to run +\fB\-\-repair\fP a second time after creating some new backups. .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 38c1c441b..9b4619baa 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMMON" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-COMMON" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands .SH SYNOPSIS diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 02f78bcfe..9a76c394d 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPACT" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-COMPACT" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-compact \- compact segment files in the repository .SH SYNOPSIS diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index 9daf0f98e..2a565cab0 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPRESSION" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-COMPRESSION" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression .SH DESCRIPTION @@ -82,29 +82,70 @@ being any valid compression specifier. .TP .B obfuscate,SPEC,C[,L] Use compressed\-size obfuscation to make fingerprinting attacks based on -the observable stored chunk size more difficult. -Note: -\- you must combine this with encryption or it won\(aqt make any sense. -\- your repo size will be bigger, of course. +the observable stored chunk size more difficult. Note: +.INDENT 7.0 +.IP \(bu 2 +You must combine this with encryption, or it won\(aqt make any sense. +.IP \(bu 2 +Your repo size will be bigger, of course. +.IP \(bu 2 +A chunk is limited by the constant \fBMAX_DATA_SIZE\fP (cur. ~20MiB). +.UNINDENT .sp -The SPEC value will determine how the size obfuscation will work: +The SPEC value determines how the size obfuscation works: +.sp +\fIRelative random reciprocal size variation\fP (multiplicative) .sp -Relative random reciprocal size variation: Size will increase by a factor, relative to the compressed data size. -Smaller factors are often used, larger factors rarely. -1: factor 0.01 .. 100.0 -2: factor 0.1 .. 1000.0 -3: factor 1.0 .. 10000.0 -4: factor 10.0 .. 100000.0 -5: factor 100.0 .. 1000000.0 -6: factor 1000.0 .. 10000000.0 +Smaller factors are used often, larger factors rarely. .sp -Add a randomly sized padding up to the given size: -110: 1kiB +Available factors: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +1: 0.01 .. 100 +2: 0.1 .. 1,000 +3: 1 .. 10,000 +4: 10 .. 100,000 +5: 100 .. 1,000,000 +6: 1,000 .. 10,000,000 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Example probabilities for SPEC \fB1\fP: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +90 % 0.01 .. 0.1 + 9 % 0.1 .. 1 + 0.9 % 1 .. 10 + 0.09% 10 .. 100 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fIRandomly sized padding up to the given size\fP (additive) +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +110: 1kiB (2 ^ (SPEC \- 100)) \&... 120: 1MiB \&... 123: 8MiB (max.) +.ft P +.fi +.UNINDENT +.UNINDENT .UNINDENT .sp Examples: @@ -120,7 +161,7 @@ borg create \-\-compression zlib REPO::ARCHIVE data borg create \-\-compression zlib,1 REPO::ARCHIVE data borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data borg create \-\-compression auto,lzma ... -borg create \-\-compression obfuscate,3,none ... +borg create \-\-compression obfuscate,110,none ... borg create \-\-compression obfuscate,3,auto,zstd,10 ... borg create \-\-compression obfuscate,2,zstd,6 ... .ft P diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index d2050a0e8..e0cc8a0e7 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CONFIG" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-CONFIG" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-config \- get, set, and delete values in a repository or cache config file .SH SYNOPSIS diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 92bc4d0d0..0419d36c3 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CREATE" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-CREATE" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-create \- Create new archive .SH SYNOPSIS @@ -169,15 +169,15 @@ set mode to M in archive for stdin data (default: 0660) interpret PATH as command and store its stdout. See also section Reading from stdin below. .TP .B \-\-paths\-from\-stdin -read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories. +read DELIM\-separated list of paths to backup from stdin. All control is external: it will back up all files given \- no more, no less. .TP .B \-\-paths\-from\-command interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP .TP .BI \-\-paths\-delimiter \ DELIM -set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: n) +set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: \fB\en\fP) .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN @@ -208,7 +208,7 @@ exclude files flagged NODUMP .INDENT 0.0 .TP .B \-x\fP,\fB \-\-one\-file\-system -stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. +stay in the same file system and do not store mount points of other file systems \- this might behave different from your expectations, see the description below. .TP .B \-\-numeric\-owner deprecated, use \fB\-\-numeric\-ids\fP instead @@ -376,13 +376,13 @@ through using the \fB\-\-keep\-exclude\-tags\fP option. The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them). It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different -from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories -with device number different from their parent, which the kernel does not consider a mountpoint and also the -other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL -subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when -using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using -btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution -installer. +from the device number of their parent. +In general: be aware that there are directories with device number different from their parent, which the kernel +does not consider a mountpoint and also the other way around. +Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL +subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). +macOS examples are the apfs mounts of a typical macOS installation. +Therefore, when using \fB\-\-one\-file\-system\fP, you should double\-check that the backup works as intended. .SS Item flags .sp \fB\-\-list\fP outputs a list of all files, directories and other diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 0e9fa9101..fd35fc1a0 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DELETE" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-DELETE" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-delete \- Delete an existing repository or archives .SH SYNOPSIS diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index e3e39bbbc..d85366b30 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DIFF" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-DIFF" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives .SH SYNOPSIS @@ -87,7 +87,7 @@ Only compare differences in content (exclude metadata differences) .B \-\-json\-lines Format output as JSON Lines. .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 90e9b5818..bfbe690cd 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXPORT-TAR" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-EXPORT-TAR" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS @@ -100,7 +100,7 @@ filter program to pipe data through .B \-\-list output verbose list of items (files, dirs, ...) .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index a278b56a6..0b2545c57 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXTRACT" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-EXTRACT" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents .SH SYNOPSIS @@ -105,7 +105,7 @@ write all extracted data to stdout .B \-\-sparse create holes in output sparse file from all\-zero chunks .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index 436d98331..9d65e8f69 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-IMPORT-TAR" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-IMPORT-TAR" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index d6102e0ac..4a8c415e9 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-INFO" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-INFO" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used .SH SYNOPSIS diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index 84dae864d..ef66ad84d 100644 --- a/docs/man/borg-init.1 +++ b/docs/man/borg-init.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-INIT" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-INIT" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-init \- Initialize an empty repository .SH SYNOPSIS @@ -124,6 +124,8 @@ The key will be stored in your home directory (in \fB~/.config/borg/keys\fP). .sp If you do \fBnot\fP want to encrypt the contents of your backups, but still want to detect malicious tampering use \fB\-\-encryption authenticated\fP\&. +To normally work with \fBauthenticated\fP repos, you will need the passphrase, but +there is an emergency workaround, see \fBBORG_WORKAROUNDS=authenticated_no_key\fP docs. .sp If \fBBLAKE2b\fP is faster than \fBSHA\-256\fP on your hardware, use \fB\-\-encryption authenticated\-blake2\fP, \fB\-\-encryption repokey\-blake2\fP or \fB\-\-encryption keyfile\-blake2\fP\&. Note: for remote backups diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 4195875cd..4ddef8e3d 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index c5c83bb09..005e8d5fb 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-EXPORT" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-KEY-EXPORT" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup .SH SYNOPSIS diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index 96520d76b..8d513cbcc 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-IMPORT" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-KEY-IMPORT" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup .SH SYNOPSIS diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index dfb9d7b14..c483ee37a 100644 --- a/docs/man/borg-key-migrate-to-repokey.1 +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-key-migrate-to-repokey \- Migrate passphrase -> repokey .SH SYNOPSIS diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 38c8fdcac..0dc91348c 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-KEY" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index 7b5e7f03a..bc3bd55dc 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-LIST" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-LIST" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-list \- List archive or repository contents .SH SYNOPSIS @@ -86,7 +86,7 @@ consider first N archives after other filters were applied .BI \-\-last \ N consider last N archives after other filters were applied .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN @@ -137,11 +137,11 @@ drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text \&... -$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:\e.ext$\(aq +$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:\e.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext \&... -$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:.ext$\(aq +$ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text \&... diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 3fc998f53..b0b5fbe17 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-MOUNT" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-MOUNT" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS @@ -143,7 +143,7 @@ consider first N archives after other filters were applied .BI \-\-last \ N consider last N archives after other filters were applied .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index e082a59e4..096c27ea2 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PATTERNS" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-PATTERNS" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns .SH DESCRIPTION @@ -36,34 +36,20 @@ The path/filenames used as input for the pattern matching start from the currently active recursion root. You usually give the recursion root(s) when invoking borg and these can be either relative or absolute paths. .sp -If you give \fI/absolute/\fP as root, the paths going into the matcher will -look relative like \fIabsolute/.../file.ext\fP, because 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\&. +Starting with Borg 1.2, paths that are matched against patterns always +appear relative. If you give \fB/absolute/\fP as root, the paths going +into the matcher will start with \fBabsolute/\fP\&. +If you give \fB\&../../relative\fP as root, the paths will be normalized +as \fBrelative/\fP\&. .sp A directory exclusion pattern can end either with or without a slash (\(aq/\(aq). If it ends with a slash, such as \fIsome/path/\fP, the directory will be included but not its content. If it does not end with a slash, such as \fIsome/path\fP, both the directory and content will be excluded. .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 \fB\-\-pattern\fP -option. For commands that support patterns in their \fBPATH\fP argument -like (\fBborg list\fP), the default pattern is path prefix. -.sp -Starting with Borg 1.2, discovered fs paths are normalised, have leading -slashes removed and then are matched against your patterns. -Note: You need to review your include / exclude patterns and make -sure they do not expect leading slashes. Borg can only deal with this -for some very simple patterns by removing leading slashes there also. -.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 -non\-default style is desired or when the desired pattern starts with -two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP). +Borg supports different pattern styles. To define a non\-default +style for a specific pattern, prefix it with two characters followed +by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP). .INDENT 0.0 .TP .B \fI\%Fnmatch\fP, selector \fIfm:\fP @@ -186,12 +172,37 @@ $ borg create \-\-exclude\-from exclude.txt backup / .UNINDENT .UNINDENT .sp -A more general and easier to use way to define filename matching patterns exists -with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you may -specify the backup roots (starting points) and patterns for inclusion/exclusion. -A root path starts with the prefix \fIR\fP, 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. +A more general and easier to use way to define filename matching patterns +exists with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using +these, you may specify the backup roots, default pattern styles and +patterns for inclusion and exclusion. +.INDENT 0.0 +.TP +.B Root path prefix \fBR\fP +A recursion root path starts with the prefix \fBR\fP, followed by a path +(a plain path, not a file pattern). Use this prefix to have the root +paths in the patterns file rather than as command line arguments. +.TP +.B Pattern style prefix \fBP\fP +To change the default pattern style, use the \fBP\fP prefix, followed by +the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP). +All patterns following this line will use this style until another style +is specified. +.TP +.B Exclude pattern prefix \fB\-\fP +Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion. +This has the same effect as the \fB\-\-exclude\fP option. +.TP +.B Exclude no\-recurse pattern prefix \fB!\fP +Use the prefix \fB!\fP, followed by a pattern, to define an exclusion +that does not recurse into subdirectories. This saves time, but +prevents include patterns to match any files in subdirectories. +.TP +.B Include pattern prefix \fB+\fP +Use the prefix \fB+\fP, followed by a pattern, to define inclusions. +This is useful to include paths that are covered in an exclude +pattern and would otherwise not be backed up. +.UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 @@ -202,11 +213,37 @@ of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP a .UNINDENT .UNINDENT .sp -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 -a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for -include rules below that directory. +The first matching pattern is used, so if an include pattern matches +before an exclude pattern, the file is backed up. Note that a no\-recurse +exclude stops examination of subdirectories so that potential includes +will not match \- use normal excludes for such use cases. +.sp +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Define the recursion root +R / +# Exclude all iso files in any directory +\- **/*.iso +# Explicitly include all inside etc and root ++ etc/** ++ root/** +# Exclude a specific directory under each user\(aqs home directories +\- home/*/.cache +# Explicitly include everything in /home ++ home/** +# Explicitly exclude some directories without recursing into them +! re:^(dev|proc|run|sys|tmp) +# Exclude all other files and directories +# that are not specifically included earlier. +\- ** +.ft P +.fi +.UNINDENT +.UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 90c072a3a..06ff5512f 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PLACEHOLDERS" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-PLACEHOLDERS" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders .SH DESCRIPTION diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index 0785d3d1c..0c8e98ad2 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PRUNE" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-PRUNE" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules .SH SYNOPSIS diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 5957d9228..f40490d13 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RECREATE" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-RECREATE" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives .SH SYNOPSIS @@ -112,7 +112,7 @@ do not change anything .B \-s\fP,\fB \-\-stats print statistics at end .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index c6fd9096d..5d1685f7b 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RENAME" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-RENAME" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive .SH SYNOPSIS diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index 687315e46..0ee58dc8f 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-SERVE" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-SERVE" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. .SH SYNOPSIS diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index d122a35e9..37605e770 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-UMOUNT" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-UMOUNT" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem .SH SYNOPSIS diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index 23748c994..12ec0013e 100644 --- a/docs/man/borg-upgrade.1 +++ b/docs/man/borg-upgrade.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-UPGRADE" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-UPGRADE" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-upgrade \- upgrade a repository from a previous version .SH SYNOPSIS diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 6c9914c9f..29a024f81 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-WITH-LOCK" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG-WITH-LOCK" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held .SH SYNOPSIS diff --git a/docs/man/borg.1 b/docs/man/borg.1 index a499c49b4..78426c040 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG" 1 "2023-03-22" "" "borg backup tool" +.TH "BORG" 1 "2023-07-20" "" "borg backup tool" .SH NAME borg \- deduplicating and encrypting backup tool .SH SYNOPSIS @@ -507,6 +507,38 @@ write to disk behaviour (not continuously streaming to disk). Retry opening a file without O_NOATIME if opening a file with O_NOATIME caused EROFS. You will need this to make archives from volume shadow copies in WSL1 (Windows Subsystem for Linux 1). +.TP +.B authenticated_no_key +Work around a lost passphrase or key for an \fBauthenticated\fP mode repository +(these are only authenticated, but not encrypted). +If the key is missing in the repository config, add \fBkey = anything\fP there. +.sp +This workaround is \fBonly\fP for emergencies and \fBonly\fP to extract data +from an affected repository (read\-only access): +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +After you have extracted all data you need, you MUST delete the repository: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +BORG_WORKAROUNDS=authenticated_no_key borg delete repo +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now you can init a fresh repo. Make sure you do not use the workaround any more. .UNINDENT .UNINDENT .TP diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index 57c477737..903a646c0 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORGFS" 1 "2023-03-22" "" "borg backup tool" +.TH "BORGFS" 1 "2023-07-20" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS @@ -146,7 +146,7 @@ consider first N archives after other filters were applied .BI \-\-last \ N consider last N archives after other filters were applied .UNINDENT -.SS Exclusion options +.SS Include/Exclude options .INDENT 0.0 .TP .BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc index eebfc5652..71922bd87 100644 --- a/docs/usage/check.rst.inc +++ b/docs/usage/check.rst.inc @@ -85,75 +85,115 @@ borg check Description ~~~~~~~~~~~ -The check command verifies the consistency of a repository and the corresponding archives. +The check command verifies the consistency of a repository and its archives. +It consists of two major steps: -check --repair is a potentially dangerous function and might lead to data loss -(for kinds of corruption it is not capable of dealing with). BE VERY CAREFUL! +1. Checking the consistency of the repository itself. This includes checking + the segment magic headers, and both the metadata and data of all objects in + the segments. The read data is checked by size and CRC. Bit rot and other + types of accidental damage can be detected this way. Running the repository + check can be split into multiple partial checks using ``--max-duration``. + When checking a remote repository, please note that the checks run on the + server and do not cause significant network traffic. + +2. Checking consistency and correctness of the archive metadata and optionally + archive data (requires ``--verify-data``). This includes ensuring that the + repository manifest exists, the archive metadata chunk is present, and that + all chunks referencing files (items) in the archive exist. This requires + reading archive and file metadata, but not data. To cryptographically verify + the file (content) data integrity pass ``--verify-data``, but keep in mind + that this requires reading all data and is hence very time consuming. When + checking archives of a remote repository, archive checks run on the client + machine because they require decrypting data and therefore the encryption + key. + +Both steps can also be run independently. Pass ``--repository-only`` to run the +repository checks only, or pass ``--archives-only`` to run the archive checks +only. + +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 full repository has been checked. Assuming a complete check +would take 7 hours, then running a daily check with ``--max-duration=3600`` +(1 hour) would result in one full repository check per week. Doing a full +repository check aborts any previous partial check; the next partial check will +restart from the beginning. With partial repository checks you can run neither +archive checks, nor enable repair mode. Consequently, if you want to use +``--max-duration`` you must also pass ``--repository-only``, and must not pass +``--archives-only``, nor ``--repair``. + +**Warning:** Please note that partial repository checks (i.e. running it with +``--max-duration``) can only perform non-cryptographic checksum checks on the +segment files. A full repository check (i.e. without ``--max-duration``) can +also do a repository index check. Enabling partial repository checks excepts +archive checks for the same reason. Therefore partial checks may be useful with +very large repositories only where a full check would take too long. + +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. It is a complete +cryptographic verification and hence very time consuming, but will detect any +accidental and malicious corruption. Tamper-resistance is only guaranteed for +encrypted repositories against attackers without access to the keys. You can +not use ``--verify-data`` with ``--repository-only``. + +About repair mode ++++++++++++++++++ + +The check command is a readonly task by default. If any corruption is found, +Borg will report the issue and proceed with checking. To actually repair the +issues found, pass ``--repair``. + +.. note:: + + ``--repair`` is a **POTENTIALLY DANGEROUS FEATURE** and might lead to data + loss! This does not just include data that was previously lost anyway, but + might include more data for kinds of corruption it is not capable of + dealing with. **BE VERY CAREFUL!** Pursuant to the previous warning it is also highly recommended to test the -reliability of the hardware running this software with stress testing software -such as memory testers. Unreliable hardware can also lead to data loss especially -when this command is run in repair mode. +reliability of the hardware running Borg with stress testing software. This +especially includes storage and memory testers. Unreliable hardware might lead +to additional data loss. -First, the underlying repository data files are checked: +It is highly recommended to create a backup of your repository before running +in repair mode (i.e. running it with ``--repair``). -- 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. -- 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. +Repair mode will attempt to fix any corruptions found. Fixing corruptions does +not mean recovering lost data: Borg can not magically restore data lost due to +e.g. a hardware failure. Repairing a repository means sacrificing some data +for the sake of the repository as a whole and the remaining data. Hence it is, +by definition, a potentially lossy task. -Second, the consistency and correctness of the archive metadata is verified: +In practice, repair mode hooks into both the repository and archive checks: -- 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. -- For all files (items) in the archive, for all chunks referenced by these - 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. -- In verify-data mode, a complete cryptographic verification of the archive data - integrity is performed. This conflicts with ``--repository-only`` as this mode - only makes sense if the archive checks are enabled. The full details of this mode - are documented below. -- 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. +1. When checking the repository's consistency, repair mode will try to recover + as many objects from segments with integrity errors as possible, and ensure + that the index is consistent with the data stored in the segments. -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 complete check took 7 -hours, then running a daily check with --max-duration=3600 (1 hour) resulted in one -completed check per week. +2. When checking the consistency and correctness of archives, repair mode might + remove whole archives from the manifest if their archive metadata chunk is + corrupt or lost. On a chunk level (i.e. the contents of files), repair mode + will replace corrupt or lost chunks with a same-size replacement chunk of + zeroes. If a previously zeroed chunk reappears, repair mode will restore + this lost chunk using the new chunk. Lastly, repair mode will also delete + orphaned chunks (e.g. caused by read errors while creating the archive). -Attention: A partial --repository-only check can only do way less checking than a full ---repository-only check: only the non-cryptographic checksum checks on segment file -entries are done, while a full --repository-only check would also do a repo index check. -A partial check cannot be combined with the ``--repair`` option. 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 restart -from the beginning. +Most steps taken by repair mode have a one-time effect on the repository, like +removing a lost archive from the repository. However, replacing a corrupt or +lost chunk with an all-zero replacement will have an ongoing effect on the +repository: When attempting to extract a file referencing an all-zero chunk, +the ``extract`` command will distinctly warn about it. The FUSE filesystem +created by the ``mount`` command will reject reading such a "zero-patched" +file unless a special mount option is given. -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 +As mentioned earlier, Borg might be able to "heal" a "zero-patched" file in +repair mode, if all its previously lost chunks reappear (e.g. via a later +backup). This is achieved by Borg not only keeping track of the all-zero +replacement chunks, but also by keeping metadata about the lost chunks. In +repair mode Borg will check whether a previously lost chunk reappeared and will +replace the all-zero replacement chunk by the reappeared chunk. If all lost +chunks of a "zero-patched" file reappear, this effectively "heals" the file. +Consequently, if lost chunks were repaired earlier, it is advised to run +``--repair`` a second time after creating some new backups. \ No newline at end of file diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 68fa29184..3059d4a8f 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -12,107 +12,107 @@ borg create .. class:: borg-options-table - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``PATH`` | paths to archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **options** | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not create a backup archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-s``, ``--stats`` | print statistics for the created archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--list`` | output verbose list of items (files, dirs, ...) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--filter STATUSCHARS`` | only display items with the given status characters (see description) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--json`` | output stats as JSON. Implies ``--stats``. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies not using the files cache. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'wheel') | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--paths-from-stdin`` | read DELIM-separated list of paths to backup from stdin. Will not recurse into directories. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--exclude-nodump`` | exclude files flagged NODUMP | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Filesystem options** | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--numeric-ids`` | only store numeric user and group identifiers | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noatime`` | do not store atime into archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--atime`` | do store atime into archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noctime`` | do not store ctime into archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--nobirthtime`` | do not store birthtime (creation date) into archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--nobsdflags`` | deprecated, use ``--noflags`` instead | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noacls`` | do not read and store ACLs into archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--noxattrs`` | do not read and store xattrs into archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--sparse`` | detect sparse holes in input (supported only by fixed chunker) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--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. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Archive options** | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--comment COMMENT`` | add a comment text to the archive | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. | - +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``PATH`` | paths to archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **options** | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not create a backup archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics for the created archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of items (files, dirs, ...) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--filter STATUSCHARS`` | only display items with the given status characters (see description) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--json`` | output stats as JSON. Implies ``--stats``. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies not using the files cache. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'wheel') | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--paths-from-stdin`` | read DELIM-separated list of paths to backup from stdin. All control is external: it will back up all files given - no more, no less. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Include/Exclude options** | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--exclude-nodump`` | exclude files flagged NODUMP | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Filesystem options** | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--numeric-ids`` | only store numeric user and group identifiers | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noatime`` | do not store atime into archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--atime`` | do store atime into archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noctime`` | do not store ctime into archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--nobirthtime`` | do not store birthtime (creation date) into archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--nobsdflags`` | deprecated, use ``--noflags`` instead | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noacls`` | do not read and store ACLs into archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--noxattrs`` | do not read and store xattrs into archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--sparse`` | detect sparse holes in input (supported only by fixed chunker) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--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. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | **Archive options** | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--comment COMMENT`` | add a comment text to the archive | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. | + +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -142,15 +142,15 @@ borg create --stdin-group GROUP set group GROUP in archive for stdin data (default: 'wheel') --stdin-mode M set mode to M in archive for stdin data (default: 0660) --content-from-command interpret PATH as command and store its stdout. See also section Reading from stdin below. - --paths-from-stdin read DELIM-separated list of paths to backup from stdin. Will not recurse into directories. + --paths-from-stdin read DELIM-separated list of paths to backup from stdin. All control is external: it will back up all files given - no more, no less. --paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin`` - --paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) + --paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``) :ref:`common_options` | - Exclusion options + Include/Exclude options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line --pattern PATTERN include/exclude paths matching PATTERN @@ -162,7 +162,7 @@ borg create Filesystem options - -x, --one-file-system stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. + -x, --one-file-system stay in the same file system and do not store mount points of other file systems - this might behave different from your expectations, see the description below. --numeric-owner deprecated, use ``--numeric-ids`` instead --numeric-ids only store numeric user and group identifiers --noatime do not store atime into archive @@ -282,13 +282,13 @@ through using the ``--keep-exclude-tags`` option. The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them). It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different -from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories -with device number different from their parent, which the kernel does not consider a mountpoint and also the -other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL -subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when -using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using -btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution -installer. +from the device number of their parent. +In general: be aware that there are directories with device number different from their parent, which the kernel +does not consider a mountpoint and also the other way around. +Linux examples for this are bind mounts (possibly same device number, but always a mountpoint) and ALL +subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). +macOS examples are the apfs mounts of a typical macOS installation. +Therefore, when using ``--one-file-system``, you should double-check that the backup works as intended. .. _list_item_flags: diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc index d527f0c16..4bad260bb 100644 --- a/docs/usage/diff.rst.inc +++ b/docs/usage/diff.rst.inc @@ -39,7 +39,7 @@ borg diff | | | :ref:`common_options` | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ - | **Exclusion options** | + | **Include/Exclude options** | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ @@ -80,7 +80,7 @@ borg diff :ref:`common_options` | - Exclusion options + Include/Exclude options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line --pattern PATTERN include/exclude paths matching PATTERN diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc index a8f43184c..cabfec740 100644 --- a/docs/usage/export-tar.rst.inc +++ b/docs/usage/export-tar.rst.inc @@ -31,7 +31,7 @@ borg export-tar | | | :ref:`common_options` | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | + | **Include/Exclude options** | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -70,7 +70,7 @@ borg export-tar :ref:`common_options` | - Exclusion options + Include/Exclude options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line --pattern PATTERN include/exclude paths matching PATTERN diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc index 22a39f202..c928209f9 100644 --- a/docs/usage/extract.rst.inc +++ b/docs/usage/extract.rst.inc @@ -45,7 +45,7 @@ borg extract | | | :ref:`common_options` | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | + | **Include/Exclude options** | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -90,7 +90,7 @@ borg extract :ref:`common_options` | - Exclusion options + Include/Exclude options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line --pattern PATTERN include/exclude paths matching PATTERN diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 18e36f207..cdb60855b 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -10,34 +10,20 @@ The path/filenames used as input for the pattern matching start from the currently active recursion root. You usually give the recursion root(s) when invoking borg and these can be either relative or absolute paths. -If you give `/absolute/` as root, the paths going into the matcher will -look relative like `absolute/.../file.ext`, because file paths in Borg -archives are always stored normalized and relative. This means that e.g. -``borg create /path/to/repo ../some/path`` will store all files as -`some/path/.../file.ext` and ``borg create /path/to/repo /home/user`` -will store all files as `home/user/.../file.ext`. +Starting with Borg 1.2, paths that are matched against patterns always +appear relative. If you give ``/absolute/`` as root, the paths going +into the matcher will start with ``absolute/``. +If you give ``../../relative`` as root, the paths will be normalized +as ``relative/``. A directory exclusion pattern can end either with or without a slash ('/'). If it ends with a slash, such as `some/path/`, the directory will be included but not its content. If it does not end with a slash, such as `some/path`, both the directory and content will be excluded. -File patterns support these styles: fnmatch, shell, regular expressions, -path prefixes and path full-matches. By default, fnmatch is used for -``--exclude`` patterns and shell-style is used for the ``--pattern`` -option. For commands that support patterns in their ``PATH`` argument -like (``borg list``), the default pattern is path prefix. - -Starting with Borg 1.2, discovered fs paths are normalised, have leading -slashes removed and then are matched against your patterns. -Note: You need to review your include / exclude patterns and make -sure they do not expect leading slashes. Borg can only deal with this -for some very simple patterns by removing leading slashes there also. - -If followed by a colon (':') 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. `aa:something/*`). +Borg supports different pattern styles. To define a non-default +style for a specific pattern, prefix it with two characters followed +by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``). `Fnmatch `_, selector `fm:` This is the default style for ``--exclude`` and ``--exclude-from``. @@ -147,12 +133,35 @@ Examples:: EOF $ borg create --exclude-from exclude.txt backup / -A more general and easier to use way to define filename matching patterns exists -with the ``--pattern`` and ``--patterns-from`` options. Using these, you may -specify the backup roots (starting points) and patterns for inclusion/exclusion. -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. +A more general and easier to use way to define filename matching patterns +exists with the ``--pattern`` and ``--patterns-from`` options. Using +these, you may specify the backup roots, default pattern styles and +patterns for inclusion and exclusion. + +Root path prefix ``R`` + A recursion root path starts with the prefix ``R``, followed by a path + (a plain path, not a file pattern). Use this prefix to have the root + paths in the patterns file rather than as command line arguments. + +Pattern style prefix ``P`` + To change the default pattern style, use the ``P`` prefix, followed by + the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``). + All patterns following this line will use this style until another style + is specified. + +Exclude pattern prefix ``-`` + Use the prefix ``-``, followed by a pattern, to define an exclusion. + This has the same effect as the ``--exclude`` option. + +Exclude no-recurse pattern prefix ``!`` + Use the prefix ``!``, followed by a pattern, to define an exclusion + that does not recurse into subdirectories. This saves time, but + prevents include patterns to match any files in subdirectories. + +Include pattern prefix ``+`` + Use the prefix ``+``, followed by a pattern, to define inclusions. + This is useful to include paths that are covered in an exclude + pattern and would otherwise not be backed up. .. note:: @@ -160,11 +169,29 @@ with the prefix -, an exclude-norecurse rule starts with !, all followed by a pa of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and ``--exclude-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 -a directory, it won't recurse into it and won't discover any potential matches for -include rules below that directory. +The first matching pattern is used, so if an include pattern matches +before an exclude pattern, the file is backed up. Note that a no-recurse +exclude stops examination of subdirectories so that potential includes +will not match - use normal excludes for such use cases. + +Example:: + + # Define the recursion root + R / + # Exclude all iso files in any directory + - **/*.iso + # Explicitly include all inside etc and root + + etc/** + + root/** + # Exclude a specific directory under each user's home directories + - home/*/.cache + # Explicitly include everything in /home + + home/** + # Explicitly exclude some directories without recursing into them + ! re:^(dev|proc|run|sys|tmp) + # Exclude all other files and directories + # that are not specifically included earlier. + - ** .. note:: @@ -346,29 +373,44 @@ auto,C[,L] obfuscate,SPEC,C[,L] Use compressed-size obfuscation to make fingerprinting attacks based on - the observable stored chunk size more difficult. - Note: - - you must combine this with encryption or it won't make any sense. - - your repo size will be bigger, of course. + the observable stored chunk size more difficult. Note: - The SPEC value will determine how the size obfuscation will work: + - You must combine this with encryption, or it won't make any sense. + - Your repo size will be bigger, of course. + - A chunk is limited by the constant ``MAX_DATA_SIZE`` (cur. ~20MiB). + + The SPEC value determines how the size obfuscation works: + + *Relative random reciprocal size variation* (multiplicative) - Relative random reciprocal size variation: Size will increase by a factor, relative to the compressed data size. - Smaller factors are often used, larger factors rarely. - 1: factor 0.01 .. 100.0 - 2: factor 0.1 .. 1000.0 - 3: factor 1.0 .. 10000.0 - 4: factor 10.0 .. 100000.0 - 5: factor 100.0 .. 1000000.0 - 6: factor 1000.0 .. 10000000.0 + Smaller factors are used often, larger factors rarely. - Add a randomly sized padding up to the given size: - 110: 1kiB - ... - 120: 1MiB - ... - 123: 8MiB (max.) + Available factors:: + + 1: 0.01 .. 100 + 2: 0.1 .. 1,000 + 3: 1 .. 10,000 + 4: 10 .. 100,000 + 5: 100 .. 1,000,000 + 6: 1,000 .. 10,000,000 + + Example probabilities for SPEC ``1``:: + + 90 % 0.01 .. 0.1 + 9 % 0.1 .. 1 + 0.9 % 1 .. 10 + 0.09% 10 .. 100 + + *Randomly sized padding up to the given size* (additive) + + :: + + 110: 1kiB (2 ^ (SPEC - 100)) + ... + 120: 1MiB + ... + 123: 8MiB (max.) Examples:: @@ -379,7 +421,7 @@ Examples:: borg create --compression zlib,1 REPO::ARCHIVE data borg create --compression auto,lzma,6 REPO::ARCHIVE data borg create --compression auto,lzma ... - borg create --compression obfuscate,3,none ... + borg create --compression obfuscate,110,none ... borg create --compression obfuscate,3,auto,zstd,10 ... borg create --compression obfuscate,2,zstd,6 ... diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc index 8dde989de..265a491a2 100644 --- a/docs/usage/init.rst.inc +++ b/docs/usage/init.rst.inc @@ -128,6 +128,8 @@ The key will be stored in your home directory (in ``~/.config/borg/keys``). If you do **not** want to encrypt the contents of your backups, but still want to detect malicious tampering use ``--encryption authenticated``. +To normally work with ``authenticated`` repos, you will need the passphrase, but +there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` docs. If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``, ``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index ed0957c23..915daa803 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -47,7 +47,7 @@ borg list +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--last N`` | consider last N archives after other filters were applied | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | + | **Include/Exclude options** | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -93,7 +93,7 @@ borg list --last N consider last N archives after other filters were applied - Exclusion options + Include/Exclude options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line --pattern PATTERN include/exclude paths matching PATTERN diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index e72b758cc..1eb9c16ed 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -49,7 +49,7 @@ borg mount +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--last N`` | consider last N archives after other filters were applied | +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | + | **Include/Exclude options** | +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -99,7 +99,7 @@ borg mount --last N consider last N archives after other filters were applied - Exclusion options + Include/Exclude options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line --pattern PATTERN include/exclude paths matching PATTERN diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 90f1d7396..48cd3c4c3 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -126,6 +126,12 @@ If you have multiple sequences of archives with different data sets (e.g. from different machines) in one shared repository, use one prune call per data set that matches only the respective archives using the -P option. +The ``--keep-within`` option takes an argument of the form "", +where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means +to keep all archives that were created within the past 48 hours. +"1m" is taken to mean "31d". The archives kept with this option do not +count towards the totals specified by any other options. + A good procedure is to thin out more and more the older your backups get. As an example, ``--keep-daily 7`` means to keep the latest backup on each day, up to 7 most recent days with backups (days without backups do not count). @@ -139,13 +145,6 @@ hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet its retention target. This enables the first chronological archive to continue aging until it is replaced by a newer archive that meets the retention criteria. -The ``--keep-within`` option takes an argument of the form "", -where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means -to keep all archives that were created within the past 48 hours. -"1m" is taken to mean "31d". This option is applied before the secondly option -and like the other options any archives kept by this option do not count towards -the later rules. - The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will keep the last N archives under the assumption that you do not create more than one backup archive in the same second). @@ -153,4 +152,4 @@ backup archive in the same second). When using ``--stats``, you will get some statistics about how much data was deleted - the "Deleted data" deduplicated size there is most interesting as that is how much your repository will shrink. -Please note that the "All archives" stats refer to the state after pruning. +Please note that the "All archives" stats refer to the state after pruning. \ No newline at end of file diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index e55edc032..22a6dc908 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -33,7 +33,7 @@ borg recreate | | | :ref:`common_options` | +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | **Exclusion options** | + | **Include/Exclude options** | +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -92,7 +92,7 @@ borg recreate :ref:`common_options` | - Exclusion options + Include/Exclude options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line --pattern PATTERN include/exclude paths matching PATTERN