diff --git a/docs/changes.rst b/docs/changes.rst index 332b7e0e2..0ec1ffeba 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -212,8 +212,8 @@ The best check that everything is ok is to run a dry-run extraction:: Changelog ========= -Version 1.1.11 (not released yet) ---------------------------------- +Version 1.1.11 (2020-03-08) +--------------------------- Compatibility notes: @@ -245,6 +245,7 @@ Fixes: mode, where unaligned memory accesses cause bus errors. 0.7.3 adds some speedups and libxxhash 0.7.3 even has a pkg-config file now. - upgrade bundled lz4 to 1.9.2 +- upgrade bundled zstd to 1.4.4 - fix crash when upgrading erroneous hints file, #4922 - extract: diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index e1fd4a8cd..9b21821a2 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK-CRUD 1 "2019-05-16" "" "borg backup tool" +.TH BORG-BENCHMARK-CRUD 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg [common options] benchmark crud [options] REPO PATH +borg [common options] benchmark crud [options] REPOSITORY PATH .SH DESCRIPTION .sp This command benchmarks borg CRUD (create, read, update, delete) operations. @@ -44,8 +44,16 @@ command will create / read / update / delete some archives named borg\-benchmark Make sure you have free space there, you\(aqll need about 1GB each (+ overhead). .sp If your repository is encrypted and borg needs a passphrase to unlock the key, use: +.INDENT 0.0 +.INDENT 3.5 .sp +.nf +.ft C BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH +.ft P +.fi +.UNINDENT +.UNINDENT .sp Measurements are done with different input file sizes and counts. The file contents are very artificial (either all zero or all random), @@ -80,8 +88,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B REPO -repo to use for benchmark (must exist) +.B REPOSITORY +repository to use for benchmark (must exist) .TP .B PATH path were to create benchmark input data diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index a461c36e0..0f435aaeb 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK 1 "2019-05-16" "" "borg backup tool" +.TH BORG-BENCHMARK 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command . diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index b5d283348..55d0e9edd 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BREAK-LOCK 1 "2019-05-16" "" "borg backup tool" +.TH BORG-BREAK-LOCK 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. . diff --git a/docs/man/borg-change-passphrase.1 b/docs/man/borg-change-passphrase.1 index 52b9f8fcf..c6c1b8bef 100644 --- a/docs/man/borg-change-passphrase.1 +++ b/docs/man/borg-change-passphrase.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHANGE-PASSPHRASE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-CHANGE-PASSPHRASE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-change-passphrase \- Change repository key file passphrase . diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 91b7a25a1..0023829bb 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHECK 1 "2019-05-16" "" "borg backup tool" +.TH BORG-CHECK 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency . diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 8e3348df4..7db1ea11c 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMMON 1 "2019-05-16" "" "borg backup tool" +.TH BORG-COMMON 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands . diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index b55dc9d19..502fd1f03 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPRESSION 1 "2019-05-16" "" "borg backup tool" +.TH BORG-COMPRESSION 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression . diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index 97cef4463..1069040d2 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CONFIG 1 "2019-05-16" "" "borg backup tool" +.TH BORG-CONFIG 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-config \- get, set, and delete values in a repository or cache config file . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg [common options] config [options] REPOSITORY [NAME] [VALUE] +borg [common options] config [options] [REPOSITORY] [NAME] [VALUE] .SH DESCRIPTION .sp This command gets and sets options in a local repository or cache config file. diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 23f1c2d80..a452dafb8 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CREATE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-CREATE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-create \- Create new archive . @@ -290,7 +290,7 @@ $ borg create \-\-compression auto,lzma,N /path/to/repo::arch ~ # Use short hostname, user name and current time in archive name $ borg create /path/to/repo::{hostname}\-{user}\-{now} ~ -# Similar, use the same datetime format as borg 1.1 will have as default +# Similar, use the same datetime format that is default as of borg 1.1 $ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S} ~ # As above, but add nanoseconds $ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~ diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 2edecae34..33d98932c 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DELETE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-DELETE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-delete \- Delete an existing repository or archives . @@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg [common options] delete [options] [TARGET] [ARCHIVE...] +borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...] .SH DESCRIPTION .sp This command deletes an archive from the repository or the complete repository. @@ -49,8 +49,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B TARGET -archive or repository to delete +.B REPOSITORY_OR_ARCHIVE +repository or archive to delete .TP .B ARCHIVE archives to delete diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index a67f79517..487096173 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DIFF 1 "2019-05-16" "" "borg backup tool" +.TH BORG-DIFF 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives . diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index f79cebc13..8ed140f34 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXPORT-TAR 1 "2019-05-16" "" "borg backup tool" +.TH BORG-EXPORT-TAR 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball . diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 77530981f..e2af3a9bc 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXTRACT 1 "2019-05-16" "" "borg backup tool" +.TH BORG-EXTRACT 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents . diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index fd3e6c2f9..c20217f68 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INFO 1 "2019-05-16" "" "borg backup tool" +.TH BORG-INFO 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used . @@ -57,7 +57,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .INDENT 0.0 .TP .B REPOSITORY_OR_ARCHIVE -archive or repository to display information about +repository or archive to display information about .UNINDENT .SS optional arguments .INDENT 0.0 diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index a607749e2..bb95b1eb0 100644 --- a/docs/man/borg-init.1 +++ b/docs/man/borg-init.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INIT 1 "2019-05-16" "" "borg backup tool" +.TH BORG-INIT 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-init \- Initialize an empty repository . diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 7dc674c85..b5730d62b 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase . diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index fa4029259..d599d9095 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-EXPORT 1 "2019-05-16" "" "borg backup tool" +.TH BORG-KEY-EXPORT 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup . diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index df6755388..5dc8f3d62 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-IMPORT 1 "2019-05-16" "" "borg backup tool" +.TH BORG-KEY-IMPORT 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup . diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index 8ea266a70..de76764c1 100644 --- a/docs/man/borg-key-migrate-to-repokey.1 +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2019-05-16" "" "borg backup tool" +.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-key-migrate-to-repokey \- Migrate passphrase -> repokey . diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index f4ce2d07e..0d5fa55ac 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY 1 "2019-05-16" "" "borg backup tool" +.TH BORG-KEY 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository . diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index 95c080538..4d0aada2d 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-LIST 1 "2019-05-16" "" "borg backup tool" +.TH BORG-LIST 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-list \- List archive or repository contents . @@ -45,7 +45,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .INDENT 0.0 .TP .B REPOSITORY_OR_ARCHIVE -repository/archive to list contents of +repository or archive to list contents of .TP .B PATH paths to list; patterns are supported diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index d613cc57a..21021b6b0 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-MOUNT 1 "2019-05-16" "" "borg backup tool" +.TH BORG-MOUNT 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem . @@ -82,7 +82,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .INDENT 0.0 .TP .B REPOSITORY_OR_ARCHIVE -repository/archive to mount +repository or archive to mount .TP .B MOUNTPOINT where to mount filesystem diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 1ac1b4618..1677882eb 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PATTERNS 1 "2019-05-16" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . @@ -127,6 +127,9 @@ selector prefix is also supported for patterns loaded from a file. Due to whitespace removal paths with whitespace at the beginning or end can only be excluded using regular expressions. .sp +To test your exclusion patterns without performing an actual backup you can +run \fBborg create \-\-list \-\-dry\-run ...\fP\&. +.sp Examples: .INDENT 0.0 .INDENT 3.5 @@ -170,6 +173,16 @@ may specify the backup roots (starting points) and patterns for inclusion/exclus 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. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Via \fB\-\-pattern\fP or \fB\-\-patterns\-from\fP you can define BOTH inclusion and exclusion +of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP and +\fB\-\-exlude\-from\fP ONLY excludes are defined. +.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 @@ -219,6 +232,8 @@ R / + /home/susan # don\(aqt backup the other home directories \- /home/* +# don\(aqt even look in /proc +! /proc .ft P .fi .UNINDENT diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 9ffca4116..da56aa618 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PLACEHOLDERS 1 "2019-05-16" "" "borg backup tool" +.TH BORG-PLACEHOLDERS 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders . diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index e1af47134..b7072da6a 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PRUNE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-PRUNE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules . diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 341f05ccf..876d38b1a 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RECREATE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-RECREATE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives . @@ -89,7 +89,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .INDENT 0.0 .TP .B REPOSITORY_OR_ARCHIVE -repository/archive to recreate +repository or archive to recreate .TP .B PATH paths to recreate; patterns are supported diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 9b33de280..b6789a549 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RENAME 1 "2019-05-16" "" "borg backup tool" +.TH BORG-RENAME 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive . diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index 46ce2a34f..d4c704f78 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-SERVE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-SERVE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. . diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index a01c5d0bd..3e0220b59 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-UMOUNT 1 "2019-05-16" "" "borg backup tool" +.TH BORG-UMOUNT 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem . diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index 6068b82b6..fa0eca904 100644 --- a/docs/man/borg-upgrade.1 +++ b/docs/man/borg-upgrade.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-UPGRADE 1 "2019-05-16" "" "borg backup tool" +.TH BORG-UPGRADE 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-upgrade \- upgrade a repository from a previous version . @@ -100,7 +100,12 @@ from scratch, use \fIborg delete\fP over the copied repository to make sure the cache files are also removed: .INDENT 0.0 .INDENT 3.5 +.sp +.nf +.ft C borg delete borg +.ft P +.fi .UNINDENT .UNINDENT .sp diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 534f92deb..df7d44a5b 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-WITH-LOCK 1 "2019-05-16" "" "borg backup tool" +.TH BORG-WITH-LOCK 1 "2020-03-07" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held . diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 5aa4b3c19..2d9d3078b 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -451,6 +451,21 @@ When set to no (default: yes), system information (like OS, Python version, ...) exceptions is not shown. Please only use for good reasons as it makes issues harder to analyze. .TP +.B BORG_WORKAROUNDS +A list of comma separated strings that trigger workarounds in borg, +e.g. to work around bugs in other software. +.sp +Currently known strings are: +.INDENT 7.0 +.TP +.B basesyncfile +Use the more simple BaseSyncFile code to avoid issues with sync_file_range. +You might need this to run borg on WSL (Windows Subsystem for Linux) or +in systemd.nspawn containers on some architectures (e.g. ARM). +Using this does not affect data safety, but might result in a more bursty +write to disk behaviour (not continuously streaming to disk). +.UNINDENT +.TP .B TMPDIR where temporary files are stored (might need a lot of temporary space for some operations), see \fI\%tempfile\fP for details .UNINDENT @@ -485,17 +500,18 @@ allowed). So please test your scripts interactively before making them a non\-in Default to \(aq$HOME\(aq, \(aq~$USER\(aq, \(aq~\(aq (in that order)\(aq. If we refer to ~ below, we in fact mean BORG_BASE_DIR. .TP -.B BORG_CONFIG_DIR -Default to \(aq~/.config/borg\(aq. This directory contains the whole config directories. -.TP .B BORG_CACHE_DIR Default to \(aq~/.cache/borg\(aq. This directory contains the local cache and might need a lot -of space for dealing with big repositories. +of space for dealing with big repositories. Make sure you\(aqre aware of the associated +security aspects of the cache location: \fIcache_security\fP +.TP +.B BORG_CONFIG_DIR +Default to \(aq~/.config/borg\(aq. This directory contains the whole config directories. .TP .B BORG_SECURITY_DIR Default to \(aq~/.config/borg/security\(aq. This directory contains information borg uses to track its usage of NONCES ("numbers used once" \- usually in encryption context) and other -security relevant data. +security relevant data. Will move with BORG_CONFIG_DIR variable unless specified. .TP .B BORG_KEYS_DIR Default to \(aq~/.config/borg/keys\(aq. This directory contains keys for encrypted repositories. @@ -658,7 +674,16 @@ the size of all deduplicated, small chunks in the repository. Big chunks won\(aqt be locally cached. .TP .B Temporary files (server): -None. +A non\-trivial amount of data will be stored on the remote temp directory +for each client that connects to it. For some remotes, this can fill the +default temporary directory at /tmp. This can be remediated by ensuring the +$TMPDIR, $TEMP, or $TMP environment variable is properly set for the sshd +process. +For some OSes, this can be done just by setting the correct value in the +.bashrc (or equivalent login config file for other shells), however in +other cases it may be neccessary to first enable \fBPermitUserEnvironment yes\fP +in your \fBsshd_config\fP file, then add \fBenvironment="TMPDIR=/my/big/tmpdir"\fP +at the start of the public key to be used in the \fBauthorized_hosts\fP file. .TP .B Cache files (client only): Contains the chunks index and files index (plus a collection of single\- diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index 0020c2c61..f290975b4 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORGFS 1 "2019-05-16" "" "borg backup tool" +.TH BORGFS 1 "2020-03-07" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem . @@ -82,7 +82,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .INDENT 0.0 .TP .B REPOSITORY_OR_ARCHIVE -repository/archive to mount +repository or archive to mount .TP .B MOUNTPOINT where to mount filesystem diff --git a/docs/usage/benchmark_crud.rst.inc b/docs/usage/benchmark_crud.rst.inc index 0aa3bfb69..3e67d7b6b 100644 --- a/docs/usage/benchmark_crud.rst.inc +++ b/docs/usage/benchmark_crud.rst.inc @@ -6,23 +6,23 @@ borg benchmark crud ------------------- .. code-block:: none - borg [common options] benchmark crud [options] REPO PATH + borg [common options] benchmark crud [options] REPOSITORY PATH .. only:: html .. class:: borg-options-table - +-------------------------------------------------------+----------+------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+----------+------------------------------------------+ - | | ``REPO`` | repo to use for benchmark (must exist) | - +-------------------------------------------------------+----------+------------------------------------------+ - | | ``PATH`` | path were to create benchmark input data | - +-------------------------------------------------------+----------+------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+----------+------------------------------------------+ + +-------------------------------------------------------+----------------+----------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+----------------+----------------------------------------------+ + | | ``REPOSITORY`` | repository to use for benchmark (must exist) | + +-------------------------------------------------------+----------------+----------------------------------------------+ + | | ``PATH`` | path were to create benchmark input data | + +-------------------------------------------------------+----------------+----------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+----------------+----------------------------------------------+ .. raw:: html @@ -34,8 +34,8 @@ borg benchmark crud .. only:: latex - REPO - repo to use for benchmark (must exist) + REPOSITORY + repository to use for benchmark (must exist) PATH path were to create benchmark input data @@ -54,9 +54,9 @@ command will create / read / update / delete some archives named borg-benchmark- Make sure you have free space there, you'll need about 1GB each (+ overhead). -If your repository is encrypted and borg needs a passphrase to unlock the key, use: +If your repository is encrypted and borg needs a passphrase to unlock the key, use:: -BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH + BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH Measurements are done with different input file sizes and counts. The file contents are very artificial (either all zero or all random), diff --git a/docs/usage/config.rst.inc b/docs/usage/config.rst.inc index 1a204d8a0..d90c327ee 100644 --- a/docs/usage/config.rst.inc +++ b/docs/usage/config.rst.inc @@ -6,7 +6,7 @@ borg config ----------- .. code-block:: none - borg [common options] config [options] REPOSITORY [NAME] [VALUE] + borg [common options] config [options] [REPOSITORY] [NAME] [VALUE] .. only:: html diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index 4cd934edc..1e789bc29 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -6,7 +6,7 @@ borg delete ----------- .. code-block:: none - borg [common options] delete [options] [TARGET] [ARCHIVE...] + borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...] .. only:: html @@ -15,7 +15,7 @@ borg delete +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | **positional arguments** | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``TARGET`` | archive or repository to delete | + | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to delete | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``ARCHIVE`` | archives to delete | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -58,8 +58,8 @@ borg delete .. only:: latex - TARGET - archive or repository to delete + REPOSITORY_OR_ARCHIVE + repository or archive to delete ARCHIVE archives to delete diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 030f56eca..53001ec09 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -96,6 +96,9 @@ selector prefix is also supported for patterns loaded from a file. Due to whitespace removal paths with whitespace at the beginning or end can only be excluded using regular expressions. +To test your exclusion patterns without performing an actual backup you can +run ``borg create --list --dry-run ...``. + Examples:: # Exclude '/home/user/file.o' but not '/home/user/file.odt': @@ -134,6 +137,13 @@ Examples:: A root path starts with the prefix `R`, followed by a path (a plain path, not a file pattern). An include rule starts with the prefix +, an exclude rule starts with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern. + + .. note:: + + Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion + of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and + ``--exlude-from`` ONLY excludes are defined. + Inclusion patterns are useful to include paths that are contained in an excluded path. The first matching pattern is used so if an include pattern matches before an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches @@ -171,6 +181,8 @@ Examples:: + /home/susan # don't backup the other home directories - /home/* + # don't even look in /proc + ! /proc .. _borg_placeholders: diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc index 5ba601f4f..0d6bfe915 100644 --- a/docs/usage/info.rst.inc +++ b/docs/usage/info.rst.inc @@ -15,7 +15,7 @@ borg info +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | **positional arguments** | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``REPOSITORY_OR_ARCHIVE`` | archive or repository to display information about | + | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to display information about | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | **optional arguments** | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -49,7 +49,7 @@ borg info .. only:: latex REPOSITORY_OR_ARCHIVE - archive or repository to display information about + repository or archive to display information about optional arguments diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index e5a43fcad..98969a92c 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -15,7 +15,7 @@ borg list +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **positional arguments** | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``REPOSITORY_OR_ARCHIVE`` | repository/archive to list contents of | + | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to list contents of | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``PATH`` | paths to list; patterns are supported | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -67,7 +67,7 @@ borg list .. only:: latex REPOSITORY_OR_ARCHIVE - repository/archive to list contents of + repository or archive to list contents of PATH paths to list; patterns are supported diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index 2520f1ff2..f813f5583 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -15,7 +15,7 @@ borg mount +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | **positional arguments** | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``REPOSITORY_OR_ARCHIVE`` | repository/archive to mount | + | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to mount | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``MOUNTPOINT`` | where to mount filesystem | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -67,7 +67,7 @@ borg mount .. only:: latex REPOSITORY_OR_ARCHIVE - repository/archive to mount + repository or archive to mount MOUNTPOINT where to mount filesystem PATH diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index 08c5bdd1f..c503f6d50 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -15,7 +15,7 @@ borg recreate +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | **positional arguments** | +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``REPOSITORY_OR_ARCHIVE`` | repository/archive to recreate | + | | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to recreate | +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``PATH`` | paths to recreate; patterns are supported | +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -77,7 +77,7 @@ borg recreate .. only:: latex REPOSITORY_OR_ARCHIVE - repository/archive to recreate + repository or archive to recreate PATH paths to recreate; patterns are supported diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc index 47a240dd0..9f94d2cf8 100644 --- a/docs/usage/upgrade.rst.inc +++ b/docs/usage/upgrade.rst.inc @@ -126,7 +126,7 @@ due to the cache resync. Upgrade should be able to resume if interrupted, although it will still iterate over all segments. If you want to start from scratch, use `borg delete` over the copied repository to -make sure the cache files are also removed: +make sure the cache files are also removed:: borg delete borg diff --git a/setup.py b/setup.py index 94a3671dc..dd6369504 100644 --- a/setup.py +++ b/setup.py @@ -17,10 +17,10 @@ import setup_zstd import setup_b2 # True: use the shared liblz4 (>= 1.7.0 / r129) from the system, False: use the bundled lz4 code -prefer_system_liblz4 = False +prefer_system_liblz4 = True # True: use the shared libzstd (>= 1.3.0) from the system, False: use the bundled zstd code -prefer_system_libzstd = False +prefer_system_libzstd = True # True: use the shared libb2 from the system, False: use the bundled blake2 code prefer_system_libb2 = True