diff options
108 files changed, 2129 insertions, 2078 deletions
diff --git a/docs/faq.rst b/docs/faq.rst index b91c0ea59..9566fdec7 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -27,13 +27,7 @@ which is slower. Can I backup from multiple servers into a single repository? ------------------------------------------------------------ -Yes, this is *possible* from the technical standpoint, but it is -*not recommended* from the security perspective. BorgBackup is -built upon a defined :ref:`attack_model` that cannot provide its -guarantees for multiple clients using the same repository. See -:ref:`borg_security_critique` for a detailed explanation. - -Also, in order for the deduplication used by Borg to work, it +In order for the deduplication used by Borg to work, it needs to keep a local cache containing checksums of all file chunks already stored in the repository. This cache is stored in ``~/.cache/borg/``. If Borg detects that a repository has been @@ -49,7 +43,7 @@ Can I back up to multiple, swapped backup targets? -------------------------------------------------- It is possible to swap your backup disks if each backup medium is assigned its -own repository by creating a new one with :ref:`borg_init`. +own repository by creating a new one with :ref:`borg_rcreate`. Can I copy or synchronize my repo to another location? ------------------------------------------------------ @@ -57,8 +51,8 @@ Can I copy or synchronize my repo to another location? If you want to have redundant backup repositories (preferably at separate locations), the recommended way to do that is like this: -- ``borg init repo1`` -- ``borg init repo2`` +- ``borg rcreate repo1`` +- ``borg rcreate repo2`` - client machine ---borg create---> repo1 - client machine ---borg create---> repo2 @@ -94,10 +88,6 @@ Also, you must not run borg against multiple instances of the same repo think they are identical and e.g. use the same local cache for them (which is an issue if they happen to be not the same). See :issue:`4272` for an example. -- Encryption security issues if you would update repo and copy-of-repo - independently, due to AES counter reuse (when using legacy encryption modes). - -See also: :ref:`faq_corrupt_repo` "this is either an attack or unsafe" warning -------------------------------------------- @@ -118,9 +108,9 @@ you could delete the manifest-timestamp and the local cache: :: - borg config repo id # shows the REPO_ID + borg config id # shows the REPO_ID rm ~/.config/borg/security/REPO_ID/manifest-timestamp - borg delete --cache-only REPO + borg rdelete --cache-only This is an unsafe and unsupported way to use borg, you have been warned. @@ -199,11 +189,6 @@ really desperate (e.g. if you have no completed backup of that file and you'ld rather get a partial file extracted than nothing). You do **not** want to give that option under any normal circumstances. -Note that checkpoints inside files are created only since version 1.1, make -sure you have an up-to-date version of borgbackup if you want to continue -instead of retransferring a huge file. In some cases, there is only an outdated -version shipped with your distribution (e.g. Debian). See :ref:`installation`. - How can I backup huge file(s) over a unstable connection? --------------------------------------------------------- @@ -241,32 +226,8 @@ then use ``tar`` to perform the comparison: :: - borg export-tar /path/to/repo::archive-name - | tar --compare -f - -C /path/to/compare/to - - -.. _faq_corrupt_repo: - -My repository is corrupt, how can I restore from an older copy of it? ---------------------------------------------------------------------- - -Note: this is only required for repos using legacy encryption modes. - -If your repositories are encrypted and have the same ID, the recommended method -is to delete the corrupted repository, but keep its security info, and then copy -the working repository to the same location: - -:: - - borg delete --keep-security-info /path/to/repo - rsync -aH /path/to/repo-working/ /path/to/repo # Note the trailing slash. + borg export-tar archive-name - | tar --compare -f - -C /path/to/compare/to -A plain delete command would remove the security info in -``~/.config/borg/security``, including the nonce value. In BorgBackup -:ref:`security_encryption` is AES-CTR, where the nonce is a counter. When the -working repo was used later for creating new archives, Borg would re-use nonce -values due to starting from a lower counter value given by the older copy of the -repository. To prevent this, the ``keep-security-info`` option is applied so -that the client-side nonce counter is kept. Can Borg add redundancy to the backup data to deal with hardware malfunction? ----------------------------------------------------------------------------- @@ -296,7 +257,7 @@ SMR (shingled magnetic recording) hard drives are very different from regular hard drives. Applications have to behave in certain ways or performance will be heavily degraded. -Borg 1.1 ships with default settings suitable for SMR drives, +Borg ships with default settings suitable for SMR drives, and has been successfully tested on *Seagate Archive v2* drives using the ext4 file system. @@ -436,16 +397,16 @@ Say you want to prune ``/var/log`` faster than the rest of archive *names* and then implement different prune policies for different prefixes. For example, you could have a script that does:: - borg create --exclude var/log $REPOSITORY:main-$(date +%Y-%m-%d) / - borg create $REPOSITORY:logs-$(date +%Y-%m-%d) /var/log + borg create --exclude var/log main-$(date +%Y-%m-%d) / + borg create logs-$(date +%Y-%m-%d) /var/log Then you would have two different prune calls with different policies:: - borg prune --verbose --list -d 30 --prefix main- "$REPOSITORY" - borg prune --verbose --list -d 7 --prefix logs- "$REPOSITORY" + borg prune --verbose --list -d 30 --prefix main- + borg prune --verbose --list -d 7 --prefix logs- -This will keep 7 days of logs and 30 days of everything else. Borg 1.1 -also supports the ``--glob-archives`` parameter. +This will keep 7 days of logs and 30 days of everything else. +Borg also supports the ``--glob-archives`` parameter. How do I remove files from an existing backup? ---------------------------------------------- @@ -476,37 +437,6 @@ to change them. Security ######## -.. _borg_security_critique: - -Isn't BorgBackup's legacy AES-CTR-based crypto broken? ------------------------------------------------------- - -Note: in borg 1.3 new AEAD cipher based modes with session keys were added, -solving the issues of the legacy modes. - -If a nonce (counter) value is reused, AES-CTR mode crypto is broken. - -To exploit the AES counter management issue, an attacker would need to have -access to the borg repository. - -By tampering with the repo, the attacker could bring the repo into a state so -that it reports a lower "highest used counter value" than the one that actually -was used. The client would usually notice that, because it rather trusts the -clientside stored "highest used counter value" than trusting the server. - -But there are situations, where this is simply not possible: - -- If clients A and B used the repo, the client A can only know its own highest - CTR value, but not the one produced by B. That is only known to (B and) the - server (the repo) and thus the client A needs to trust the server about the - value produced by B in that situation. You can't do much about this except - not having multiple clients per repo. - -- Even if there is only one client, if client-side information is completely - lost (e.g. due to disk defect), the client also needs to trust the value from - server side. You can avoid this by not continuing to write to the repository - after you have lost clientside borg information. - .. _home_config_borg: How important is the $HOME/.config/borg directory? @@ -583,7 +513,7 @@ Using ``BORG_PASSCOMMAND`` with a properly permissioned file Using keyfile-based encryption with a blank passphrase It is possible to encrypt your repository in ``keyfile`` mode instead of the default ``repokey`` mode and use a blank passphrase for the key file (simply press Enter twice - when ``borg init`` asks for the password). See :ref:`encrypted_repos` + when ``borg rcreate`` asks for the password). See :ref:`encrypted_repos` for more details. Using ``BORG_PASSCOMMAND`` with macOS Keychain @@ -717,34 +647,6 @@ Send a private email to the :ref:`security contact <security-contact>` if you think you have discovered a security issue. Please disclose security issues responsibly. -How important are the nonce files? ------------------------------------- - -This only applies to repositories using legacy encryption modes. - -Borg uses :ref:`AES-CTR encryption <borg_security_critique>`. An -essential part of AES-CTR is a sequential counter that must **never** -repeat. If the same value of the counter is used twice in the same repository, -an attacker can decrypt the data. The counter is stored in the home directory -of each user ($HOME/.config/borg/security/$REPO_ID/nonce) as well as -in the repository (/path/to/repo/nonce). When creating a new archive borg uses -the highest of the two values. The value of the counter in the repository may be -higher than your local value if another user has created an archive more recently -than you did. - -Since the nonce is not necessary to read the data that is already encrypted, -``borg info``, ``borg list``, ``borg extract`` and ``borg mount`` should work -just fine without it. - -If the nonce file stored in the repo is lost, but you still have your local copy, -borg will recreate the repository nonce file the next time you run ``borg create``. -This should be safe for repositories that are only used from one user account -on one machine. - -For repositories that are used by multiple users and/or from multiple machines -it is safest to avoid running *any* commands that modify the repository after -the nonce is deleted or if you suspect it may have been tampered with. See :ref:`attack_model`. - Common issues ############# @@ -789,9 +691,9 @@ How can I deal with my very unstable SSH connection? If you have issues with lost connections during long-running borg commands, you could try to work around: -- Make partial extracts like ``borg extract REPO PATTERN`` to do multiple +- Make partial extracts like ``borg extract PATTERN`` to do multiple smaller extraction runs that complete before your connection has issues. -- Try using ``borg mount REPO MOUNTPOINT`` and ``rsync -avH`` from +- Try using ``borg mount MOUNTPOINT`` and ``rsync -avH`` from ``MOUNTPOINT`` to your desired extraction directory. If the connection breaks down, just repeat that over and over again until rsync does not find anything to do any more. Due to the way borg mount works, this might be less efficient @@ -846,7 +748,7 @@ space for chunks.archive.d (see :issue:`235` for details): :: # this assumes you are working with the same user as the backup. - cd ~/.cache/borg/$(borg config /path/to/repo id) + cd ~/.cache/borg/$(borg config id) rm -rf chunks.archive.d ; touch chunks.archive.d This deletes all the cached archive chunk indexes and replaces the directory |