From 1e2835eb1df7300e71d54b8e808051a0acfb6c55 Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Sun, 18 Jun 2017 12:13:28 +0200 Subject: docs: man pages, usage. --- 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 | 15 +++--- docs/man/borg-common.1 | 2 +- docs/man/borg-compression.1 | 60 +++++++-------------- docs/man/borg-create.1 | 23 ++++---- docs/man/borg-delete.1 | 7 ++- docs/man/borg-diff.1 | 8 +-- docs/man/borg-export-tar.1 | 12 ++--- docs/man/borg-extract.1 | 6 +-- docs/man/borg-info.1 | 7 ++- docs/man/borg-init.1 | 31 +++++++---- docs/man/borg-key-change-passphrase.1 | 46 +++++++++++++++- docs/man/borg-key-export.1 | 2 +- docs/man/borg-key-import.1 | 4 +- docs/man/borg-key-migrate-to-repokey.1 | 2 +- docs/man/borg-key.1 | 2 +- docs/man/borg-list.1 | 29 ++++------ docs/man/borg-mount.1 | 9 ++-- docs/man/borg-patterns.1 | 79 +++++++++++++--------------- docs/man/borg-placeholders.1 | 96 +++++++++++++--------------------- docs/man/borg-prune.1 | 24 +++++---- docs/man/borg-recreate.1 | 26 ++++----- docs/man/borg-rename.1 | 2 +- docs/man/borg-serve.1 | 8 ++- docs/man/borg-umount.1 | 4 +- docs/man/borg-upgrade.1 | 4 +- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 75 ++++++++++++++++++-------- 31 files changed, 321 insertions(+), 272 deletions(-) (limited to 'docs/man') diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index ed1a5e1e0..c763aae31 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 "2017-05-17" "" "borg backup tool" +.TH BORG-BENCHMARK-CRUD 1 "2017-06-18" "" "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 0f46eb8a6..79e356ac1 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 "2017-05-17" "" "borg backup tool" +.TH BORG-BENCHMARK 1 "2017-06-18" "" "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 a7275b0c0..7b4291cd5 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 "2017-05-17" "" "borg backup tool" +.TH BORG-BREAK-LOCK 1 "2017-06-18" "" "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 a4649a71e..d5b3edbfa 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 "2017-05-17" "" "borg backup tool" +.TH BORG-CHANGE-PASSPHRASE 1 "2017-06-18" "" "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 cb694cac1..cf2996a2a 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 "2017-05-17" "" "borg backup tool" +.TH BORG-CHECK 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency . @@ -55,7 +55,7 @@ stored in the segments. 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 \-\-archives\-only option. +The repository check can be skipped using the \fB\-\-archives\-only\fP option. .UNINDENT .sp Second, the consistency and correctness of the archive metadata is verified: @@ -84,10 +84,10 @@ decryption and this is always done client\-side, because key access will be required). .IP \(bu 2 The archive checks can be time consuming, they can be skipped using the -\-\-repository\-only option. +\fB\-\-repository\-only\fP option. .UNINDENT .sp -The \-\-verify\-data option will perform a full integrity verification (as opposed to +The \fB\-\-verify\-data\fP option will perform a full integrity verification (as opposed to checking the CRC32 of the segment) of data, which means reading the data from the repository, decrypting and decompressing it. This is a cryptographic verification, which will detect (accidental) corruption. For encrypted repositories it is @@ -113,7 +113,7 @@ only perform repository checks only perform archives checks .TP .B \-\-verify\-data -perform cryptographic archive data integrity verification (conflicts with \-\-repository\-only) +perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP) .TP .B \-\-repair attempt to repair any inconsistencies found @@ -125,7 +125,10 @@ work slower, but using less space .INDENT 0.0 .TP .B \-P\fP,\fB \-\-prefix -only consider archive names starting with this prefix +only consider archive names starting with this prefix. +.TP +.B \-a\fP,\fB \-\-glob\-archives +only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .B \-\-sort\-by Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 223fd33a7..f48ccb6c1 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 "2017-05-17" "" "borg backup tool" +.TH BORG-COMMON 1 "2017-06-18" "" "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 9e176f224..3347a6582 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 "2017-05-17" "" "borg backup tool" +.TH BORG-COMPRESSION 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression . @@ -32,57 +32,48 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH DESCRIPTION .sp +It is no problem to mix different compression methods in one repo, +deduplication is done on the source data chunks (not on the compressed +or encrypted data). +.sp +If some specific chunk was once compressed and stored into the repo, creating +another backup that also uses this chunk will not change the stored chunk. +So if you use different compression specs for the backups, whichever stores a +chunk first determines its compression. See also borg recreate. +.sp Compression is lz4 by default. If you want something else, you have to specify what you want. .sp Valid compression specifiers are: -.sp -none .INDENT 0.0 -.INDENT 3.5 +.TP +.B none Do not compress. -.UNINDENT -.UNINDENT -.sp -lz4 -.INDENT 0.0 -.INDENT 3.5 +.TP +.B lz4 Use lz4 compression. High speed, low compression. (default) -.UNINDENT -.UNINDENT -.sp -zlib[,L] -.INDENT 0.0 -.INDENT 3.5 +.TP +.B zlib[,L] Use zlib ("gz") compression. Medium speed, medium compression. If you do not explicitely give the compression level L (ranging from 0 to 9), it will use level 6. Giving level 0 (means "no compression", but still has zlib protocol overhead) is usually pointless, you better use "none" compression. -.UNINDENT -.UNINDENT -.sp -lzma[,L] -.INDENT 0.0 -.INDENT 3.5 +.TP +.B lzma[,L] Use lzma ("xz") compression. Low speed, high compression. If you do not explicitely give the compression level L (ranging from 0 to 9), it will use level 6. Giving levels above 6 is pointless and counterproductive because it does not compress better due to the buffer size used by borg \- but it wastes lots of CPU cycles and RAM. -.UNINDENT -.UNINDENT -.sp -auto,C[,L] -.INDENT 0.0 -.INDENT 3.5 +.TP +.B auto,C[,L] Use a built\-in heuristic to decide per chunk whether to compress or not. The heuristic tries with lz4 whether the data is compressible. For incompressible data, it will not use compression (uses "none"). For compressible data, it uses the given C[,L] compression \- with C[,L] being any valid compression specifier. .UNINDENT -.UNINDENT .sp Examples: .INDENT 0.0 @@ -99,17 +90,6 @@ borg create \-\-compression auto,lzma ... .fi .UNINDENT .UNINDENT -.sp -General remarks: -.sp -It is no problem to mix different compression methods in one repo, -deduplication is done on the source data chunks (not on the compressed -or encrypted data). -.sp -If some specific chunk was once compressed and stored into the repo, creating -another backup that also uses this chunk will not change the stored chunk. -So if you use different compression specs for the backups, whichever stores a -chunk first determines its compression. See also borg recreate. .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 0cae7ca0c..ec8d7b525 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 "2017-05-17" "" "borg backup tool" +.TH BORG-CREATE 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-create \- Create new archive . @@ -54,7 +54,7 @@ In the archive name, you may use the following placeholders: {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others. .sp To speed up pulling backups over sshfs and similar network file systems which do -not provide correct inode information the \-\-ignore\-inode flag can be used. This +not provide correct inode information the \fB\-\-ignore\-inode\fP flag can be used. This potentially decreases reliability of change detection, while avoiding always reading all files on these file systems. .sp @@ -63,7 +63,7 @@ creation of a new archive to ensure fast operation. This is because the file cac is used to determine changed files quickly uses absolute filenames. If this is not possible, consider creating a bind mount to a stable location. .sp -The \-\-progress option shows (from left to right) Original, Compressed and Deduplicated +The \fB\-\-progress\fP option shows (from left to right) Original, Compressed and Deduplicated (O, C and D, respectively), then the Number of files (N) processed so far, followed by the currently processed path. .sp @@ -98,6 +98,9 @@ only display items with the given status characters .TP .B \-\-json output stats as JSON (implies \-\-stats) +.TP +.B \-\-no\-cache\-sync +experimental: do not synchronize the cache. Implies \-\-no\-files\-cache. .UNINDENT .SS Exclusion options .INDENT 0.0 @@ -118,10 +121,10 @@ exclude directories that are tagged by containing a filesystem object with the g if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive .TP .BI \-\-pattern \ PATTERN -include/exclude paths matching PATTERN +experimental: include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -read include/exclude patterns from PATTERNFILE, one per line +experimental: read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SS Filesystem options .INDENT 0.0 @@ -181,11 +184,7 @@ $ borg create /path/to/repo::my\-files \e \-\-exclude \(aq*.pyc\(aq # Backup home directories excluding image thumbnails (i.e. only -# /home/*/.thumbnails is excluded, not /home/*/*/.thumbnails) -$ borg create /path/to/repo::my\-files /home \e - \-\-exclude \(aqre:^/home/[^/]+/\e.thumbnails/\(aq - -# Do the same using a shell\-style pattern +# /home//.thumbnails is excluded, not /home/*/*/.thumbnails etc.) $ borg create /path/to/repo::my\-files /home \e \-\-exclude \(aqsh:/home/*/.thumbnails\(aq @@ -238,8 +237,8 @@ $ borg create /path/to/repo::daily\-projectA\-{now:%Y\-%m\-%d} projectA .UNINDENT .SH NOTES .sp -The \-\-exclude patterns are not like tar. In tar \-\-exclude .bundler/gems will -exclude foo/.bundler/gems. In borg it will not, you need to use \-\-exclude +The \fB\-\-exclude\fP patterns are not like tar. In tar \fB\-\-exclude\fP .bundler/gems will +exclude foo/.bundler/gems. In borg it will not, you need to use \fB\-\-exclude\fP \(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for more information. .sp diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index c7c96aa15..2e8891532 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 "2017-05-17" "" "borg backup tool" +.TH BORG-DELETE 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-delete \- Delete an existing repository or archives . @@ -66,7 +66,10 @@ work slower, but using less space .INDENT 0.0 .TP .B \-P\fP,\fB \-\-prefix -only consider archive names starting with this prefix +only consider archive names starting with this prefix. +.TP +.B \-a\fP,\fB \-\-glob\-archives +only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .B \-\-sort\-by Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index b69a792be..ad030a672 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 "2017-05-17" "" "borg backup tool" +.TH BORG-DIFF 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives . @@ -47,7 +47,7 @@ are compared, which is very fast. .sp For archives prior to Borg 1.1 chunk contents are compared by default. If you did not create the archives with different chunker params, -pass \-\-same\-chunker\-params. +pass \fB\-\-same\-chunker\-params\fP\&. Note that the chunker params changed from Borg 0.xx to 1.0. .sp See the output of the "borg help patterns" command for more help on exclude patterns. @@ -97,10 +97,10 @@ exclude directories that are tagged by containing a filesystem object with the g if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive .TP .BI \-\-pattern \ PATTERN -include/exclude paths matching PATTERN +experimental: include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -read include/exclude patterns from PATTERNFILE, one per line +experimental: read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 73cd98150..515b4d849 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 "2017-05-17" "" "borg backup tool" +.TH BORG-EXPORT-TAR 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball . @@ -39,7 +39,7 @@ This command creates a tarball from an archive. .sp When giving \(aq\-\(aq as the output FILE, Borg will write a tar stream to standard output. .sp -By default (\-\-tar\-filter=auto) Borg will detect whether the FILE should be compressed +By default (\fB\-\-tar\-filter=auto\fP) Borg will detect whether the FILE should be compressed based on its file extension and pipe the tarball through an appropriate filter before writing it to FILE: .INDENT 0.0 @@ -51,7 +51,7 @@ before writing it to FILE: \&.tar.xz: xz .UNINDENT .sp -Alternatively a \-\-tar\-filter program may be explicitly specified. It should +Alternatively a \fB\-\-tar\-filter\fP program may be explicitly specified. It should read the uncompressed tar stream from stdin and write a compressed/filtered tar stream to stdout. .sp @@ -62,7 +62,7 @@ BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported. Timestamp resolution is limited to whole seconds, not the nanosecond resolution otherwise supported by Borg. .sp -A \-\-sparse option (as found in borg extract) is not supported. +A \fB\-\-sparse\fP option (as found in borg extract) is not supported. .sp By default the entire archive is extracted but a subset of files and directories can be selected by passing a list of \fBPATHs\fP as arguments. @@ -103,10 +103,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -include/exclude paths matching PATTERN +experimental: include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -read include/exclude patterns from PATTERNFILE, one per line +experimental: read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index dbe9c3537..13a71ab72 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 "2017-05-17" "" "borg backup tool" +.TH BORG-EXTRACT 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents . @@ -76,10 +76,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -include/exclude paths matching PATTERN +experimental: include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -read include/exclude patterns from PATTERNFILE, one per line +experimental: read include/exclude patterns from PATTERNFILE, one per line .TP .B \-\-numeric\-owner only obey numeric user and group identifiers diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index f235a866c..338d3ca60 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 "2017-05-17" "" "borg backup tool" +.TH BORG-INFO 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used . @@ -67,7 +67,10 @@ format output as JSON .INDENT 0.0 .TP .B \-P\fP,\fB \-\-prefix -only consider archive names starting with this prefix +only consider archive names starting with this prefix. +.TP +.B \-a\fP,\fB \-\-glob\-archives +only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .B \-\-sort\-by Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index e25b9ca17..9576afa8d 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 "2017-06-11" "" "borg backup tool" +.TH BORG-INIT 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-init \- Initialize an empty repository . @@ -81,6 +81,8 @@ a different keyboard layout. You can change your passphrase for existing repos at any time, it won\(aqt affect the encryption/decryption key or other secrets. .SS Encryption modes +.\" nanorst: inline-fill +. .TS center; |l|l|l|l|. @@ -103,9 +105,10 @@ SHA\-256 T} T{ none T} T{ -authenticated +\fIauthenticated\fP T} T{ -repokey, keyfile +repokey +keyfile T} _ T{ @@ -113,17 +116,22 @@ BLAKE2b T} T{ n/a T} T{ -authenticated\-blake2 +\fIauthenticated\-blake2\fP T} T{ -repokey\-blake2, -keyfile\-blake2 +\fIrepokey\-blake2\fP +\fIkeyfile\-blake2\fP T} _ .TE +.\" nanorst: inline-replace +. +.sp +\fIMarked modes\fP are new in Borg 1.1 and are not backwards\-compatible with Borg 1.0.x. .sp On modern Intel/AMD CPUs (except very cheap ones), AES is usually hardware\-accelerated. -BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs, +BLAKE2b is faster than SHA256 on Intel/AMD 64\-bit CPUs +(except AMD Ryzen and future CPUs with SHA extensions), which makes \fIauthenticated\-blake2\fP faster than \fInone\fP and \fIauthenticated\fP\&. .sp On modern ARM CPUs, NEON provides hardware acceleration for SHA256 making it faster @@ -134,7 +142,7 @@ Hardware acceleration is always used automatically when available. \fIrepokey\fP and \fIkeyfile\fP use AES\-CTR\-256 for encryption and HMAC\-SHA256 for authentication in an encrypt\-then\-MAC (EtM) construction. The chunk ID hash is HMAC\-SHA256 as well (with a separate key). -These modes are compatible with borg 1.0.x. +These modes are compatible with Borg 1.0.x. .sp \fIrepokey\-blake2\fP and \fIkeyfile\-blake2\fP are also authenticated encryption modes, but use BLAKE2b\-256 instead of HMAC\-SHA256 for authentication. The chunk ID @@ -144,7 +152,7 @@ These modes are new and \fInot\fP compatible with Borg 1.0.x. \fIauthenticated\fP mode uses no encryption, but authenticates repository contents through the same HMAC\-SHA256 hash as the \fIrepokey\fP and \fIkeyfile\fP modes (it uses it as the chunk ID hash). The key is stored like \fIrepokey\fP\&. -This mode is new and \fInot\fP compatible with borg 1.0.x. +This mode is new and \fInot\fP compatible with Borg 1.0.x. .sp \fIauthenticated\-blake2\fP is like \fIauthenticated\fP, but uses the keyed BLAKE2b\-256 hash from the other blake2 modes. @@ -152,7 +160,8 @@ This mode is new and \fInot\fP compatible with Borg 1.0.x. .sp \fInone\fP mode uses no encryption and no authentication. It uses SHA256 as chunk ID hash. Not recommended, rather consider using an authenticated or -authenticated/encrypted mode. +authenticated/encrypted mode. This mode has possible denial\-of\-service issues +when running \fBborg create\fP on contents controlled by an attacker. Use it only for new repositories where no encryption is wanted \fBand\fP when compatibility with 1.0.x is important. If compatibility with 1.0.x is not important, use \fIauthenticated\-blake2\fP or \fIauthenticated\fP instead. @@ -172,7 +181,7 @@ repository to create .B \-e\fP,\fB \-\-encryption select encryption key mode \fB(required)\fP .TP -.B \-a\fP,\fB \-\-append\-only +.B \-\-append\-only create an append\-only mode repository .TP .B \-\-storage\-quota diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 6457d3a7f..88d1b2c1a 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 "2017-05-17" "" "borg backup tool" +.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase . @@ -43,6 +43,50 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .sp REPOSITORY +.SH EXAMPLES +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# Create a key file protected repository +$ borg init \-\-encryption=keyfile \-v /path/to/repo +Initializing repository at "/path/to/repo" +Enter new passphrase: +Enter same passphrase again: +Remember your passphrase. Your data will be inaccessible without it. +Key in "/root/.config/borg/keys/mnt_backup" created. +Keep this key safe. Your data will be inaccessible without it. +Synchronizing chunks cache... +Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0. +Done. + +# Change key file passphrase +$ borg key change\-passphrase \-v /path/to/repo +Enter passphrase for key /root/.config/borg/keys/mnt_backup: +Enter new passphrase: +Enter same passphrase again: +Remember your passphrase. Your data will be inaccessible without it. +Key updated +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Fully automated using environment variables: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ BORG_NEW_PASSPHRASE=old borg init \-e=repokey repo +# now "old" is the current passphrase. +$ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase repo +# now "new" is the current passphrase. +.ft P +.fi +.UNINDENT +.UNINDENT .SH SEE ALSO .sp \fIborg\-common(1)\fP diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 9736bba3e..236886831 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 "2017-05-17" "" "borg backup tool" +.TH BORG-KEY-EXPORT 1 "2017-06-18" "" "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 2ab5af4c2..92a1754d8 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 "2017-05-17" "" "borg backup tool" +.TH BORG-KEY-IMPORT 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup . @@ -56,7 +56,7 @@ path to the backup .INDENT 0.0 .TP .B \-\-paper -interactively import from a backup done with \-\-paper +interactively import from a backup done with \fB\-\-paper\fP .UNINDENT .SH SEE ALSO .sp diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index 178429792..0d408612e 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 "2017-05-17" "" "borg backup tool" +.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-06-18" "" "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 e61f8e30a..0915aa5fd 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 "2017-05-17" "" "borg backup tool" +.TH BORG-KEY 1 "2017-06-18" "" "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 66bcf1c17..3bceff410 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 "2017-05-17" "" "borg backup tool" +.TH BORG-LIST 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-list \- List archive or repository contents . @@ -61,16 +61,19 @@ specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}") .TP .B \-\-json -Only valid for listing repository contents. Format output as JSON. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. +Only valid for listing repository contents. Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. .TP .B \-\-json\-lines -Only valid for listing archive contents. Format output as JSON Lines. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. +Only valid for listing archive contents. Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. .UNINDENT .SS filters .INDENT 0.0 .TP .B \-P\fP,\fB \-\-prefix -only consider archive names starting with this prefix +only consider archive names starting with this prefix. +.TP +.B \-a\fP,\fB \-\-glob\-archives +only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .B \-\-sort\-by Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp @@ -100,10 +103,10 @@ exclude directories that are tagged by containing a filesystem object with the g if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive .TP .BI \-\-pattern \ PATTERN -include/exclude paths matching PATTERN +experimental: include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -read include/exclude patterns from PATTERNFILE, one per line +experimental: read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SH EXAMPLES .INDENT 0.0 @@ -138,9 +141,7 @@ drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject .UNINDENT .SH NOTES .sp -The following keys are available for \-\-format: -.INDENT 0.0 -.INDENT 3.5 +The following keys are available for \fB\-\-format\fP: .INDENT 0.0 .IP \(bu 2 NEWLINE: OS dependent line separator @@ -157,13 +158,9 @@ CR .IP \(bu 2 LF .UNINDENT -.UNINDENT -.UNINDENT .sp Keys for listing repository archives: .INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 .IP \(bu 2 archive, name: archive name interpreted as text (might be missing non\-text characters, see barchive) .IP \(bu 2 @@ -173,13 +170,9 @@ time: time of creation of the archive .IP \(bu 2 id: internal ID of the archive .UNINDENT -.UNINDENT -.UNINDENT .sp Keys for listing archive files: .INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 .IP \(bu 2 type .IP \(bu 2 @@ -247,8 +240,6 @@ extra: prepends {source} with " \-> " for soft links and " link to " for hard li .IP \(bu 2 health: either "healthy" (file ok) or "broken" (if file has all\-zero replacement chunks) .UNINDENT -.UNINDENT -.UNINDENT .SH SEE ALSO .sp \fIborg\-common(1)\fP, \fIborg\-info(1)\fP, \fIborg\-diff(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-patterns(1)\fP diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 298967af1..d1892ac12 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 "2017-05-17" "" "borg backup tool" +.TH BORG-MOUNT 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem . @@ -55,7 +55,7 @@ versions: when used with a repository mount, this gives a merged, versioned view of the files in the archives. EXPERIMENTAL, layout may change in future. .IP \(bu 2 allow_damaged_files: by default damaged files (where missing chunks were -replaced with runs of zeros by borg check \-\-repair) are not readable and +replaced with runs of zeros by borg check \fB\-\-repair\fP) are not readable and return EIO (I/O error). Set this option to read such files. .UNINDENT .sp @@ -95,7 +95,10 @@ Extra mount options .INDENT 0.0 .TP .B \-P\fP,\fB \-\-prefix -only consider archive names starting with this prefix +only consider archive names starting with this prefix. +.TP +.B \-a\fP,\fB \-\-glob\-archives +only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. .TP .B \-\-sort\-by Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 9446b21f0..239a441f0 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 "2017-05-17" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . @@ -34,16 +34,17 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .sp File patterns support these styles: fnmatch, shell, regular expressions, path prefixes and path full\-matches. By default, fnmatch is used for -\fI\-\-exclude\fP patterns and shell\-style is used for \fI\-\-pattern\fP\&. If followed -by a colon (\(aq:\(aq) the first two characters of a pattern are used as a +\fB\-\-exclude\fP patterns and shell\-style is used for the experimental \fB\-\-pattern\fP +option. +.sp +If followed by a colon (\(aq:\(aq) the first two characters of a pattern are used as a style selector. Explicit style selection is necessary when a non\-default style is desired or when the desired pattern starts with two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP). -.sp -\fI\%Fnmatch\fP, selector \fIfm:\fP .INDENT 0.0 -.INDENT 3.5 -This is the default style for \-\-exclude and \-\-exclude\-from. +.TP +.B \fI\%Fnmatch\fP, selector \fIfm:\fP +This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&. These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq matching any single character specified, including ranges, and \(aq[!...]\(aq @@ -56,23 +57,15 @@ must match from the start to just before a path separator. Except for the root path, paths will never end in the path separator when matching is attempted. Thus, if a given pattern ends in a path separator, a \(aq*\(aq is appended before matching is attempted. -.UNINDENT -.UNINDENT -.sp -Shell\-style patterns, selector \fIsh:\fP -.INDENT 0.0 -.INDENT 3.5 +.TP +.B Shell\-style patterns, selector \fIsh:\fP This is the default style for \-\-pattern and \-\-patterns\-from. Like fnmatch patterns these are similar to shell patterns. The difference is that the pattern may include \fI**/\fP for matching zero or more directory levels, \fI*\fP for matching zero or more arbitrary characters with the exception of any path separator. -.UNINDENT -.UNINDENT -.sp -Regular expressions, selector \fIre:\fP -.INDENT 0.0 -.INDENT 3.5 +.TP +.B Regular expressions, selector \fIre:\fP Regular expressions similar to those found in Perl are supported. Unlike shell patterns regular expressions are not required to match the complete path and any substring match is sufficient. It is strongly recommended to @@ -81,20 +74,12 @@ separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The regular expression syntax is described in the \fI\%Python documentation for the re module\fP\&. -.UNINDENT -.UNINDENT -.sp -Path prefix, selector \fIpp:\fP -.INDENT 0.0 -.INDENT 3.5 +.TP +.B Path prefix, selector \fIpp:\fP This pattern style is useful to match whole sub\-directories. The pattern \fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein. -.UNINDENT -.UNINDENT -.sp -Path full\-match, selector \fIpf:\fP -.INDENT 0.0 -.INDENT 3.5 +.TP +.B Path full\-match, selector \fIpf:\fP This pattern style is useful to match whole paths. This is kind of a pseudo pattern as it can not have any variable or unspecified parts \- the full, precise path must be given. @@ -109,13 +94,24 @@ If you use such a pattern to include a file, it will always be included Other include/exclude patterns that would normally match will be ignored. Same logic applies for exclude. .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fIre:\fP, \fIsh:\fP and \fIfm:\fP patterns are all implemented on top of the Python SRE +engine. It is very easy to formulate patterns for each of these types which +requires an inordinate amount of time to match paths. If untrusted users +are able to supply patterns, ensure they cannot supply \fIre:\fP patterns. +Further, ensure that \fIsh:\fP and \fIfm:\fP patterns only contain a handful of +wildcards at most. +.UNINDENT .UNINDENT .sp -Exclusions can be passed via the command line option \fI\-\-exclude\fP\&. When used +Exclusions can be passed via the command line option \fB\-\-exclude\fP\&. When used from within a shell the patterns should be quoted to protect them from expansion. .sp -The \fI\-\-exclude\-from\fP option permits loading exclusion patterns from a text +The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text file with one pattern per line. Lines empty or starting with the number sign (\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style selector prefix is also supported for patterns loaded from a file. Due to @@ -159,26 +155,25 @@ $ borg create \-\-exclude\-from exclude.txt backup / .fi .UNINDENT .UNINDENT -.sp A more general and easier to use way to define filename matching patterns exists -with the \fI\-\-pattern\fP and \fI\-\-patterns\-from\fP options. Using these, you may specify -the backup roots (starting points) and patterns for inclusion/exclusion. A -root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a +with the experimental \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you +may specify the backup roots (starting points) and patterns for inclusion/exclusion. +A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a file pattern). An include rule starts with the prefix +, an exclude rule starts with the prefix \-, both followed by a pattern. 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. .sp -Note that the default pattern style for \fI\-\-pattern\fP and \fI\-\-patterns\-from\fP is +Note that the default pattern style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP is shell style (\fIsh:\fP), so those patterns behave similar to rsync include/exclude patterns. The pattern style can be set via the \fIP\fP prefix. .sp -Patterns (\fI\-\-pattern\fP) and excludes (\fI\-\-exclude\fP) from the command line are -considered first (in the order of appearance). Then patterns from \fI\-\-patterns\-from\fP -are added. Exclusion patterns from \fI\-\-exclude\-from\fP files are appended last. +Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command line are +considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP +are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last. .sp -An example \fI\-\-patterns\-from\fP file could look like that: +An example \fB\-\-patterns\-from\fP file could look like that: .INDENT 0.0 .INDENT 3.5 .sp diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 72ae10462..3c3efbf8b 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 "2017-05-17" "" "borg backup tool" +.TH BORG-PLACEHOLDERS 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders . @@ -32,80 +32,42 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH DESCRIPTION .sp -Repository (or Archive) URLs, \-\-prefix and \-\-remote\-path values support these +Repository (or Archive) URLs, \fB\-\-prefix\fP and \fB\-\-remote\-path\fP values support these placeholders: -.sp -{hostname} .INDENT 0.0 -.INDENT 3.5 +.TP +.B {hostname} The (short) hostname of the machine. -.UNINDENT -.UNINDENT -.sp -{fqdn} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {fqdn} The full name of the machine. -.UNINDENT -.UNINDENT -.sp -{now} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {now} The current local date and time, by default in ISO\-8601 format. You can also supply your own \fI\%format string\fP, e.g. {now:%Y\-%m\-%d_%H:%M:%S} -.UNINDENT -.UNINDENT -.sp -{utcnow} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {utcnow} The current UTC date and time, by default in ISO\-8601 format. You can also supply your own \fI\%format string\fP, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S} -.UNINDENT -.UNINDENT -.sp -{user} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {user} The user name (or UID, if no name is available) of the user running borg. -.UNINDENT -.UNINDENT -.sp -{pid} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {pid} The current process ID. -.UNINDENT -.UNINDENT -.sp -{borgversion} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {borgversion} The version of borg, e.g.: 1.0.8rc1 -.UNINDENT -.UNINDENT -.sp -{borgmajor} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {borgmajor} The version of borg, only the major version, e.g.: 1 -.UNINDENT -.UNINDENT -.sp -{borgminor} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {borgminor} The version of borg, only major and minor version, e.g.: 1.0 -.UNINDENT -.UNINDENT -.sp -{borgpatch} -.INDENT 0.0 -.INDENT 3.5 +.TP +.B {borgpatch} The version of borg, only major, minor and patch version, e.g.: 1.0.8 .UNINDENT -.UNINDENT .sp If literal curly braces need to be used, double them for escaping: .INDENT 0.0 @@ -132,6 +94,20 @@ borg prune \-\-prefix \(aq{hostname}\-\(aq ... .fi .UNINDENT .UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +systemd uses a difficult, non\-standard syntax for command lines in unit files (refer to +the \fIsystemd.unit(5)\fP manual page). +.sp +When invoking borg from unit files, pay particular attention to escaping, +especially when using the now/utcnow placeholders, since systemd performs its own +%\-based variable replacement even in quoted text. To avoid interference from systemd, +double all percent signs (\fB{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S}\fP +becomes \fB{hostname}\-{now:%%Y\-%%m\-%%d_%%H:%%M:%%S}\fP). +.UNINDENT +.UNINDENT .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index dcb817a6e..941a398d9 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 "2017-05-17" "" "borg backup tool" +.TH BORG-PRUNE 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules . @@ -42,7 +42,7 @@ automated backup scripts wanting to keep a certain number of historic backups. Also, prune automatically removes checkpoint archives (incomplete archives left behind by interrupted backup runs) except if the checkpoint is the latest archive (and thus still needed). Checkpoint archives are not considered when -comparing archive counts against the retention limits (\-\-keep\-X). +comparing archive counts against the retention limits (\fB\-\-keep\-X\fP). .sp If a prefix is set with \-P, then only archives that start with the prefix are considered for deletion and only those archives count towards the totals @@ -55,14 +55,14 @@ If you have multiple sequences of archives with different data sets (e.g. from different machines) in one shared repository, use one prune call per data set that matches only the respective archives using the \-P option. .sp -The "\-\-keep\-within" option takes an argument of the form "", -where char is "H", "d", "w", "m", "y". For example, "\-\-keep\-within 2d" means +The \fB\-\-keep\-within\fP option takes an argument of the form "", +where char is "H", "d", "w", "m", "y". For example, \fB\-\-keep\-within 2d\fP means to keep all archives that were created within the past 48 hours. "1m" is taken to mean "31d". The archives kept with this option do not count towards the totals specified by any other options. .sp A good procedure is to thin out more and more the older your backups get. -As an example, "\-\-keep\-daily 7" means to keep the latest backup on each day, +As an example, \fB\-\-keep\-daily 7\fP means to keep the latest backup on each day, up to 7 most recent days with backups (days without backups do not count). The rules are applied from secondly to yearly, and backups selected by previous rules do not count towards those of later rules. The time that each backup @@ -70,7 +70,7 @@ starts is used for pruning purposes. Dates and times are interpreted in the local timezone, and weeks go from Monday to Sunday. Specifying a negative number of archives to keep means that there is no limit. .sp -The "\-\-keep\-last N" option is doing the same as "\-\-keep\-secondly N" (and it will +The \fB\-\-keep\-last N\fP option is doing the same as \fB\-\-keep\-secondly N\fP (and it will keep the last N archives under the assumption that you do not create more than one backup archive in the same second). .SH OPTIONS @@ -121,12 +121,18 @@ number of monthly archives to keep .B \-y\fP,\fB \-\-keep\-yearly number of yearly archives to keep .TP -.B \-P\fP,\fB \-\-prefix -only consider archive names starting with this prefix -.TP .B \-\-save\-space work slower, but using less space .UNINDENT +.SS filters +.INDENT 0.0 +.TP +.B \-P\fP,\fB \-\-prefix +only consider archive names starting with this prefix. +.TP +.B \-a\fP,\fB \-\-glob\-archives +only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive. +.UNINDENT .SH EXAMPLES .sp Be careful, prune is a potentially dangerous command, it will remove backup diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 0e22a3207..9124d1101 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 "2017-05-17" "" "borg backup tool" +.TH BORG-RECREATE 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives . @@ -39,33 +39,33 @@ Recreate the contents of existing archives. .sp This is an \fIexperimental\fP feature. Do \fInot\fP use this on your only backup. .sp -\-\-exclude, \-\-exclude\-from, \-\-exclude\-if\-present, \-\-keep\-exclude\-tags, and PATH +\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, \fB\-\-exclude\-if\-present\fP, \fB\-\-keep\-exclude\-tags\fP, and PATH have the exact same semantics as in "borg create". If PATHs are specified the resulting archive will only contain files from these PATHs. .sp Note that all paths in an archive are relative, therefore absolute patterns/paths -will \fInot\fP match (\-\-exclude, \-\-exclude\-from, PATHs). +will \fInot\fP match (\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, PATHs). .sp -\-\-recompress allows to change the compression of existing data in archives. +\fB\-\-recompress\fP allows to change the compression of existing data in archives. Due to how Borg stores compressed size information this might display incorrect information for archives that were not recreated at the same time. There is no risk of data loss by this. .sp -\-\-chunker\-params will re\-chunk all files in the archive, this can be +\fB\-\-chunker\-params\fP will re\-chunk all files in the archive, this can be used to have upgraded Borg 0.xx or Attic archives deduplicate with Borg 1.x archives. .sp -USE WITH CAUTION. +\fBUSE WITH CAUTION.\fP Depending on the PATHs and patterns given, recreate can be used to permanently delete files from archives. -When in doubt, use "\-\-dry\-run \-\-verbose \-\-list" to see how patterns/PATHS are +When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/PATHS are interpreted. .sp The archive being recreated is only removed after the operation completes. The archive that is built during the operation exists at the same time at ".recreate". The new archive will have a different archive ID. .sp -With \-\-target the original archive is not replaced, instead a new archive is created. +With \fB\-\-target\fP the original archive is not replaced, instead a new archive is created. .sp When rechunking space usage can be substantial, expect at least the entire deduplicated size of the archives using the previous chunker params. @@ -114,13 +114,13 @@ exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosauru exclude directories that are tagged by containing a filesystem object with the given NAME .TP .B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files -if tag objects are specified with \-\-exclude\-if\-present, don\(aqt omit the tag objects themselves from the backup archive +if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive .TP .BI \-\-pattern \ PATTERN -include/exclude paths matching PATTERN +experimental: include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -read include/exclude patterns from PATTERNFILE, one per line +experimental: read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SS Archive options .INDENT 0.0 @@ -141,10 +141,10 @@ manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss form select compression algorithm, see the output of the "borg help compression" command for details. .TP .B \-\-recompress -recompress data chunks according to \-\-compression if "if\-different". When "always", chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for "if\-different", not the compression level (if any). +recompress data chunks according to \fB\-\-compression\fP if \fIif\-different\fP\&. When \fIalways\fP, chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for \fIif\-different\fP, not the compression level (if any). .TP .BI \-\-chunker\-params \ PARAMS -specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095 +specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: 19,23,21,4095 .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index 9c075314f..17e65f439 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 "2017-05-17" "" "borg backup tool" +.TH BORG-RENAME 1 "2017-06-18" "" "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 798d6486d..5052c724d 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 "2017-05-17" "" "borg backup tool" +.TH BORG-SERVE 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. . @@ -45,8 +45,14 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .BI \-\-restrict\-to\-path \ PATH restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub\-directories is granted implicitly; PATH doesn\(aqt need to directly point to a repository. .TP +.BI \-\-restrict\-to\-repository \ PATH +restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \-\-restrict\-to\-path sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. +.TP .B \-\-append\-only only allow appending to repository segment files +.TP +.B \-\-storage\-quota +Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota. .UNINDENT .SH EXAMPLES .sp diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 26a3c1f6c..21b3c2eec 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 "2017-05-17" "" "borg backup tool" +.TH BORG-UMOUNT 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem . @@ -101,7 +101,7 @@ bin boot etc home lib lib64 lost+found media mnt opt root sbin s .INDENT 0.0 .INDENT 3.5 \fBborgfs\fP will be automatically provided if you used a distribution -package, \fBpip\fP or \fBsetup.py\fP to install Borg\&. Users of the +package, \fBpip\fP or \fBsetup.py\fP to install Borg. Users of the standalone binary will have to manually create a symlink (see \fIpyinstaller\-binary\fP). .UNINDENT diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index ed9e419d3..0d4cef89c 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 "2017-05-17" "" "borg backup tool" +.TH BORG-UPGRADE 1 "2017-06-18" "" "borg backup tool" .SH NAME borg-upgrade \- upgrade a repository from a previous version . @@ -132,7 +132,7 @@ path to the repository to be upgraded .B \-n\fP,\fB \-\-dry\-run do not change repository .TP -.B \-i\fP,\fB \-\-inplace +.B \-\-inplace rewrite repository in place, with no chance of going back to older versions of the repository. .TP diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index 4099a9110..c71bd28a2 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 "2017-05-17" "" "borg backup tool" +.TH BORG-WITH-LOCK 1 "2017-06-18" "" "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 e6d15b0fa..99493444e 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -259,7 +259,7 @@ If you have set BORG_REPO (see above) and an archive location is needed, use The log level of the builtin logging configuration defaults to WARNING. This is because we want Borg to be mostly silent and only output warnings, errors and critical messages, unless output has been requested -by supplying an option that implies output (eg, \-\-list or \-\-progress). +by supplying an option that implies output (e.g. \fB\-\-list\fP or \fB\-\-progress\fP). .sp Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL .sp @@ -284,28 +284,50 @@ give different output on different log levels \- it\(aqs just a possibility. \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 -Options \-\-critical and \-\-error are provided for completeness, +Options \fB\-\-critical\fP and \fB\-\-error\fP are provided for completeness, their usage is not recommended as you might miss important information. .UNINDENT .UNINDENT .SS Return codes .sp Borg can exit with the following return codes (rc): -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -0 = success (logged as INFO) -1 = warning (operation reached its normal end, but there were warnings \- - you should check the log, logged as WARNING) -2 = error (like a fatal error, a local or remote exception, the operation - did not reach its normal end, logged as ERROR) -128+N = killed by signal N (e.g. 137 == kill \-9) -.ft P -.fi -.UNINDENT -.UNINDENT +.TS +center; +|l|l|. +_ +T{ +Return code +T} T{ +Meaning +T} +_ +T{ +0 +T} T{ +success (logged as INFO) +T} +_ +T{ +1 +T} T{ +warning (operation reached its normal end, but there were warnings \-\- +you should check the log, logged as WARNING) +T} +_ +T{ +2 +T} T{ +error (like a fatal error, a local or remote exception, the operation +did not reach its normal end, logged as ERROR) +T} +_ +T{ +128+N +T} T{ +killed by signal N (e.g. 137 == kill \-9) +T} +_ +.TE .sp If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated level as the last log entry. @@ -319,18 +341,27 @@ Borg uses some environment variables for automation: .TP .B BORG_REPO When set, use the value to give the default repository location. If a command needs an archive -parameter, you can abbreviate as \fI::archive\fP\&. If a command needs a repository parameter, you -can either leave it away or abbreviate as \fI::\fP, if a positional parameter is required. +parameter, you can abbreviate as \fB::archive\fP\&. If a command needs a repository parameter, you +can either leave it away or abbreviate as \fB::\fP, if a positional parameter is required. .TP .B BORG_PASSPHRASE When set, use the value to answer the passphrase question for encrypted repositories. -It is used when a passphrase is needed to access a encrypted repo as well as when a new +It is used when a passphrase is needed to access an encrypted repo as well as when a new +passphrase should be initially set when initializing an encrypted repo. +See also BORG_NEW_PASSPHRASE. +.TP +.B BORG_PASSCOMMAND +When set, use the standard output of the command (trailing newlines are stripped) to answer the +passphrase question for encrypted repositories. +It is used when a passphrase is needed to access an encrypted repo as well as when a new passphrase should be initially set when initializing an encrypted repo. +If BORG_PASSPHRASE is also set, it takes precedence. See also BORG_NEW_PASSPHRASE. .TP .B BORG_NEW_PASSPHRASE When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for. -This variable is checked first. If it is not set, BORG_PASSPHRASE will be checked also. +This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also +be checked. Main usecase for this is to fully automate \fBborg change\-passphrase\fP\&. .TP .B BORG_DISPLAY_PASSPHRASE @@ -537,7 +568,7 @@ depending on archive count and size \- see FAQ about how to reduce). .TP .B Network (only for client/server operation): If your repository is remote, all deduplicated (and optionally compressed/ -encrypted) data of course has to go over the connection (ssh: repo url). +encrypted) data of course has to go over the connection (\fBssh://\fP repo url). If you use a locally mounted network filesystem, additionally some copy operations used for transaction support also go over the connection. If you backup multiple sources to one target repository, additional traffic -- cgit v1.2.3