build_man

borgbackup · May 16, 2019 · aefe327 · aefe327
1 parent 2f1f73c
commit aefe327
Show file tree

Hide file tree

Showing 33 changed files with 77 additions and 34 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
 .