From bcd7ab3decf6f8b07d012c59fe04dcec1378886c Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 3 Aug 2022 18:20:10 +0200 Subject: [PATCH 1/6] docs: rcreate: explain "related repo" --- docs/usage/rcreate.rst | 1 + src/borg/archiver/rcreate.py | 53 +++++++++++++++++++++--------------- 2 files changed, 32 insertions(+), 22 deletions(-) diff --git a/docs/usage/rcreate.rst b/docs/usage/rcreate.rst index 985c29c34..15b82bdbe 100644 --- a/docs/usage/rcreate.rst +++ b/docs/usage/rcreate.rst @@ -15,6 +15,7 @@ Examples $ borg rcreate --encryption=repokey-blake2-chacha20-poly1305 # no encryption, not recommended $ borg rcreate --encryption=authenticated + $ borg rcreate --encryption=authenticated-blake2 $ borg rcreate --encryption=none # Remote repository (accesses a remote borg via ssh) diff --git a/src/borg/archiver/rcreate.py b/src/borg/archiver/rcreate.py index 7fb0854c1..24dbb0070 100644 --- a/src/borg/archiver/rcreate.py +++ b/src/borg/archiver/rcreate.py @@ -80,7 +80,7 @@ class RCreateMixIn: have the key and know the passphrase. Make sure to keep a backup of your key **outside** the repository - do not lock yourself out by "leaving your keys inside your car" (see :ref:`borg_key_export`). - For remote backups the encryption is done locally - the remote machine + The encryption is done locally - if you use a remote repository, the remote machine never sees your passphrase, your unencrypted key or your unencrypted files. Chunking and id generation are also based on your key to improve your privacy. @@ -125,27 +125,23 @@ class RCreateMixIn: .. nanorst: inline-fill - +-----------------------------------+--------------+----------------+--------------------+---------+ - | Mode (K = keyfile or repokey) | ID-Hash | Encryption | Authentication | V >= | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | K-blake2-chacha20-poly1305 | BLAKE2b | CHACHA20 | POLY1305 | 2.0 | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | K-chacha20-poly1305 | HMAC-SHA-256 | CHACHA20 | POLY1305 | 2.0 | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | K-blake2-aes-ocb | BLAKE2b | AES256-OCB | AES256-OCB | 2.0 | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | K-aes-ocb | HMAC-SHA-256 | AES256-OCB | AES256-OCB | 2.0 | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | K-blake2 | BLAKE2b | AES256-CTR | BLAKE2b | 1.1 | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | K | HMAC-SHA-256 | AES256-CTR | HMAC-SHA256 | any | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | authenticated-blake2 | BLAKE2b | none | BLAKE2b | 1.1 | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | authenticated | HMAC-SHA-256 | none | HMAC-SHA256 | 1.1 | - +-----------------------------------+--------------+----------------+--------------------+---------+ - | none | SHA-256 | none | none | any | - +-----------------------------------+--------------+----------------+--------------------+---------+ + +-----------------------------------+--------------+----------------+--------------------+ + | Mode (K = keyfile or repokey) | ID-Hash | Encryption | Authentication | + +-----------------------------------+--------------+----------------+--------------------+ + | K-blake2-chacha20-poly1305 | BLAKE2b | CHACHA20 | POLY1305 | + +-----------------------------------+--------------+----------------+--------------------+ + | K-chacha20-poly1305 | HMAC-SHA-256 | CHACHA20 | POLY1305 | + +-----------------------------------+--------------+----------------+--------------------+ + | K-blake2-aes-ocb | BLAKE2b | AES256-OCB | AES256-OCB | + +-----------------------------------+--------------+----------------+--------------------+ + | K-aes-ocb | HMAC-SHA-256 | AES256-OCB | AES256-OCB | + +-----------------------------------+--------------+----------------+--------------------+ + | authenticated-blake2 | BLAKE2b | none | BLAKE2b | + +-----------------------------------+--------------+----------------+--------------------+ + | authenticated | HMAC-SHA-256 | none | HMAC-SHA256 | + +-----------------------------------+--------------+----------------+--------------------+ + | none | SHA-256 | none | none | + +-----------------------------------+--------------+----------------+--------------------+ .. nanorst: inline-replace @@ -156,6 +152,19 @@ class RCreateMixIn: If you do **not** want to encrypt the contents of your backups, but still want to detect malicious tampering use an `authenticated` mode. It's like `repokey` minus encryption. + Creating a related repository + +++++++++++++++++++++++++++++ + + A related repository uses same secret key material as the other/original repository. + + By default, only the ID key and chunker secret will be the same (these are important + for deduplication) and the AE crypto keys will be newly generated random keys. + + Optionally, if you use ``--copy-ae-key`` you can also keep the same AE crypto keys + (used for authenticated encryption). Might be desired e.g. if you want to have less + keys to manage. + + Creating related repositories is useful e.g. if you want to use ``borg transfer`` later. """ ) subparser = subparsers.add_parser( From 17e75f3eea8fb8c86fbe123552127081b8f69254 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 3 Aug 2022 18:33:02 +0200 Subject: [PATCH 2/6] docs: transfer: talk of "related repo" --- src/borg/archiver/transfer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/borg/archiver/transfer.py b/src/borg/archiver/transfer.py index 2f4ed137c..ef548205e 100644 --- a/src/borg/archiver/transfer.py +++ b/src/borg/archiver/transfer.py @@ -117,7 +117,7 @@ class TransferMixIn: Suggested use for general purpose archive transfer (not repo upgrades):: - # initialize DST_REPO reusing key material from SRC_REPO, so that + # create a related DST_REPO (reusing key material from SRC_REPO), so that # chunking and chunk id generation will work in the same way as before. borg --repo=DST_REPO rcreate --other-repo=SRC_REPO --encryption=DST_ENC From 78230dd2999b0aae50d00f69ea588942ad5df8bd Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 3 Aug 2022 18:46:50 +0200 Subject: [PATCH 3/6] docs: key: fix keyfile mode in example --- docs/usage/key.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/key.rst b/docs/usage/key.rst index d1c08328c..656cba2f6 100644 --- a/docs/usage/key.rst +++ b/docs/usage/key.rst @@ -11,7 +11,7 @@ Examples :: # Create a key file protected repository - $ borg rcreate --encryption=keyfile -v + $ borg rcreate --encryption=keyfile-aes-ocb -v Initializing repository at "/path/to/repo" Enter new passphrase: Enter same passphrase again: From c3345fe423ba383ef4c68b3d747c2c4f2ea6e38b Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 3 Aug 2022 21:46:54 +0200 Subject: [PATCH 4/6] remove remainders of borg key migrate-to-repokey --- docs/usage/key_migrate-to-repokey.rst.inc | 60 ----------------------- setup_docs.py | 1 - 2 files changed, 61 deletions(-) delete mode 100644 docs/usage/key_migrate-to-repokey.rst.inc diff --git a/docs/usage/key_migrate-to-repokey.rst.inc b/docs/usage/key_migrate-to-repokey.rst.inc deleted file mode 100644 index 33cff7209..000000000 --- a/docs/usage/key_migrate-to-repokey.rst.inc +++ /dev/null @@ -1,60 +0,0 @@ -.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! - -.. _borg_key_migrate-to-repokey: - -borg key migrate-to-repokey ---------------------------- -.. code-block:: none - - borg [common options] key migrate-to-repokey [options] [REPOSITORY] - -.. only:: html - - .. class:: borg-options-table - - +-------------------------------------------------------+----------------+--+ - | **positional arguments** | - +-------------------------------------------------------+----------------+--+ - | | ``REPOSITORY`` | | - +-------------------------------------------------------+----------------+--+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+----------------+--+ - - .. raw:: html - - - -.. only:: latex - - REPOSITORY - - - - :ref:`common_options` - | - -Description -~~~~~~~~~~~ - -This command migrates a repository from passphrase mode (removed in Borg 1.0) -to repokey mode. - -You will be first asked for the repository passphrase (to open it in passphrase -mode). This is the same passphrase as you used to use for this repo before 1.0. - -It will then derive the different secrets from this passphrase. - -Then you will be asked for a new passphrase (twice, for safety). This -passphrase will be used to protect the repokey (which contains these same -secrets in encrypted form). You may use the same passphrase as you used to -use, but you may also use a different one. - -After migrating to repokey mode, you can change the passphrase at any time. -But please note: the secrets will always stay the same and they could always -be derived from your (old) passphrase-mode passphrase. \ No newline at end of file diff --git a/setup_docs.py b/setup_docs.py index c568a70a2..a9a77d3a5 100644 --- a/setup_docs.py +++ b/setup_docs.py @@ -315,7 +315,6 @@ class build_man(Command): "key_change-location": "key", "key_export": "key", "key_import": "key", - "key_migrate-to-repokey": "key", "export-tar": "tar", "import-tar": "tar", "benchmark_crud": "benchmark", From c7c7690b26d75891e541dd31728a7513625716f2 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 3 Aug 2022 22:19:12 +0200 Subject: [PATCH 5/6] build_man build_usage --- docs/man/borg-benchmark-cpu.1 | 2 +- docs/man/borg-benchmark-crud.1 | 2 +- docs/man/borg-benchmark.1 | 2 +- docs/man/borg-break-lock.1 | 2 +- docs/man/borg-check.1 | 2 +- docs/man/borg-common.1 | 2 +- docs/man/borg-compact.1 | 2 +- docs/man/borg-compression.1 | 2 +- docs/man/borg-config.1 | 2 +- docs/man/borg-create.1 | 4 +- docs/man/borg-delete.1 | 8 +-- docs/man/borg-diff.1 | 2 +- docs/man/borg-export-tar.1 | 2 +- docs/man/borg-extract.1 | 2 +- docs/man/borg-import-tar.1 | 2 +- docs/man/borg-info.1 | 2 +- docs/man/borg-key-change-location.1 | 2 +- docs/man/borg-key-change-passphrase.1 | 4 +- docs/man/borg-key-export.1 | 2 +- docs/man/borg-key-import.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 | 4 +- docs/man/borg-placeholders.1 | 2 +- docs/man/borg-prune.1 | 5 +- docs/man/borg-rcreate.1 | 62 +++++++-------------- docs/man/borg-rdelete.1 | 2 +- docs/man/borg-recreate.1 | 2 +- docs/man/borg-rename.1 | 2 +- docs/man/borg-rinfo.1 | 2 +- docs/man/borg-rlist.1 | 2 +- docs/man/borg-serve.1 | 2 +- docs/man/borg-transfer.1 | 12 ++--- docs/man/borg-umount.1 | 2 +- docs/man/borg-with-lock.1 | 2 +- docs/man/borg.1 | 2 +- docs/man/borgfs.1 | 2 +- docs/usage/delete.rst.inc | 68 +++++++++++------------ docs/usage/help.rst.inc | 2 +- docs/usage/prune.rst.inc | 77 ++++++++++++++------------- docs/usage/rcreate.rst.inc | 57 ++++++++++++-------- docs/usage/transfer.rst.inc | 4 +- 43 files changed, 182 insertions(+), 187 deletions(-) diff --git a/docs/man/borg-benchmark-cpu.1 b/docs/man/borg-benchmark-cpu.1 index 539184728..8040ef6ec 100644 --- a/docs/man/borg-benchmark-cpu.1 +++ b/docs/man/borg-benchmark-cpu.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK-CPU" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-BENCHMARK-CPU" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-benchmark-cpu \- Benchmark CPU bound operations. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 29f20033e..fe178f554 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK-CRUD" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-BENCHMARK-CRUD" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index a3d64543e..f8ecf2ac8 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BENCHMARK" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-BENCHMARK" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command .SH SYNOPSIS diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index e8521a747..ae288dde6 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-BREAK-LOCK" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-BREAK-LOCK" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. .SH SYNOPSIS diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 8340cb3bc..3bed66f92 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CHECK" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-CHECK" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency .SH SYNOPSIS diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index fefc34bcd..feaafa1c0 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMMON" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-COMMON" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands .SH SYNOPSIS diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 87d5ea1e5..92532942a 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPACT" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-COMPACT" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-compact \- compact segment files in the repository .SH SYNOPSIS diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index a6ce53c98..9fc23e685 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-COMPRESSION" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-COMPRESSION" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression .SH DESCRIPTION diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index bd9cca5e7..02b118bc0 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CONFIG" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-CONFIG" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-config \- get, set, and delete values in a repository or cache config file .SH SYNOPSIS diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index c02d7934e..62c3922b4 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-CREATE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-CREATE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-create \- Create new archive .SH SYNOPSIS @@ -297,7 +297,7 @@ $ fusermount \-u sshfs\-mount # Make a big effort in fine granular deduplication (big chunk management # overhead, needs a lot of RAM and disk space, see formula in internals -# docs \- same parameters as borg < 1.0 or attic): +# docs \- same parameters as borg < 1.0): $ borg create \-\-chunker\-params buzhash,10,23,16,4095 small /smallstuff # Backup a raw device (must not be active/in use/mounted at that time) diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 8c9fb2b90..dd18663ff 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DELETE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-DELETE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-delete \- Delete archives .SH SYNOPSIS @@ -76,11 +76,11 @@ delete only the local cache for the given repository .B \-\-force force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work. .TP -.B \-\-keep\-security\-info -keep the local security info when deleting a repository -.TP .B \-\-save\-space work slower, but using less space +.TP +.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS +write checkpoint every SECONDS seconds (Default: 1800) .UNINDENT .SS Archive filters .INDENT 0.0 diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index df1dcce14..5943d9c97 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-DIFF" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-DIFF" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives .SH SYNOPSIS diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 86f01f142..43cf1e173 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXPORT-TAR" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-EXPORT-TAR" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 9c20e776e..9ff2d4392 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-EXTRACT" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-EXTRACT" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents .SH SYNOPSIS diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1 index 0a1781142..68ffe0d8a 100644 --- a/docs/man/borg-import-tar.1 +++ b/docs/man/borg-import-tar.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-IMPORT-TAR" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-IMPORT-TAR" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-import-tar \- Create a backup archive from a tarball .SH SYNOPSIS diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index 152b51765..695e310af 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-INFO" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-INFO" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used .SH SYNOPSIS diff --git a/docs/man/borg-key-change-location.1 b/docs/man/borg-key-change-location.1 index 891a93aef..92e4ef6e2 100644 --- a/docs/man/borg-key-change-location.1 +++ b/docs/man/borg-key-change-location.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-CHANGE-LOCATION" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-LOCATION" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-key-change-location \- Change repository key location .SH SYNOPSIS diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 9f311d677..ee1c3d208 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS @@ -52,7 +52,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .nf .ft C # Create a key file protected repository -$ borg rcreate \-\-encryption=keyfile \-v +$ borg rcreate \-\-encryption=keyfile\-aes\-ocb \-v Initializing repository at "/path/to/repo" Enter new passphrase: Enter same passphrase again: diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index adf8a0a58..22129489e 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-EXPORT" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-KEY-EXPORT" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup .SH SYNOPSIS diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index dc9528c28..a66d3602e 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY-IMPORT" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-KEY-IMPORT" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup .SH SYNOPSIS diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 43ef8f251..afef0990e 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-KEY" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-KEY" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index e1d948c13..b8a806355 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-LIST" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-LIST" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-list \- List archive contents .SH SYNOPSIS diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 348dd4ac0..ad1f82eb8 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-MOUNT" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-MOUNT" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 60f7dd415..91891db82 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PATTERNS" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-PATTERNS" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns .SH DESCRIPTION @@ -220,7 +220,7 @@ pattern and would otherwise not be backed up. The first matching pattern is used, so if an include pattern matches before an exclude pattern, the file is backed up. Note that a no\-recurse exclude stops examination of subdirectories so that potential includes -will not match \- use normal exludes for such use cases. +will not match \- use normal excludes for such use cases. .sp \fBTip: You can easily test your patterns with \-\-dry\-run and \-\-list\fP: .INDENT 0.0 diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 9ec6c65a3..482bf79f8 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PLACEHOLDERS" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-PLACEHOLDERS" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders .SH DESCRIPTION diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index beb7605e7..ee0a5f53c 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-PRUNE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-PRUNE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules .SH SYNOPSIS @@ -132,6 +132,9 @@ number of yearly archives to keep .TP .B \-\-save\-space work slower, but using less space +.TP +.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS +write checkpoint every SECONDS seconds (Default: 1800) .UNINDENT .SS Archive filters .INDENT 0.0 diff --git a/docs/man/borg-rcreate.1 b/docs/man/borg-rcreate.1 index 0bc41e72d..aed60c5d5 100644 --- a/docs/man/borg-rcreate.1 +++ b/docs/man/borg-rcreate.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RCREATE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-RCREATE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-rcreate \- Create a new, empty repository .SH SYNOPSIS @@ -72,7 +72,7 @@ Encrypt and sign your backups to prevent anyone from reading or forging them unl have the key and know the passphrase. Make sure to keep a backup of your key \fBoutside\fP the repository \- do not lock yourself out by "leaving your keys inside your car" (see \fIborg_key_export\fP). -For remote backups the encryption is done locally \- the remote machine +The encryption is done locally \- if you use a remote repository, the remote machine never sees your passphrase, your unencrypted key or your unencrypted files. Chunking and id generation are also based on your key to improve your privacy. @@ -119,7 +119,7 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st . .TS center; -|l|l|l|l|l|. +|l|l|l|l|. _ T{ Mode (K = keyfile or repokey) @@ -129,8 +129,6 @@ T} T{ Encryption T} T{ Authentication -T} T{ -V >= T} _ T{ @@ -141,8 +139,6 @@ T} T{ CHACHA20 T} T{ POLY1305 -T} T{ -2.0 T} _ T{ @@ -153,8 +149,6 @@ T} T{ CHACHA20 T} T{ POLY1305 -T} T{ -2.0 T} _ T{ @@ -165,8 +159,6 @@ T} T{ AES256\-OCB T} T{ AES256\-OCB -T} T{ -2.0 T} _ T{ @@ -177,32 +169,6 @@ T} T{ AES256\-OCB T} T{ AES256\-OCB -T} T{ -2.0 -T} -_ -T{ -K\-blake2 -T} T{ -BLAKE2b -T} T{ -AES256\-CTR -T} T{ -BLAKE2b -T} T{ -1.1 -T} -_ -T{ -K -T} T{ -HMAC\-SHA\-256 -T} T{ -AES256\-CTR -T} T{ -HMAC\-SHA256 -T} T{ -any T} _ T{ @@ -213,8 +179,6 @@ T} T{ none T} T{ BLAKE2b -T} T{ -1.1 T} _ T{ @@ -225,8 +189,6 @@ T} T{ none T} T{ HMAC\-SHA256 -T} T{ -1.1 T} _ T{ @@ -237,8 +199,6 @@ T} T{ none T} T{ none -T} T{ -any T} _ .TE @@ -251,6 +211,18 @@ case of malicious activity in the repository. .sp If you do \fBnot\fP want to encrypt the contents of your backups, but still want to detect malicious tampering use an \fIauthenticated\fP mode. It\(aqs like \fIrepokey\fP minus encryption. +.SS Creating a related repository +.sp +A related repository uses same secret key material as the other/original repository. +.sp +By default, only the ID key and chunker secret will be the same (these are important +for deduplication) and the AE crypto keys will be newly generated random keys. +.sp +Optionally, if you use \fB\-\-copy\-ae\-key\fP you can also keep the same AE crypto keys +(used for authenticated encryption). Might be desired e.g. if you want to have less +keys to manage. +.sp +Creating related repositories is useful e.g. if you want to use \fBborg transfer\fP later. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. @@ -271,6 +243,9 @@ Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. .TP .B \-\-make\-parent\-dirs create the parent directories of the repository directory, if they are missing. +.TP +.B \-\-copy\-ae\-key +copy the authenticated encryption (AE) key from the key of the other repo (default: new random key). .UNINDENT .SH EXAMPLES .INDENT 0.0 @@ -287,6 +262,7 @@ $ borg rcreate \-\-encryption=repokey\-blake2\-aes\-ocb $ borg rcreate \-\-encryption=repokey\-blake2\-chacha20\-poly1305 # no encryption, not recommended $ borg rcreate \-\-encryption=authenticated +$ borg rcreate \-\-encryption=authenticated\-blake2 $ borg rcreate \-\-encryption=none # Remote repository (accesses a remote borg via ssh) diff --git a/docs/man/borg-rdelete.1 b/docs/man/borg-rdelete.1 index a410fc913..db1584040 100644 --- a/docs/man/borg-rdelete.1 +++ b/docs/man/borg-rdelete.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RDELETE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-RDELETE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-rdelete \- Delete a repository .SH SYNOPSIS diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 608ec3b37..a7fbbfe4b 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RECREATE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-RECREATE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives .SH SYNOPSIS diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index ad46e2888..46a6b37e0 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RENAME" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-RENAME" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive .SH SYNOPSIS diff --git a/docs/man/borg-rinfo.1 b/docs/man/borg-rinfo.1 index e7bd04a99..7f0a6db29 100644 --- a/docs/man/borg-rinfo.1 +++ b/docs/man/borg-rinfo.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RINFO" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-RINFO" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-rinfo \- Show repository infos .SH SYNOPSIS diff --git a/docs/man/borg-rlist.1 b/docs/man/borg-rlist.1 index 1db9b02c0..5b17b8988 100644 --- a/docs/man/borg-rlist.1 +++ b/docs/man/borg-rlist.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-RLIST" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-RLIST" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-rlist \- List the archives contained in a repository .SH SYNOPSIS diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index 3f6b3cfa6..94af97393 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-SERVE" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-SERVE" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-serve \- Start in server mode. This command is usually not used manually. .SH SYNOPSIS diff --git a/docs/man/borg-transfer.1 b/docs/man/borg-transfer.1 index ca6fb77e5..ce8cf084d 100644 --- a/docs/man/borg-transfer.1 +++ b/docs/man/borg-transfer.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-TRANSFER" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-TRANSFER" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-transfer \- archives transfer from other repository, optionally upgrade data format .SH SYNOPSIS @@ -44,9 +44,9 @@ Suggested use for general purpose archive transfer (not repo upgrades): .sp .nf .ft C -# initialize DST_REPO reusing key material from SRC_REPO, so that +# create a related DST_REPO (reusing key material from SRC_REPO), so that # chunking and chunk id generation will work in the same way as before. -borg \-\-repo=DST_REPO init \-\-other\-repo=SRC_REPO \-\-encryption=DST_ENC +borg \-\-repo=DST_REPO rcreate \-\-other\-repo=SRC_REPO \-\-encryption=DST_ENC # transfer archives from SRC_REPO to DST_REPO borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run # check what it would do @@ -126,15 +126,15 @@ $ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 rcreate \e \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-e repokey\-blake2\-aes\-ocb # 2. Check what and how much it would transfer: -$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \e +$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run # 3. Transfer (copy) archives from old repo into new repo (takes time and space!): -$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \e +$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 # 4. Check if we have everything (same as 2.): -$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \e +$ borg \-\-repo ssh://borg2@borgbackup/./tests/b20 transfer \-\-upgrader=From12To20 \e \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run .ft P .fi diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index f69ff727c..e201cc896 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-UMOUNT" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-UMOUNT" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-umount \- un-mount the FUSE filesystem .SH SYNOPSIS diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index b9b8fc86b..36c381d2a 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG-WITH-LOCK" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG-WITH-LOCK" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg-with-lock \- run a user specified command with the repository lock held .SH SYNOPSIS diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 446549a05..622c60950 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORG" 1 "2022-07-17" "" "borg backup tool" +.TH "BORG" 1 "2022-08-03" "" "borg backup tool" .SH NAME borg \- deduplicating and encrypting backup tool .SH SYNOPSIS diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index fb8f92d0a..b7ccbe631 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "BORGFS" 1 "2022-07-17" "" "borg backup tool" +.TH "BORGFS" 1 "2022-08-03" "" "borg backup tool" .SH NAME borgfs \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc index 721a7f3d5..e341bd399 100644 --- a/docs/usage/delete.rst.inc +++ b/docs/usage/delete.rst.inc @@ -12,39 +12,39 @@ borg delete .. class:: borg-options-table - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | **optional arguments** | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not change repository | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--list`` | output verbose list of archives | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--consider-checkpoints`` | consider checkpoint archives for deletion (default: not considered). | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-s``, ``--stats`` | print statistics for the deleted archive | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--cache-only`` | delete only the local cache for the given repository | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--keep-security-info`` | keep the local security info when deleting a repository | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--first N`` | consider first N archives after other filters were applied | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ - | | ``--last N`` | consider last N archives after other filters were applied | - +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | **optional arguments** | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not change repository | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of archives | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--consider-checkpoints`` | consider checkpoint archives for deletion (default: not considered). | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics for the deleted archive | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--cache-only`` | delete only the local cache for the given repository | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--save-space`` | work slower, but using less space | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--first N`` | consider first N archives after other filters were applied | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``--last N`` | consider last N archives after other filters were applied | + +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ .. raw:: html @@ -65,8 +65,8 @@ borg delete -s, --stats print statistics for the deleted archive --cache-only delete only the local cache for the given repository --force force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. - --keep-security-info keep the local security info when deleting a repository --save-space work slower, but using less space + -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) :ref:`common_options` diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 6b9e25416..159144f0c 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -173,7 +173,7 @@ Include pattern prefix ``+`` The first matching pattern is used, so if an include pattern matches before an exclude pattern, the file is backed up. Note that a no-recurse exclude stops examination of subdirectories so that potential includes -will not match - use normal exludes for such use cases. +will not match - use normal excludes for such use cases. **Tip: You can easily test your patterns with --dry-run and --list**:: diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index 74d8f7e0b..7ba9a776f 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -12,43 +12,45 @@ borg prune .. class:: borg-options-table - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | **optional arguments** | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-n``, ``--dry-run`` | do not change repository | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--force`` | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-s``, ``--stats`` | print statistics for the deleted archive | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--list`` | output verbose list of archives it keeps/prunes | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--keep-within INTERVAL`` | keep all archives within this time interval | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--keep-minutely`` | number of minutely archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-d``, ``--keep-daily`` | number of daily archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``--save-space`` | work slower, but using less space | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | **Archive filters** — Archive filters can be applied to repository targets. | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ - | | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". | - +-----------------------------------------------------------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------+ + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | **optional arguments** | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-n``, ``--dry-run`` | do not change repository | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``--force`` | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics for the deleted archive | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``--list`` | output verbose list of archives it keeps/prunes | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``--keep-within INTERVAL`` | keep all archives within this time interval | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``--keep-minutely`` | number of minutely archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-H``, ``--keep-hourly`` | number of hourly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-d``, ``--keep-daily`` | number of daily archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-w``, ``--keep-weekly`` | number of weekly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``--save-space`` | work slower, but using less space | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | **Archive filters** — Archive filters can be applied to repository targets. | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ + | | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". | + +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+ .. raw:: html @@ -76,6 +78,7 @@ borg prune -m, --keep-monthly number of monthly archives to keep -y, --keep-yearly number of yearly archives to keep --save-space work slower, but using less space + -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) :ref:`common_options` diff --git a/docs/usage/rcreate.rst.inc b/docs/usage/rcreate.rst.inc index 6f6842417..74c913997 100644 --- a/docs/usage/rcreate.rst.inc +++ b/docs/usage/rcreate.rst.inc @@ -25,6 +25,8 @@ borg rcreate +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--make-parent-dirs`` | create the parent directories of the repository directory, if they are missing. | +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | | ``--copy-ae-key`` | copy the authenticated encryption (AE) key from the key of the other repo (default: new random key). | + +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | .. class:: borg-common-opt-ref | | | | :ref:`common_options` | @@ -48,6 +50,7 @@ borg rcreate --append-only create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details. --storage-quota QUOTA Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. --make-parent-dirs create the parent directories of the repository directory, if they are missing. + --copy-ae-key copy the authenticated encryption (AE) key from the key of the other repo (default: new random key). :ref:`common_options` @@ -83,7 +86,7 @@ Borg will: have the key and know the passphrase. Make sure to keep a backup of your key **outside** the repository - do not lock yourself out by "leaving your keys inside your car" (see :ref:`borg_key_export`). - For remote backups the encryption is done locally - the remote machine + The encryption is done locally - if you use a remote repository, the remote machine never sees your passphrase, your unencrypted key or your unencrypted files. Chunking and id generation are also based on your key to improve your privacy. @@ -128,27 +131,23 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st .. nanorst: inline-fill -+-----------------------------------+--------------+----------------+--------------------+---------+ -| Mode (K = keyfile or repokey) | ID-Hash | Encryption | Authentication | V >= | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| K-blake2-chacha20-poly1305 | BLAKE2b | CHACHA20 | POLY1305 | 2.0 | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| K-chacha20-poly1305 | HMAC-SHA-256 | CHACHA20 | POLY1305 | 2.0 | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| K-blake2-aes-ocb | BLAKE2b | AES256-OCB | AES256-OCB | 2.0 | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| K-aes-ocb | HMAC-SHA-256 | AES256-OCB | AES256-OCB | 2.0 | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| K-blake2 | BLAKE2b | AES256-CTR | BLAKE2b | 1.1 | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| K | HMAC-SHA-256 | AES256-CTR | HMAC-SHA256 | any | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| authenticated-blake2 | BLAKE2b | none | BLAKE2b | 1.1 | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| authenticated | HMAC-SHA-256 | none | HMAC-SHA256 | 1.1 | -+-----------------------------------+--------------+----------------+--------------------+---------+ -| none | SHA-256 | none | none | any | -+-----------------------------------+--------------+----------------+--------------------+---------+ ++-----------------------------------+--------------+----------------+--------------------+ +| Mode (K = keyfile or repokey) | ID-Hash | Encryption | Authentication | ++-----------------------------------+--------------+----------------+--------------------+ +| K-blake2-chacha20-poly1305 | BLAKE2b | CHACHA20 | POLY1305 | ++-----------------------------------+--------------+----------------+--------------------+ +| K-chacha20-poly1305 | HMAC-SHA-256 | CHACHA20 | POLY1305 | ++-----------------------------------+--------------+----------------+--------------------+ +| K-blake2-aes-ocb | BLAKE2b | AES256-OCB | AES256-OCB | ++-----------------------------------+--------------+----------------+--------------------+ +| K-aes-ocb | HMAC-SHA-256 | AES256-OCB | AES256-OCB | ++-----------------------------------+--------------+----------------+--------------------+ +| authenticated-blake2 | BLAKE2b | none | BLAKE2b | ++-----------------------------------+--------------+----------------+--------------------+ +| authenticated | HMAC-SHA-256 | none | HMAC-SHA256 | ++-----------------------------------+--------------+----------------+--------------------+ +| none | SHA-256 | none | none | ++-----------------------------------+--------------+----------------+--------------------+ .. nanorst: inline-replace @@ -158,3 +157,17 @@ case of malicious activity in the repository. If you do **not** want to encrypt the contents of your backups, but still want to detect malicious tampering use an `authenticated` mode. It's like `repokey` minus encryption. + +Creating a related repository ++++++++++++++++++++++++++++++ + +A related repository uses same secret key material as the other/original repository. + +By default, only the ID key and chunker secret will be the same (these are important +for deduplication) and the AE crypto keys will be newly generated random keys. + +Optionally, if you use ``--copy-ae-key`` you can also keep the same AE crypto keys +(used for authenticated encryption). Might be desired e.g. if you want to have less +keys to manage. + +Creating related repositories is useful e.g. if you want to use ``borg transfer`` later. \ No newline at end of file diff --git a/docs/usage/transfer.rst.inc b/docs/usage/transfer.rst.inc index 824c125ef..ebe4c3cd9 100644 --- a/docs/usage/transfer.rst.inc +++ b/docs/usage/transfer.rst.inc @@ -72,9 +72,9 @@ Optionally, it can also upgrade the transferred data. Suggested use for general purpose archive transfer (not repo upgrades):: - # initialize DST_REPO reusing key material from SRC_REPO, so that + # create a related DST_REPO (reusing key material from SRC_REPO), so that # chunking and chunk id generation will work in the same way as before. - borg --repo=DST_REPO init --other-repo=SRC_REPO --encryption=DST_ENC + borg --repo=DST_REPO rcreate --other-repo=SRC_REPO --encryption=DST_ENC # transfer archives from SRC_REPO to DST_REPO borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run # check what it would do From f621b21ec1a6f436d4fb7b2b0082be61edc83a32 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Wed, 3 Aug 2022 22:19:28 +0200 Subject: [PATCH 6/6] docs: update security.rst --- docs/internals/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internals/security.rst b/docs/internals/security.rst index e90549d0f..6dcebf42a 100644 --- a/docs/internals/security.rst +++ b/docs/internals/security.rst @@ -83,7 +83,7 @@ authentication keys and calculating the HMAC of the metadata to authenticate [#] # RANDOM(n) returns n random bytes salt = RANDOM(64) - ikm = id_key || enc_key || enc_hmac_key + ikm = id_key || crypt_key # *context* depends on the operation, for manifest authentication it is # the ASCII string "borg-metadata-authentication-manifest". tam_key = HKDF-SHA-512(ikm, salt, context)