added docs

2026-09-15 18:53:28 +02:00
parent db60b5a2ea
commit 343fe9b22f
8 changed files with 929 additions and 0 deletions
@@ -0,0 +1,69 @@
+# AIM Recovery Guide
+
+## Principle
+
+Git protects source code, not AIM's ignored runtime secrets.
+
+A `git reset --hard` or fresh checkout cannot restore ignored data such
+as inventory Vaults, SSH keys or a Python virtual environment.
+
+## Critical persistent data
+
+Back up separately:
+
+``` text
+/etc/ansible/inventories/<customer>/group_vars/all/vault.yml
+/etc/ansible/inventories/<customer>/group_vars/linux/.ssh/
+```
+
+Other customer inventory YAML should also be covered by the system
+backup policy.
+
+## Rebuildable data
+
+Do not recover `.venv` from Git. Rebuild it:
+
+``` bash
+sudo rm -rf /etc/ansible/.venv
+sudo python3 -m venv /etc/ansible/.venv
+sudo /etc/ansible/.venv/bin/python -m pip install --upgrade pip setuptools wheel
+sudo /etc/ansible/.venv/bin/python -m pip install -e /etc/ansible/scripts
+sudo ln -sfn /etc/ansible/.venv/bin/aim /usr/local/bin/aim
+```
+
+## Recover Vaults and SSH keys from a filesystem backup
+
+When restoring from a backup tree, copy only files that do not already
+exist in the active inventory. Never overwrite surviving current secrets
+as part of a bulk recovery.
+
+See `../install.md` for the current dry-run and restore commands.
+
+## AIM session inventory backup
+
+AIM can create:
+
+``` text
+hosts.aim-session.bak.yml
+```
+
+This is a pre-change recovery aid, not the primary backup strategy for
+customer secrets.
+
+Restore from it only through an explicit recovery decision after
+validating the relevant inventory state.
+
+## Post-recovery validation
+
+Before deleting the backup source:
+
+1.  Confirm Vault files exist for expected customers.
+2.  Confirm SSH private/public key files and permissions.
+3.  Test Vault decryption/access for representative customers.
+4.  Test Linux SSH authentication.
+5.  Test Windows WinRM for representative domain/local credential
+    models.
+6.  Test any other customer-specific access that depends on recovered
+    secrets.
+
+Keep the filesystem backup until these checks pass.