diff options
author | Thomas Waldmann <tw@waldmann-edv.de> | 2019-09-07 00:36:10 +0200 |
---|---|---|
committer | Thomas Waldmann <tw@waldmann-edv.de> | 2019-09-07 00:36:10 +0200 |
commit | 33862f5a5040546be49fbaf871201686c16b7347 (patch) | |
tree | de263385364c3d7cb98730c876ff5b6ad4963aeb /docs | |
parent | 102068bfebd9f7515aeb651d5e9033b52bc68def (diff) |
build_man1.2.0a7
Diffstat (limited to 'docs')
32 files changed, 160 insertions, 52 deletions
diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 266cd87b0..f9bf2afee 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-04-22" "" "borg backup tool" +.TH BORG-BENCHMARK-CRUD 1 "2019-09-06" "" "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 38aafa30e..dfd52df63 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-04-22" "" "borg backup tool" +.TH BORG-BENCHMARK 1 "2019-09-06" "" "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 19ed8e045..1770d7d28 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-03-21" "" "borg backup tool" +.TH BORG-BREAK-LOCK 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. . diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 88a2072c1..8e77989b5 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-03-21" "" "borg backup tool" +.TH BORG-CHECK 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency . @@ -56,6 +56,8 @@ If you use a remote repo server via ssh:, the repo check is executed on the repo 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. .UNINDENT .sp Second, the consistency and correctness of the archive metadata is verified: @@ -87,6 +89,16 @@ The archive checks can be time consuming, they can be skipped using the \fB\-\-repository\-only\fP option. .UNINDENT .sp +The \fB\-\-max\-duration\fP option can be used to split a long\-running repository check into multiple partial checks. +After the given number of seconds the check is interrupted. The next partial check will continue where the +previous one stopped, until the complete repository has been checked. Example: Assuming a full check took 7 +hours, then running a daily check with \-\-max\-duration=3600 (1 hour) would result in one full check per week. +.sp +Attention: Partial checks can only do way less checks than a full check (only the CRC32 checks on segment file +entries are done) and cannot be combined with \fB\-\-repair\fP\&. Partial checks may therefore be useful only with very +large repositories where a full check would take too long. Doing a full repository check aborts a partial check; +the next partial check will start from the beginning. +.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, diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 89173da79..e6d207102 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-03-21" "" "borg backup tool" +.TH BORG-COMMON 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands . diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index d7f988aad..9763eb601 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPACT 1 "2019-03-21" "" "borg backup tool" +.TH BORG-COMPACT 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-compact \- compact segment files in the repository . @@ -32,18 +32,26 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg [common options] compact [options] REPOSITORY +borg [common options] compact [options] [REPOSITORY] .SH DESCRIPTION .sp This command frees repository space by compacting segments. .sp Use this regularly to avoid running out of space \- you do not need to use this -after each borg command though. +after each borg command though. It is especially useful after deleting archives, +because only compaction will really free repository space. .sp borg compact does not need a key, so it is possible to invoke it from the client or also from the server. .sp -Depending on the amount of segments that need compaction, it may take a while. +Depending on the amount of segments that need compaction, it may take a while, +so consider using the \fB\-\-progress\fP option. +.sp +When using \fB\-\-verbose\fP, borg will output an estimate of the freed space. +.sp +After upgrading borg (server) to 1.2+, you can use \fBborg compact \-\-cleanup\-commits\fP +to clean up the numerous 17byte commit\-only segments that borg 1.1 did not clean up +due to a bug. It is enough to do that once per repository. .sp See \fIseparate_compaction\fP in Additional Notes for more details. .SH OPTIONS @@ -70,9 +78,7 @@ cleanup commit\-only 17\-byte segment files # compact segments and free repo disk space $ borg compact /path/to/repo -# same as above plus clean up 17byte commit\-only segments, -# use this one time after upgrading borg (server) to 1.2+ -# to clean up the tiny segments files created by borg 1.1: +# same as above plus clean up 17byte commit\-only segments $ borg compact \-\-cleanup\-commits /path/to/repo .ft P .fi diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index bdb894120..ba6ef9039 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-03-21" "" "borg backup tool" +.TH BORG-COMPRESSION 1 "2019-09-06" "" "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 273363dbd..dfa390840 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-03-21" "" "borg backup tool" +.TH BORG-CONFIG 1 "2019-09-06" "" "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 7eb973c48..4e2640cd8 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-03-21" "" "borg backup tool" +.TH BORG-CREATE 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-create \- Create new archive . @@ -191,6 +191,9 @@ only store numeric user and group identifiers .B \-\-noatime do not store atime into archive .TP +.B \-\-atime +do store atime into archive +.TP .B \-\-noctime do not store ctime into archive .TP @@ -251,6 +254,10 @@ $ borg create /path/to/repo::my\-files /home \e # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio) $ borg create \-C zlib,6 \-\-one\-file\-system /path/to/repo::root\-{now:%Y\-%m\-%d} / +# Backup onto a remote host ("push" style) via ssh to port 2222, +# logging in as user "borg" and storing into /path/to/repo +$ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}\-root\-{now} / + # Backup a remote host locally ("pull" style) using sshfs $ mkdir sshfs\-mount $ sshfs root@example.com:/ sshfs\-mount @@ -284,7 +291,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 972fe7265..55f20ce12 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-03-21" "" "borg backup tool" +.TH BORG-DELETE 1 "2019-09-06" "" "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. @@ -64,8 +64,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 d0a818072..9a9a30063 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-03-21" "" "borg backup tool" +.TH BORG-DIFF 1 "2019-09-06" "" "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 8c9bc97f6..bab919326 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-03-21" "" "borg backup tool" +.TH BORG-EXPORT-TAR 1 "2019-09-06" "" "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 f4ad4b4c0..f2afe6cef 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-03-21" "" "borg backup tool" +.TH BORG-EXTRACT 1 "2019-09-06" "" "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 3719b0007..d3fda97ab 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-03-21" "" "borg backup tool" +.TH BORG-INFO 1 "2019-09-06" "" "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 7a1b418a7..f7a78d452 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-03-21" "" "borg backup tool" +.TH BORG-INIT 1 "2019-09-06" "" "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 0aa23d2d8..728b5f8a7 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-03-21" "" "borg backup tool" +.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2019-09-06" "" "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 d24dafbf3..3a9499476 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-03-21" "" "borg backup tool" +.TH BORG-KEY-EXPORT 1 "2019-09-06" "" "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 5eae1241d..2b220b7b1 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-03-21" "" "borg backup tool" +.TH BORG-KEY-IMPORT 1 "2019-09-06" "" "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 c432be9b2..8509c19f8 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-03-21" "" "borg backup tool" +.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2019-09-06" "" "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 2bb7003cf..02d46c3e9 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-03-21" "" "borg backup tool" +.TH BORG-KEY 1 "2019-09-06" "" "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 9060d27d3..16d74c347 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-03-21" "" "borg backup tool" +.TH BORG-LIST 1 "2019-09-06" "" "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 @@ -236,6 +236,8 @@ sha384 .IP \(bu 2 sha512 .IP \(bu 2 +xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!) +.IP \(bu 2 archiveid .IP \(bu 2 archivename diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 508cd86ba..d3846bd69 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-03-21" "" "borg backup tool" +.TH BORG-MOUNT 1 "2019-09-06" "" "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 7aff5336b..66c2d6dd7 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-03-21" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . @@ -219,6 +219,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 68f05d4ec..d46d8ec86 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-03-21" "" "borg backup tool" +.TH BORG-PLACEHOLDERS 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders . @@ -32,8 +32,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH DESCRIPTION .sp -Repository (or Archive) URLs, \fB\-\-prefix\fP and \fB\-\-remote\-path\fP values support these -placeholders: +Repository (or Archive) URLs, \fB\-\-prefix\fP, \fB\-\-glob\-archives\fP, \fB\-\-comment\fP +and \fB\-\-remote\-path\fP values support these placeholders: .INDENT 0.0 .TP .B {hostname} diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index 243d026e8..f895fe311 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-03-21" "" "borg backup tool" +.TH BORG-PRUNE 1 "2019-09-06" "" "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 a804e64ee..d733492c2 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-03-21" "" "borg backup tool" +.TH BORG-RECREATE 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives . @@ -90,7 +90,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 99f35506e..d48b987f1 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-03-21" "" "borg backup tool" +.TH BORG-RENAME 1 "2019-09-06" "" "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 2d8223790..37267cabb 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-03-21" "" "borg backup tool" +.TH BORG-SERVE 1 "2019-09-06" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. . @@ -102,6 +102,48 @@ has been introduced in v7.2. We recommend to use in this case. .UNINDENT .UNINDENT +.SS SSH Configuration +.sp +\fBborg serve\fP\(aqs pipes (\fBstdin\fP/\fBstdout\fP/\fBstderr\fP) are connected to the \fBsshd\fP process on the server side. In the event that the SSH connection between \fBborg serve\fP and the client is disconnected or stuck abnormally (for example, due to a network outage), it can take a long time for \fBsshd\fP to notice the client is disconnected. In the meantime, \fBsshd\fP continues running, and as a result so does the \fBborg serve\fP process holding the lock on the repository. This can cause subsequent \fBborg\fP operations on the remote repository to fail with the error: \fBFailed to create/acquire the lock\fP\&. +.sp +In order to avoid this, it is recommended to perform the following additional SSH configuration: +.sp +Either in the client side\(aqs \fB~/.ssh/config\fP file, or in the client\(aqs \fB/etc/ssh/ssh_config\fP file: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +Host backupserver + ServerAliveInterval 10 + ServerAliveCountMax 30 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Replacing \fBbackupserver\fP with the hostname, FQDN or IP address of the borg server. +.sp +This will cause the client to send a keepalive to the server every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the ssh client process will be terminated, causing the borg process to terminate gracefully. +.sp +On the server side\(aqs \fBsshd\fP configuration file (typically \fB/etc/ssh/sshd_config\fP): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +ClientAliveInterval 10 +ClientAliveCountMax 30 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This will cause the server to send a keep alive to the client every 10 seconds. If 30 consecutive keepalives are sent without a response (a time of 300 seconds), the server\(aqs sshd process will be terminated, causing the \fBborg serve\fP process to terminate gracefully and release the lock on the repository. +.sp +If you then run borg commands with \fB\-\-lock\-wait 600\fP, this gives sufficient time for the borg serve processes to terminate after the SSH connection is torn down after the 300 second wait for the keepalives to fail. +.sp +You may, of course, modify the timeout values demonstrated above to values that suit your environment and use case. .SH SEE ALSO .sp \fIborg\-common(1)\fP diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 16d43d1dd..aa8a10d89 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-03-21" "" "borg backup tool" +.TH BORG-UMOUNT 1 "2019-09-06" "" "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 47e7feeb2..fd24c395f 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-03-21" "" "borg backup tool" +.TH BORG-UPGRADE 1 "2019-09-06" "" "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 cbdffe86c..10ce63d93 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-03-21" "" "borg backup tool" +.TH BORG-WITH-LOCK 1 "2019-09-06" "" "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 3bfef2715..9b40add0c 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 @@ -658,7 +673,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 t |