docs: document installation, secrets, and setup steps

2026-05-03 19:33:03 +02:00
parent de4b8833bd
commit 22b3a95bf8
3 changed files with 97 additions and 1 deletions
@@ -0,0 +1,28 @@
+# Secrets
+
+Secrets are managed with `agenix` in the `agenix/` directory. This allows to declaratively define secrets as well as which keys are allowed to decrypt them.
+
+# Usage
+
+The `agenix` help menu is already very helpful, but here you have a survival guide:
+
+- `agenix` commands should run relative to the `agenix/` direcotry.
+- `agenix -d` allows you to descrypt such file if you possess any of the decryption keys.
+- `agenix -e` decrypts (if present) and opens the file in your editor to re-encrypt when exited.
+- `agenix -r` re-encypts `*.age` files in the case you ever change its decryption keys.
+
+# Secrets
+
+<!-- TODO: missing ntfy.sh secret docs -->
+
+## DNS TSIG Keys
+
+The DNS server takes zone updates through `nsupdate` with symmetric TSIG keys.
+
+These keys can be generated using `tsig-keygen <key-name>` (historically they were done with `dnssec-keygen` and `HMAC` algorithms, but this is no longer supported).
+
+When DNS is enabled for a host, it will look for `dns/${fqdn}/${zone}.key` secrets.
+
+- The key whose zone matches the `${fqdn}` will be allowed to tramit updates for all the domain.
+- Keys restrained to a specific `${subdomain}` will only be allowed to edit records of such subdomain.
+- All keys must be named with the zone they affect, final dot included, so that (e.g. `tuxcord.net/javalsai.tuxcord.net.key` must be generated by `tsig-keygen javalsai.tuxcord.net.`).