Merge pull request #2456 from ThomasWaldmann/doc-updates-backports-1.0

doc updates backported to 1.0

README.rst

@@ -27,6 +27,10 @@ Main features
   of bytes stored: each file is split into a number of variable length chunks
   and only chunks that have never been seen before are added to the repository.
 
+  A chunk is considered duplicate if its id_hash value is identical.
+  A cryptographically strong hash or MAC function is used as id_hash, e.g.
+  (hmac-)sha256.
+
   To deduplicate, all the chunks in the same repository are considered, no
   matter whether they come from different machines, from previous backups,
   from the same backup or even from the same single file.

borg/archiver.py

@@ -1764,7 +1764,20 @@ class Archiver:
                                help='repository to prune')
 
         upgrade_epilog = textwrap.dedent("""
-        Upgrade an existing Borg repository.
+        Upgrade an existing, local Borg repository.
+
+        When you do not need borg upgrade
+        +++++++++++++++++++++++++++++++++
+
+        Not every change requires that you run ``borg upgrade``.
+
+        You do **not** need to run it when:
+
+        - moving your repository to a different place
+        - upgrading to another point release (like 1.0.x to 1.0.y),
+          except when noted otherwise in the changelog
+        - upgrading from 1.0.x to 1.1.x,
+          except when noted otherwise in the changelog
 
         Borg 1.x.y upgrades
         +++++++++++++++++++
@@ -1796,8 +1809,13 @@ class Archiver:
 
         Currently, only LOCAL repositories can be upgraded (issue #465).
 
-        It will change the magic strings in the repository's segments
-        to match the new Borg magic strings. The keyfiles found in
+        Please note that ``borg create`` (since 1.0.0) uses bigger chunks by
+        default than old borg or attic did, so the new chunks won't deduplicate
+        with the old chunks in the upgraded repository.
+        See ``--chunker-params`` option of ``borg create`` and ``borg recreate``.
+
+        ``borg upgrade`` will change the magic strings in the repository's
+        segments to match the new Borg magic strings. The keyfiles found in
         $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
         copied to $BORG_KEYS_DIR or ~/.config/borg/keys.
 

docs/internals.rst

@@ -96,6 +96,8 @@ The id_hash function is:
 * sha256 (no encryption keys available)
 * hmac-sha256 (encryption keys available)
 
+As the id / key is used for deduplication, id_hash must be a cryptographically
+strong hash or MAC.
 
 Segments and archives
 ---------------------
@@ -233,6 +235,11 @@ 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.
 
+Buzhash is **only** used for cutting the chunks at places defined by the
+content, the buzhash value is **not** used as the deduplication criteria (we
+use a cryptographically strong hash/MAC over the chunk contents for this, the
+id_hash).
+
 ``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:
 

docs/usage.rst

@@ -925,6 +925,11 @@ in ``.ssh/authorized_keys`` ::
     command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustable backup clients>
     command="borg serve ..." ssh-rsa <key used for backup management>
 
+Please note that if you run ``borg init`` via a ``borg serve --append-only``
+server, the repository config will be created with a ``append_only=1`` entry.
+This behaviour is subject to change in a later borg version. So, be aware of
+it for now, but do not rely on it.
+
 Example
 +++++++