diff --git a/README.rst b/README.rst index 780a914ea..d215f9ea8 100644 --- a/README.rst +++ b/README.rst @@ -165,7 +165,7 @@ for the complete license. .. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable :alt: Documentation - :target: http://borgbackup.readthedocs.org/en/stable/ + :target: https://borgbackup.readthedocs.org/en/stable/ .. |build| image:: https://travis-ci.org/borgbackup/borg.svg :alt: Build Status diff --git a/borg/archiver.py b/borg/archiver.py index a2191a4d9..4d9d12da2 100644 --- a/borg/archiver.py +++ b/borg/archiver.py @@ -470,7 +470,7 @@ class Archiver: manifest, key = Manifest.load(repository) archives = manifest.list_archive_infos(sort_by='ts', reverse=True) # just a ArchiveInfo list if args.hourly + args.daily + args.weekly + args.monthly + args.yearly == 0 and args.within is None: - self.print_error('At least one of the "within", "keep-hourly", "keep-daily", "keep-weekly", ' + self.print_error('At least one of the "keep-within", "keep-hourly", "keep-daily", "keep-weekly", ' '"keep-monthly" or "keep-yearly" settings must be specified') return self.exit_code if args.prefix: diff --git a/borg/testsuite/archiver.py b/borg/testsuite/archiver.py index d264224ae..072793293 100644 --- a/borg/testsuite/archiver.py +++ b/borg/testsuite/archiver.py @@ -769,7 +769,7 @@ class ArchiverTestCase(ArchiverTestCaseBase): output = self.cmd('create', '-v', '--list', self.repository_location + '::test1', 'input') self.assert_in("U input/file1", output) # this is expected, although surprising, for why, see: - # http://borgbackup.readthedocs.org/en/latest/faq.html#i-am-seeing-a-added-status-for-a-unchanged-file + # https://borgbackup.readthedocs.org/en/latest/faq.html#i-am-seeing-a-added-status-for-a-unchanged-file self.assert_in("A input/file2", output) def test_create_topical(self): diff --git a/docs/deployment.rst b/docs/deployment.rst index f60467df0..bd69f943f 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -73,8 +73,10 @@ The options which are added to the key will perform the following: 3. Run ``borg serve`` restricted at the client base path 4. Restrict ssh and do not allow stuff which imposes a security risk -Due to the cd command we use, the server automatically changes the current working -directory so the client will not need to append the hostname to the remote URI. +Due to the ``cd`` command we use, the server automatically changes the current +working directory. Then client doesn't need to have knowledge of the absolute +or relative remote repository path and can directly access the repositories at +``@:``. .. note:: The setup above ignores all client given commandline parameters which are normally appended to the `borg serve` command. @@ -161,4 +163,4 @@ See also -------- * `SSH Daemon manpage `_ -* `Ansible `_ +* `Ansible `_ diff --git a/docs/faq.rst b/docs/faq.rst index bebb291fb..acd6d8599 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -67,14 +67,14 @@ adjust the level or algorithm). |project_name| offers a lot of different compression algorithms and levels. Which of them is the best for you pretty much depends on your -use case, your data, your hardware - so you need to do an informed +use case, your data, your hardware -- so you need to do an informed decision about whether you want to use compression, which algorithm and which level you want to use. This is why compression defaults to none. How can I specify the encryption passphrase programmatically? ------------------------------------------------------------- - + The encryption passphrase can be specified programmatically using the `BORG_PASSPHRASE` environment variable. This is convenient when setting up automated encrypted backups. Another option is to use @@ -89,11 +89,11 @@ key file based encryption with a blank passphrase. See ``export`` in a shell script file should be safe, however, as the environment of a process is `accessible only to that user - `_. + `_. When backing up to remote encrypted repos, is encryption done locally? ---------------------------------------------------------------------- - + Yes, file and directory metadata and data is locally encrypted, before leaving the local machine. We do not mean the transport layer encryption by that, but the data/metadata itself. Transport layer encryption (e.g. diff --git a/docs/global.rst.inc b/docs/global.rst.inc index 317c8d851..439b71d1a 100644 --- a/docs/global.rst.inc +++ b/docs/global.rst.inc @@ -8,17 +8,17 @@ .. _issue tracker: https://github.com/borgbackup/borg/issues .. _deduplication: https://en.wikipedia.org/wiki/Data_deduplication .. _AES: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard -.. _HMAC-SHA256: http://en.wikipedia.org/wiki/HMAC +.. _HMAC-SHA256: https://en.wikipedia.org/wiki/HMAC .. _SHA256: https://en.wikipedia.org/wiki/SHA-256 .. _PBKDF2: https://en.wikipedia.org/wiki/PBKDF2 .. _ACL: https://en.wikipedia.org/wiki/Access_control_list -.. _libacl: http://savannah.nongnu.org/projects/acl/ -.. _libattr: http://savannah.nongnu.org/projects/attr/ +.. _libacl: https://savannah.nongnu.org/projects/acl/ +.. _libattr: https://savannah.nongnu.org/projects/attr/ .. _liblz4: https://github.com/Cyan4973/lz4 .. _OpenSSL: https://www.openssl.org/ -.. _`Python 3`: http://www.python.org/ +.. _`Python 3`: https://www.python.org/ .. _Buzhash: https://en.wikipedia.org/wiki/Buzhash -.. _msgpack: http://msgpack.org/ +.. _msgpack: https://msgpack.org/ .. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/ .. _llfuse: https://pypi.python.org/pypi/llfuse/ .. _homebrew: http://brew.sh/ diff --git a/docs/internals.rst b/docs/internals.rst index 059b9893e..246ffca9f 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -207,7 +207,7 @@ The |project_name| chunker uses a rolling hash computed by the Buzhash_ algorith It triggers (chunks) when the last HASH_MASK_BITS bits of the hash are zero, producing chunks of 2^HASH_MASK_BITS Bytes on average. -create --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE +``borg create --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE`` can be used to tune the chunker parameters, the default is: - CHUNK_MIN_EXP = 10 (minimum chunk size = 2^10 B = 1 kiB) @@ -220,7 +220,7 @@ for the archive, and stored encrypted in the keyfile. This is to prevent chunk size based fingerprinting attacks on your encrypted repo contents (to guess what files you have based on a specific set of chunk sizes). -For some more general usage hints see also `--chunker-params`. +For some more general usage hints see also ``--chunker-params``. Indexes / Caches @@ -311,28 +311,27 @@ more chunks than estimated above, because 1 file is at least 1 chunk). If a remote repository is used the repo index will be allocated on the remote side. -E.g. backing up a total count of 1Mi files with a total size of 1TiB. +E.g. backing up a total count of 1 Mi (IEC binary prefix e.g. 2^20) files with a total size of 1TiB. -a) with create --chunker-params 10,23,16,4095 (default): +a) with create ``--chunker-params 10,23,16,4095`` (default): mem_usage = 2.8GiB -b) with create --chunker-params 10,23,20,4095 (custom): +b) with create ``--chunker-params 10,23,20,4095`` (custom): mem_usage = 0.4GiB -Note: there is also the --no-files-cache option to switch off the files cache. -You'll save some memory, but it will need to read / chunk all the files then as -it can not skip unmodified files then. - +.. note:: There is also the ``--no-files-cache`` option to switch off the files cache. + You'll save some memory, but it will need to read / chunk all the files as + it can not skip unmodified files then. Encryption ---------- -AES_ is used in CTR mode (so no need for padding). A 64bit initialization +AES_-256 is used in CTR mode (so no need for padding). A 64bit initialization vector is used, a `HMAC-SHA256`_ is computed on the encrypted chunk with a random 64bit nonce and both are stored in the chunk. -The header of each chunk is : ``TYPE(1)`` + ``HMAC(32)`` + ``NONCE(8)`` + ``CIPHERTEXT``. +The header of each chunk is: ``TYPE(1)`` + ``HMAC(32)`` + ``NONCE(8)`` + ``CIPHERTEXT``. Encryption and HMAC use two different keys. In AES CTR mode you can think of the IV as the start value for the counter. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 296321c18..18457e9c7 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -17,7 +17,7 @@ a good amount of free space on the filesystem that has your backup repository If you run out of disk space, it can be hard or impossible to free space, because |project_name| needs free space to operate - even to delete backup -archives. There is a `--save-space` option for some commands, but even with +archives. There is a ``--save-space`` option for some commands, but even with that |project_name| will need free space to operate. You can use some monitoring process or just include the free space information diff --git a/docs/usage.rst b/docs/usage.rst index 3379462d9..73a60dc8e 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -18,9 +18,9 @@ The log level of the builtin logging configuration defaults to WARNING. This is because we want |project_name| to be mostly silent and only output warnings (plus errors and critical messages). -Use --verbose or --info to set INFO (you will get informative output then +Use ``--verbose`` or ``--info`` to set INFO (you will get informative output then additionally to warnings, errors, critical messages). -Use --debug to set DEBUG to get output made for debugging. +Use ``--debug`` to set DEBUG to get output made for debugging. All log messages created with at least the set level will be output. @@ -29,9 +29,9 @@ Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL While you can set misc. log levels, do not expect that every command will give different output on different log levels - it's just a possibility. -..warning:: While some options (like --stats or --list) will emit more +.. warning:: While some options (like ``--stats`` or ``--list``) will emit more informational messages, you have to use INFO (or lower) log level to make -them show up in log output. Use `-v` or a logging configuration. +them show up in log output. Use ``-v`` or a logging configuration. Return codes ~~~~~~~~~~~~ @@ -75,7 +75,7 @@ Some "yes" sayers (if set, they automatically confirm that you really want to do BORG_RELOCATED_REPO_ACCESS_IS_OK For "Warning: The repository at location ... was previously located at ..." BORG_CHECK_I_KNOW_WHAT_I_AM_DOING - For "Warning: 'check --repair' is an experimental feature that might result in data loss." + For "Warning: '``check --repair``' is an experimental feature that might result in data loss." BORG_DELETE_I_KNOW_WHAT_I_AM_DOING For "You requested to completely DELETE the repository *including* all archives it contains: " @@ -334,11 +334,11 @@ Be careful, prune is potentially dangerous command, it will remove backup archives. The default of prune is to apply to **all archives in the repository** unless -you restrict its operation to a subset of the archives using `--prefix`. -When using --prefix, be careful to choose a good prefix - e.g. do not use a +you restrict its operation to a subset of the archives using ``--prefix``. +When using ``--prefix``, be careful to choose a good prefix - e.g. do not use a prefix "foo" if you do not also want to match "foobar". -It is strongly recommended to always run `prune --dry-run ...` first so you +It is strongly recommended to always run ``prune --dry-run ...`` first so you will see what it would do without it actually doing anything. :: @@ -457,17 +457,17 @@ Here are misc. notes about topics that are maybe not covered in enough detail in Item flags ~~~~~~~~~~ -`borg create -v --list` outputs a verbose list of all files, directories and other +``borg create -v --list`` outputs a verbose list of all files, directories and other file system items it considered (no matter whether they had content changes or not). For each item, it prefixes a single-letter flag that indicates type and/or status of the item. If you are interested only in a subset of that output, you can give e.g. -`--filter=AME` and it will only show regular files with A, M or E status (see +``--filter=AME`` and it will only show regular files with A, M or E status (see below). A uppercase character represents the status of a regular file relative to the -"files" cache (not relative to the repo - this is an issue if the files cache +"files" cache (not relative to the repo -- this is an issue if the files cache is not used). Metadata is stored in any case and for 'A' and 'M' also new data chunks are stored. For 'U' all data chunks refer to already existing chunks. @@ -501,12 +501,12 @@ resource usage (RAM and disk space) as the amount of resources needed is (also) determined by the total amount of chunks in the repository (see `Indexes / Caches memory usage` for details). -`--chunker-params=10,23,16,4095 (default)` results in a fine-grained deduplication +``--chunker-params=10,23,16,4095 (default)`` results in a fine-grained deduplication and creates a big amount of chunks and thus uses a lot of resources to manage them. This is good for relatively small data volumes and if the machine has a good amount of free RAM and disk space. -`--chunker-params=19,23,21,4095` results in a coarse-grained deduplication and +``--chunker-params=19,23,21,4095`` results in a coarse-grained deduplication and creates a much smaller amount of chunks and thus uses less resources. This is good for relatively big data volumes and if the machine has a relatively low amount of free RAM and disk space. @@ -519,10 +519,11 @@ In the worst case (all files are big and were touched in between backups), this will store all content into the repository again. Usually, it is not that bad though: + - usually most files are not touched, so it will just re-use the old chunks -it already has in the repo + it already has in the repo - files smaller than the (both old and new) minimum chunksize result in only -one chunk anyway, so the resulting chunks are same and deduplication will apply + one chunk anyway, so the resulting chunks are same and deduplication will apply If you switch chunker params to save resources for an existing repo that already has some backup archives, you will see an increasing effect over time, @@ -556,7 +557,7 @@ You need to be careful with what you give as filename when using ``--read-specia e.g. if you give ``/dev/zero``, your backup will never terminate. The given files' metadata is saved as it would be saved without -``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) - but +``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) -- but additionally, also the content read from it will be saved for it. Restoring such files' content is currently only supported one at a time via