From 48e815883f231e0d733e5449813e4736c0071444 Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Sun, 18 Jun 2017 02:07:37 +0200 Subject: [PATCH] docs: usage: fix unintended block quota in common options --- docs/usage/common-options.rst.inc | 72 +++++++++++++++---------------- docs/usage/help.rst.inc | 9 ++++ docs/usage/init.rst.inc | 18 +++++--- docs/usage/upgrade.rst.inc | 2 +- setup.py | 6 +-- 5 files changed, 62 insertions(+), 45 deletions(-) diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc index 7299aa721..6bc18ebac 100644 --- a/docs/usage/common-options.rst.inc +++ b/docs/usage/common-options.rst.inc @@ -1,36 +1,36 @@ - ``-h``, ``--help`` - | show this help message and exit - ``--critical`` - | work on log level CRITICAL - ``--error`` - | work on log level ERROR - ``--warning`` - | work on log level WARNING (default) - ``--info``, ``-v``, ``--verbose`` - | work on log level INFO - ``--debug`` - | enable debug output, work on log level DEBUG - ``--debug-topic TOPIC`` - | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug. if TOPIC is not fully qualified. - ``-p``, ``--progress`` - | show progress information - ``--log-json`` - | Output one JSON object per log line instead of formatted text. - ``--lock-wait N`` - | wait for the lock, but max. N seconds (default: 1). - ``--show-version`` - | show/log the borg version - ``--show-rc`` - | show/log the return code (rc) - ``--no-files-cache`` - | do not load/update the file metadata cache used to detect unchanged files - ``--umask M`` - | set umask to M (local and remote, default: 0077) - ``--remote-path PATH`` - | use PATH as borg executable on the remote (default: "borg") - ``--remote-ratelimit rate`` - | set remote network upload rate limit in kiByte/s (default: 0=unlimited) - ``--consider-part-files`` - | treat part files like normal files (e.g. to list/extract them) - ``--debug-profile FILE`` - | Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof". \ No newline at end of file +``-h``, ``--help`` + | show this help message and exit +``--critical`` + | work on log level CRITICAL +``--error`` + | work on log level ERROR +``--warning`` + | work on log level WARNING (default) +``--info``, ``-v``, ``--verbose`` + | work on log level INFO +``--debug`` + | enable debug output, work on log level DEBUG +``--debug-topic TOPIC`` + | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug. if TOPIC is not fully qualified. +``-p``, ``--progress`` + | show progress information +``--log-json`` + | Output one JSON object per log line instead of formatted text. +``--lock-wait N`` + | wait for the lock, but max. N seconds (default: 1). +``--show-version`` + | show/log the borg version +``--show-rc`` + | show/log the return code (rc) +``--no-files-cache`` + | do not load/update the file metadata cache used to detect unchanged files +``--umask M`` + | set umask to M (local and remote, default: 0077) +``--remote-path PATH`` + | use PATH as borg executable on the remote (default: "borg") +``--remote-ratelimit rate`` + | set remote network upload rate limit in kiByte/s (default: 0=unlimited) +``--consider-part-files`` + | treat part files like normal files (e.g. to list/extract them) +``--debug-profile FILE`` + | Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof". \ No newline at end of file diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 40789083b..8d158ae7f 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -72,6 +72,15 @@ Path full-match, selector `pf:` Other include/exclude patterns that would normally match will be ignored. Same logic applies for exclude. +.. note:: + + `re:`, `sh:` and `fm:` 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 `re:` patterns. + Further, ensure that `sh:` and `fm:` patterns only contain a handful of + wildcards at most. + Exclusions can be passed via the command line option `--exclude`. When used from within a shell the patterns should be quoted to protect them from expansion. diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc index ec99fd663..88fe11c7e 100644 --- a/docs/usage/init.rst.inc +++ b/docs/usage/init.rst.inc @@ -15,7 +15,7 @@ positional arguments optional arguments ``-e``, ``--encryption`` | select encryption key mode **(required)** - ``-a``, ``--append-only`` + ``--append-only`` | create an append-only mode repository ``--storage-quota`` | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. @@ -72,16 +72,23 @@ the encryption/decryption key or other secrets. Encryption modes ++++++++++++++++ +.. nanorst: inline-fill + +----------+---------------+------------------------+--------------------------+ | Hash/MAC | Not encrypted | Not encrypted, | Encrypted (AEAD w/ AES) | | | no auth | but authenticated | and authenticated | +----------+---------------+------------------------+--------------------------+ -| SHA-256 | none | authenticated | repokey, keyfile | +| SHA-256 | none | `authenticated` | repokey | +| | | | keyfile | +----------+---------------+------------------------+--------------------------+ -| BLAKE2b | n/a | authenticated-blake2 | repokey-blake2, | -| | | | keyfile-blake2 | +| BLAKE2b | n/a | `authenticated-blake2` | `repokey-blake2` | +| | | | `keyfile-blake2` | +----------+---------------+------------------------+--------------------------+ +.. nanorst: inline-replace + +`Marked modes` are new in Borg 1.1 and are not backwards-compatible with Borg 1.0.x. + 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 @@ -114,7 +121,8 @@ 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. +authenticated/encrypted mode. This mode has possible denial-of-service issues +when running ``borg create`` on contents controlled by an attacker. Use it only for new repositories where no encryption is wanted **and** when compatibility with 1.0.x is important. If compatibility with 1.0.x is not important, use `authenticated-blake2` or `authenticated` instead. diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc index bbf51724b..cc40e8b2c 100644 --- a/docs/usage/upgrade.rst.inc +++ b/docs/usage/upgrade.rst.inc @@ -15,7 +15,7 @@ positional arguments optional arguments ``-n``, ``--dry-run`` | do not change repository - ``-i``, ``--inplace`` + ``--inplace`` | rewrite repository in place, with no chance of going back to older | versions of the repository. ``--force`` diff --git a/setup.py b/setup.py index 864b352a5..3b9b495ba 100644 --- a/setup.py +++ b/setup.py @@ -274,7 +274,7 @@ class build_usage(Command): if 'create' in choices: common_options = [group for group in choices['create']._action_groups if group.title == 'Common options'][0] with open('docs/usage/common-options.rst.inc', 'w') as doc: - self.write_options_group(common_options, doc, False) + self.write_options_group(common_options, doc, False, base_indent=0) return is_subcommand @@ -294,7 +294,7 @@ class build_usage(Command): else: self.write_options_group(group, fp) - def write_options_group(self, group, fp, with_title=True): + def write_options_group(self, group, fp, with_title=True, base_indent=4): def is_positional_group(group): return any(not o.option_strings for o in group._group_actions) @@ -303,7 +303,7 @@ class build_usage(Command): return '\n'.join('| ' + line for line in text.splitlines()) def shipout(text): - fp.write(textwrap.indent('\n'.join(text), ' ' * 4)) + fp.write(textwrap.indent('\n'.join(text), ' ' * base_indent)) if not group._group_actions: return