Merge pull request #5036 from fantasya-pbem/docs/4941_Backport_FAQ-Borg-Config-Dir

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

docs/faq.rst

@@ -352,6 +352,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 those 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 key passphrase) 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?
@@ -365,8 +387,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?
 -------------------------------------------------------------

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
@@ -424,7 +426,7 @@ Temporary files (server):
     process.
     For some OSes, this can be done just by setting the correct value in the
     .bashrc (or equivalent login config file for other shells), however in
-    other cases it may be neccessary to first enable ``PermitUserEnvironment yes``
+    other cases it may be necessary to first enable ``PermitUserEnvironment yes``
     in your ``sshd_config`` file, then add ``environment="TMPDIR=/my/big/tmpdir"``
     at the start of the public key to be used in the ``authorized_hosts`` file.