added readmes (#1)

Co-authored-by: DerLinkman <derlinkman@gmail.com> Reviewed-on: #1
2026-07-18 19:36:54 +00:00
parent 8d64bf5982
commit cab59c1658
7 changed files with 782 additions and 0 deletions
@@ -0,0 +1,119 @@
+# Rolle `bootstrap`
+
+Ersteinrichtung (Provisioning) eines frischen Debian-Hosts. Die Rolle legt den
+Admin-User an, installiert Basispakete, härtet die SSH-Konfiguration, verteilt
+autorisierte SSH-Keys, konfiguriert Tastaturlayout, MOTD, Bash-Aliase und
+sysctl, und bindet optional die Rollen `docker` und `monitoring` ein.
+
+> Siehe auch das Top-Level-Playbook `bootstrap.yml` sowie die
+> [Repo-README](../../README.md).
+
+## Voraussetzungen
+
+- Debian-Ziel-Host
+- SSH-Zugang als Benutzer, der `become` darf (Playbook nutzt `user: admin`)
+- `ansible.posix` Collection (für `sysctl`-Modul)
+
+## Einbindung
+
+Die Rolle wird normalerweise über das Top-Level-Playbook `bootstrap.yml`
+aufgerufen, kann aber auch direkt per `include_role`/`import_role` eingebunden
+werden:
+
+```yaml
+- hosts: all
+  become: true
+  user: admin
+  roles:
+    - role: bootstrap
+```
+
+```bash
+ansible-playbook -i inventory/dmc12.yml --vault-password-file .vault_pass bootstrap.yml
+```
+
+## Funktionsweise
+
+`tasks/main.yml` reiht die Subtasks nacheinander aus und bindet am Ende
+bedarfsabhängig die Rollen `docker` und `monitoring` ein:
+
+1. `install-basicpackages.yml` – Basispakete installieren
+2. `create-admin-user.yml` – Admin-User anlegen + sudoers
+3. `set-motd.yml` – MOTD via fastfetch (`tags: motd`)
+4. `set-keyboardlayout.yml` – QWERTZ-Layout
+5. `install-openssh.yml` – OpenSSH Server/Client (`tags: ssh`)
+6. `configure-ssh.yml` – sshd_config härtbar (`tags: ssh`)
+7. `add-ssh-keys.yml` – authorized_keys verteilen (`tags: ssh`)
+8. `setup-bashrc.yml` – nützliche Aliase (`tags: bashrc`)
+9. `configure-sysctl.yml` – vm.swappiness = 10 (`tags: sysctl`)
+10. `import_role: docker` (sofern nicht `skip_docker`)
+11. `import_role: monitoring` (sofern nicht `skip_monitoring`)
+
+### Installierte Basispakete
+
+`fastfetch`, `htop`, `curl`, `wget`, `git`, `sudo`, `console-setup`,
+`qemu-guest-agent`, `cron`, `net-tools`, `tcpdump`, `locales-all`.
+
+### SSH-Härtung
+
+Die Vorlage `templates/sshd.conf.j2` deaktiviert Root-Login und
+Passwort-Authentifizierung, erlaubt ausschließlich Publickey-Auth und setzt
+restriktive Forwarding-/Logging-Optionen. Nach Änderung wird der sshd via
+Handler neu gestartet.
+
+## Variablen
+
+| Variable                | Typ      | Default           | Beschreibung                                        |
+|-------------------------|----------|-------------------|-----------------------------------------------------|
+| `admin_authorized_keys` | list     | siehe `defaults/` | Liste von `{ key, comment }`-Einträgen für `admin` |
+| `admin_password`        | string   | siehe `defaults/` | SHA-512-Hash des Admin-Passworts                    |
+
+### Steuer-Variablen (keine Defaults, optional setzen)
+
+| Variable           | Typ    | Default | Beschreibung                                              |
+|--------------------|--------|---------|-----------------------------------------------------------|
+| `skip_docker`      | bool   | `false` | Wenn `true`, wird die `docker`-Rolle übersprungen        |
+| `skip_monitoring`  | bool   | `false` | Wenn `true`, wird die `monitoring`-Rolle übersprungen    |
+| `ssh_service_name` | string | `sshd`  | Name des SSH-Service (überschrieben bspw. für `ssh`)    |
+
+`admin_authorized_keys` wird auch pro Inventory in `group_vars/external.yml`
+überschrieben. Der Handler `Restart sshd` verwendet `ssh_service_name`, sofern
+gesetzt (z. B. `ssh` für `gitea`/`ipam` in `inventory/dmc12.yml`).
+
+## Templates
+
+| Template               | Ziel                                           |
+|------------------------|------------------------------------------------|
+| `sshd.conf.j2`         | `/etc/ssh/sshd_config` (validiert via `sshd -T`) |
+| `authorized_keys.j2`  | `/home/admin/.ssh/authorized_keys`            |
+| `sudoers-admin.j2`    | `/etc/sudoers.d/10-admin` (validiert via `visudo -cf`) |
+| `keyboard.j2`         | `/etc/default/keyboard`                        |
+
+## Handler
+
+| Handler                 | Auslöser                                  |
+|-------------------------|-------------------------------------------|
+| `Restart sshd`          | Änderung an `sshd_config`                 |
+| `Reload keyboard layout`| Änderung an `/etc/default/keyboard`       |
+
+## Tags
+
+`motd`, `ssh`, `bashrc`, `sysctl` – ermöglichen das gezielte Re-Apply einzelner
+Teile, z. B.:
+
+```bash
+ansible-playbook bootstrap.yml -i inventory/dmc12.yml -t ssh
+```
+
+## Abhängigkeiten
+
+- `docker` (optional, via `import_role`)
+- `monitoring` (optional, via `import_role`)
+
+## Hinweise
+
+- `configure-sysctl.yml` wird auf LXC-Containern übersprungen
+  (`virtualization_type != "lxc"`).
+- `setup-bashrc.yml` legt Aliase für alle regulären User inkl. root an.
+- `install-openssh.yml` entfernt ggf. das Meta-Paket `ssh` vor der
+  Installation von `openssh-server`/`openssh-client`.