From aefe327ed04a29f8d2c63610f5e129dcc6ba9524 Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Thu, 16 May 2019 02:30:16 +0200
Subject: [PATCH] build_man

---
 docs/man/borg-benchmark-crud.1         |  2 +-
 docs/man/borg-benchmark.1              |  2 +-
 docs/man/borg-break-lock.1             |  2 +-
 docs/man/borg-change-passphrase.1      |  2 +-
 docs/man/borg-check.1                  |  2 +-
 docs/man/borg-common.1                 |  2 +-
 docs/man/borg-compression.1            |  2 +-
 docs/man/borg-config.1                 |  2 +-
 docs/man/borg-create.1                 |  2 +-
 docs/man/borg-delete.1                 |  2 +-
 docs/man/borg-diff.1                   |  2 +-
 docs/man/borg-export-tar.1             |  2 +-
 docs/man/borg-extract.1                |  2 +-
 docs/man/borg-info.1                   |  2 +-
 docs/man/borg-init.1                   |  2 +-
 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                   |  2 +-
 docs/man/borg-mount.1                  |  2 +-
 docs/man/borg-patterns.1               |  2 +-
 docs/man/borg-placeholders.1           |  6 ++--
 docs/man/borg-prune.1                  |  2 +-
 docs/man/borg-recreate.1               |  2 +-
 docs/man/borg-rename.1                 |  2 +-
 docs/man/borg-serve.1                  | 44 +++++++++++++++++++++++++-
 docs/man/borg-umount.1                 |  2 +-
 docs/man/borg-upgrade.1                |  2 +-
 docs/man/borg-with-lock.1              |  2 +-
 docs/man/borg.1                        |  1 +
 docs/man/borgfs.1                      |  2 +-
 33 files changed, 77 insertions(+), 34 deletions(-)

diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1
index 73e3f021a5..e1fd4a8cde 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-02-10" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .
diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1
index 904a7b5e57..a461c36e02 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-02-10" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2019-05-16" "" "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 f00a776ead..b5d2833486 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-02-10" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2019-05-16" "" "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 f43ec3acf6..52b9f8fcf6 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-02-10" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2019-05-16" "" "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 edee83b263..91b7a25a1f 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-02-10" "" "borg backup tool"
+.TH BORG-CHECK 1 "2019-05-16" "" "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 ab71c92fac..8e3348df40 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-02-10" "" "borg backup tool"
+.TH BORG-COMMON 1 "2019-05-16" "" "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 1e15681fc2..b55dc9d19f 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-02-10" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2019-05-16" "" "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 1224894ece..97cef44633 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-02-10" "" "borg backup tool"
+.TH BORG-CONFIG 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .
diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1
index b05047573f..23f1c2d803 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-02-10" "" "borg backup tool"
+.TH BORG-CREATE 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1
index 8848c4b2fe..2edecae342 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-02-10" "" "borg backup tool"
+.TH BORG-DELETE 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .
diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1
index 2d8ca50187..a67f795170 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-02-10" "" "borg backup tool"
+.TH BORG-DIFF 1 "2019-05-16" "" "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 2d09bcefb0..f79cebc139 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-02-10" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2019-05-16" "" "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 32a75e4afa..77530981ff 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-02-10" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2019-05-16" "" "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 dbc54ecce1..fd3e6c2f9a 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-02-10" "" "borg backup tool"
+.TH BORG-INFO 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .
diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1
index 1f3a81383c..a607749e2a 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-02-10" "" "borg backup tool"
+.TH BORG-INIT 1 "2019-05-16" "" "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 5da65554e5..7dc674c85d 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-02-10" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2019-05-16" "" "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 b23984968d..fa40292591 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-02-10" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2019-05-16" "" "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 9907981821..df67553881 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-02-10" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2019-05-16" "" "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 1030e892d3..8ea266a703 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-02-10" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2019-05-16" "" "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 a11209da2b..f4ce2d07e9 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-02-10" "" "borg backup tool"
+.TH BORG-KEY 1 "2019-05-16" "" "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 a3bc9e20d5..95c0805386 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-02-10" "" "borg backup tool"
+.TH BORG-LIST 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1
index 5f71ff58df..d613cc57a0 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-02-10" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index 6cebcc9bdb..1ac1b4618e 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-02-10" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1
index 6914e358e3..9ffca4116f 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-02-10" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2019-05-16" "" "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 284baeab0e..e1af471345 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-02-10" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2019-05-16" "" "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 e2f16bdd47..341f05ccf1 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-02-10" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .
diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1
index cdd824b4df..9b33de2805 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-02-10" "" "borg backup tool"
+.TH BORG-RENAME 1 "2019-05-16" "" "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 3516b30821..46ce2a34fd 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-02-10" "" "borg backup tool"
+.TH BORG-SERVE 1 "2019-05-16" "" "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 8435628dbe..a01c5d0bd0 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-02-10" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2019-05-16" "" "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 8776999cd7..6068b82b61 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-02-10" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .
diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1
index a503b41c6d..534f92deb3 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-02-10" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2019-05-16" "" "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 147b3be2f5..3bfef27151 100644
--- a/docs/man/borg.1
+++ b/docs/man/borg.1
@@ -430,6 +430,7 @@ use \fI\%fqdn@uniqueid\fP\&.
 .TP
 .B BORG_LOGGING_CONF
 When set, use the given filename as \fI\%INI\fP\-style logging configuration.
+A basic example conf can be found at \fBdocs/misc/logging.conf\fP\&.
 .TP
 .B BORG_RSH
 When set, use this command instead of \fBssh\fP\&. This can be used to specify ssh options, such as
diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1
index 4950220af0..0020c2c61f 100644
--- a/docs/man/borgfs.1
+++ b/docs/man/borgfs.1
@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2019-02-10" "" "borg backup tool"
+.TH BORGFS 1 "2019-05-16" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .