Borg fixes as pre-generated keyfiles are currently unsupported

3 files changed, 36 insertions, 0 deletions

diff --git a/docs/backups.md b/docs/backups.md
index 4cfeff4..c612116 100644
--- a/docs/backups.md
+++ b/docs/backups.md
@@ -135,7 +135,28 @@ For [Borg][]:
 
 Make sure to cleanup `~/temp/misc/restore` after recovering what you need.
 
+Note on backup keys:
+
+* In the past (before 2024), the Hydra Suite and it's companion [Puppet][]
+  modules used pre-generated [Borg][] repository keys for the sake of automation.
+  This is [not possible anymore][].
+* As it's [important to keep copies of the borg repository key safely
+  elsewhere][], the managed configuration supports OpenPGP-encrypting the
+  repository key and uploading it to the remote repository.
+* This OpenPGP-encrypted key file is named as `keyfile.asc` and is uploaded
+  in the root folder of the remote repository.
+* This OpenPGP-encrypted key file is encrypted and signed with a provided
+  OpenPGP keypair and passphrase (convention is to use the machines's OpenPGP
+  general purpose key, or the machine's role key).
+* This allows the operators to fetch this encrypted keyfile and use their copy
+  of the machine's OpenPGP key to extract the passphrase _on their
+  encrypted-storage workstations_ (recommendation is to not do this on the remote
+  repository).
+
 [Borg]: https://www.borgbackup.org/
+[Puppet]: https://www.puppet.com/
+[not possible anymore]: https://github.com/borgbackup/borg/issues/7047
+[important to keep copies of the borg repository key safely elsewhere]: https://borgbackup.readthedocs.io/en/latest/faq.html#how-important-is-the-home-config-borg-directory
 
 ### eCryptfs
 
diff --git a/share/hydra/import-keys b/share/hydra/import-keys
index 7339a0d..1811930 100755
--- a/share/hydra/import-keys
+++ b/share/hydra/import-keys
@@ -123,6 +123,14 @@ EOF
 }
 
 # Import Borg key
+#
+# Borg does not support using pre-generated keys anymore (as of 2024-05-16).
+#
+# This code is therefore deprecated, but will stay here for a while, as maybe
+# in the long term borg starts to support this again.
+#
+# Check also https://github.com/borgbackup/borg/issues/7047
+#            https://borgbackup.readthedocs.io/en/latest/faq.html#how-important-is-the-home-config-borg-directory
 function hydra_import_keys_borg {
   if [ "`facter fqdn`" != "$hostname" ]; then
     echo "-----------------------------------------------------"
diff --git a/share/hydra/newkeys b/share/hydra/newkeys
index deb9b6e..c53dfe7 100755
--- a/share/hydra/newkeys
+++ b/share/hydra/newkeys
@@ -69,6 +69,13 @@ function hydra_newkeys {
   done
 }
 
+# Borg does not support using pre-generated keys anymore (as of 2024-05-16).
+#
+# This code is therefore deprecated, but will stay here for a while, as maybe
+# in the long term borg starts to support this again.
+#
+# Check also https://github.com/borgbackup/borg/issues/7047
+#            https://borgbackup.readthedocs.io/en/latest/faq.html#how-important-is-the-home-config-borg-directory
 function hydra_newkeys_borg {
   # Check for borg
   #if ! which borg &> /dev/null; then