Repository: borgbackup/borg
Pull request: [DOCS] #4941 – FAQ Borg config dir
fixes #4941

Problem statement:
How important is $HOME/.config/borg?
I've been reading the docs and issues over and over and it isn't clear to me how important the `$HOME/.config/borg` folder is. I'm getting the impression that analogous to duplicacy's per-repo `config` file, that the `$HOME/.config/borg` folder needs to be backed up independently as it contains stateful information. Which leads me to the following questions and I apologize if this has already been answered elsewhere:

- Should I back this folder up independently? i.e, if it gets corrupted what do I lose in terms of the ability to do with my repos?

- Is it a security risk if someone gains access to this folder? Meaning can I back it up in plaintext or do I need to encrypt it (file permissions aside)?

- Furthermore what happens if you delete `$HOME/.config/borg/cache`. Considering it's called the "cache" folder one would think it could be deleted safely, but it appears that if you delete it you need to use environment variables to silence warnings about unknown/untrusted repositories. Is this permanent or can the cache be regenerated?

Hints from issue discussion:
I am currently working on this.

Commit message: [DOCS] #4941 – How important is Borg config?

Add link to cache internals.

Patch to review:
diff --git a/docs/faq.rst b/docs/faq.rst
index 4940695875..21881f3c9c 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -353,6 +353,28 @@ to change them.
 Security
 ########
 
+.. _home_config_borg:
+
+How important is the $HOME/.config/borg directory?
+--------------------------------------------------
+
+The Borg config directory has content that you should take care of:
+
+``security`` subdirectory
+  Each directory here represents one Borg repository by its ID and contains the last known status.
+  If a repository's status is different from this information at the beginning of BorgBackup
+  operation, Borg outputs warning messages and asks for confirmation, so make sure you do not lose
+  or manipulate these files. However, apart from that warnings, a loss of these files can be
+  recovered.
+
+``keys`` subdirectory
+  In this directory all your repository keyfiles are stored. You MUST make sure to have an
+  independent backup of these keyfiles, otherwise you cannot access your backups anymore if you lose
+  them. You also MUST keep these files secret; everyone who gains access to your repository and has
+  the corresponding keyfile (and the protection password) can extract it.
+
+Make sure that only you have access to the Borg config directory.
+
 .. _cache_security:
 
 Do I need to take security precautions regarding the cache?
@@ -366,8 +388,8 @@ same system which also contains the original files which are being
 backed up. So someone with access to the cache files would also have
 access the the original files anyway.
 
-If you ever need to move the cache to a different location, this can
-be achieved by using the appropriate :ref:`env_vars`.
+The Internals section contains more details about :ref:`cache`. If you ever need to move the cache
+to a different location, this can be achieved by using the appropriate :ref:`env_vars`.
 
 How can I specify the encryption passphrase programmatically?
 -------------------------------------------------------------
diff --git a/docs/usage_general.rst.inc b/docs/usage_general.rst.inc
index a6b35feaad..7a89cb4708 100644
--- a/docs/usage_general.rst.inc
+++ b/docs/usage_general.rst.inc
@@ -230,8 +230,6 @@ General:
             in systemd.nspawn containers on some architectures (e.g. ARM).
             Using this does not affect data safety, but might result in a more bursty
             write to disk behaviour (not continuously streaming to disk).
-    TMPDIR
-        where temporary files are stored (might need a lot of temporary space for some operations), see tempfile_ for details
 
 Some automatic "answerers" (if set, they automatically answer confirmation questions):
     BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=no (or =yes)
@@ -251,22 +249,26 @@ Some automatic "answerers" (if set, they automatically answer confirmation quest
 
 Directories and files:
     BORG_BASE_DIR
-        Default to '$HOME', '~$USER', '~' (in that order)'.
+        Defaults to '$HOME', '~$USER', '~' (in that order)'.
         If we refer to ~ below, we in fact mean BORG_BASE_DIR.
     BORG_CACHE_DIR
-        Default to '~/.cache/borg'. This directory contains the local cache and might need a lot
+        Defaults to '~/.cache/borg'. This directory contains the local cache and might need a lot
         of space for dealing with big repositories. Make sure you're aware of the associated
         security aspects of the cache location: :ref:`cache_security`
     BORG_CONFIG_DIR
-        Default to '~/.config/borg'. This directory contains the whole config directories.
+        Defaults to '~/.config/borg'. This directory contains the whole config directories. See FAQ
+        for security advisory about the data in this directory: :ref:`home_config_borg`
     BORG_SECURITY_DIR
-        Default to '~/.config/borg/security'. This directory contains information borg uses to
+        Defaults to '~/.config/borg/security'. This directory contains information borg uses to
         track its usage of NONCES ("numbers used once" - usually in encryption context) and other
         security relevant data. Will move with BORG_CONFIG_DIR variable unless specified.
     BORG_KEYS_DIR
-        Default to '~/.config/borg/keys'. This directory contains keys for encrypted repositories.
+        Defaults to '~/.config/borg/keys'. This directory contains keys for encrypted repositories.
     BORG_KEY_FILE
         When set, use the given filename as repository key file.
+    TMPDIR
+        This is where temporary files are stored (might need a lot of temporary space for some
+        operations), see tempfile_ for details.
 
 Building:
     BORG_OPENSSL_PREFIX


Code review comments:
diff_hunk: @@ -353,6 +353,28 @@ to change them.
 Security
 ########
 
+.. _home_config_borg:
+
+How important is the $HOME/.config/borg directory?
+--------------------------------------------------
+
+The Borg config directory has content that you should take care of:
+
+``security`` subdirectory
+  Each directory here represents one Borg repository by its ID and contains the last known status.
+  If a repository's status is different from this information at the beginning of BorgBackup
+  operation, Borg outputs warning messages and asks for confirmation, so make sure you do not lose
+  or manipulate these files. However, apart from that warnings, a loss of these files can be
+  recovered.
+
+``keys`` subdirectory
+  In this directory all your repository keyfiles are stored. You MUST make sure to have an
+  independent backup of these keyfiles, otherwise you cannot access your backups anymore if you lose
+  them. You also MUST keep these files secret; everyone who gains access to your repository and has
+  the corresponding keyfile (and the protection password) can extract it.
path: docs/faq.rst
text: @user1:
s/protection password/key passphrase/ - just to get the terminology in sync with other places.