From e32503b84c3045506a8cec33fa1748f8d9232a8e Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sat, 14 Jan 2017 17:19:19 +0100 Subject: [PATCH] ran setup.py build_usage --- docs/usage/create.rst.inc | 8 +++++-- docs/usage/init.rst.inc | 46 +++++++++++++++++++++++++------------- docs/usage/prune.rst.inc | 2 ++ docs/usage/upgrade.rst.inc | 4 ++-- 4 files changed, 41 insertions(+), 19 deletions(-) diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 1fd794b72..83c8810eb 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -73,8 +73,12 @@ Description ~~~~~~~~~~~ This command creates a backup archive containing all files found while recursively -traversing all paths specified. The archive will consume almost no disk space for -files or parts of files that have already been stored in other archives. +traversing all paths specified. When giving '-' as path, borg will read data +from standard input and create a file 'stdin' in the created archive from that +data. + +The archive will consume almost no disk space for files or parts of files that +have already been stored in other archives. The archive name needs to be unique. It must not end in '.checkpoint' or '.checkpoint.N' (with N being a number), because these names are used for diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc index a754c5da1..c8633b237 100644 --- a/docs/usage/init.rst.inc +++ b/docs/usage/init.rst.inc @@ -14,7 +14,7 @@ positional arguments optional arguments ``-e``, ``--encryption`` - | select encryption key mode (default: "repokey") + | select encryption key mode (default: "None") ``-a``, ``--append-only`` | create an append-only mode repository @@ -27,21 +27,22 @@ Description This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. -Encryption can be enabled at repository init time (the default). +Encryption can be enabled at repository init time. -It is not recommended to disable encryption. Repository encryption protects you -e.g. against the case that an attacker has access to your backup repository. +It is not recommended to work without encryption. Repository encryption protects +you e.g. against the case that an attacker has access to your backup repository. But be careful with the key / the passphrase: -If you want "passphrase-only" security, use the repokey mode. The key will -be stored inside the repository (in its "config" file). In above mentioned -attack scenario, the attacker will have the key (but not the passphrase). +If you want "passphrase-only" security, use one of the repokey modes. The +key will be stored inside the repository (in its "config" file). In above +mentioned attack scenario, the attacker will have the key (but not the +passphrase). -If you want "passphrase and having-the-key" security, use the keyfile mode. -The key will be stored in your home directory (in .config/borg/keys). In -the attack scenario, the attacker who has just access to your repo won't have -the key (and also not the passphrase). +If you want "passphrase and having-the-key" security, use one of the keyfile +modes. The key will be stored in your home directory (in .config/borg/keys). +In the attack scenario, the attacker who has just access to your repo won't +have the key (and also not the passphrase). Make a backup copy of the key file (keyfile mode) or repo config file (repokey mode) and keep it at a safe place, so you still have the key in @@ -72,12 +73,27 @@ Encryption modes repokey and keyfile 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. -repokey-blake2 and keyfile-blake2 use the same authenticated encryption, but -use a keyed BLAKE2b-256 hash for the chunk ID hash. +repokey-blake2 and keyfile-blake2 are also authenticated encryption modes, +but use BLAKE2b-256 instead of HMAC-SHA256 for authentication. The chunk ID +hash is a keyed BLAKE2b-256 hash. +These modes are new and not compatible with borg 1.0.x. "authenticated" mode uses no encryption, but authenticates repository contents -through the same keyed BLAKE2b-256 hash as the other blake2 modes. -The key is stored like repokey. +through the same keyed BLAKE2b-256 hash as the other blake2 modes (it uses it +as chunk ID hash). The key is stored like repokey. +This mode is new and not compatible with borg 1.0.x. + +"none" 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. +This mode is compatible with borg 1.0.x. Hardware acceleration will be used automatically. + +On modern Intel/AMD CPUs (except very cheap ones), AES is usually hw +accelerated. BLAKE2b is faster than sha256 on Intel/AMD 64bit CPUs. + +On modern ARM CPUs, NEON provides hw acceleration for sha256 making it faster +than BLAKE2b-256 there. diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index e0c6e16a2..01c58d1b2 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -17,6 +17,8 @@ optional arguments | do not change repository ``--force`` | force pruning of corrupted archives + ``-p``, ``--progress`` + | show progress display while deleting archives ``-s``, ``--stats`` | print statistics for the deleted archive ``--list`` diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc index 6b06847a5..8fd443c81 100644 --- a/docs/usage/upgrade.rst.inc +++ b/docs/usage/upgrade.rst.inc @@ -36,7 +36,7 @@ Description Upgrade an existing Borg repository. Borg 1.x.y upgrades -------------------- ++++++++++++++++++++ Use ``borg upgrade --tam REPO`` to require manifest authentication introduced with Borg 1.0.9 to address security issues. This means @@ -58,7 +58,7 @@ https://borgbackup.readthedocs.io/en/stable/changes.html#pre-1-0-9-manifest-spoo for details. Attic and Borg 0.xx to Borg 1.x -------------------------------- ++++++++++++++++++++++++++++++++ This currently supports converting an Attic repository to Borg and also helps with converting Borg 0.xx to 1.0.