oopen-server/roles/ipt-server/MIGRATION.md

ipt-server — Migrationsleitfaden

Dieser Leitfaden beschreibt, wie ein bestehender Host vom alten Verfahren (manuell verwaltete /etc/ipt-firewall/-Dateien, ggf. firewall- oder modify-ipt-server-Rolle) auf die neue ipt-server-Ansible-Rolle umgestellt wird.

---

Überblick

Das alte Verfahren:

• Firewall-Skripte und Conf-Dateien wurden manuell oder über die alte firewall-Rolle (lineinfile/blockinfile) gepflegt.
• Änderungen direkt in /etc/ipt-firewall/ auf dem Host.

Das neue Verfahren:

• Alle Firewall-Einstellungen liegen in host_vars/${HOSTNAME}/ipt-server.yml.
• Ansible deployt die Config-Dateien aus Jinja2-Templates.
• Direktes Editieren auf dem Host ist nicht mehr vorgesehen.

Die Migration ist nicht-destruktiv: Bestehende Config-Dateien werden erst dann überschrieben, wenn die Migration explizit freigegeben wird (fw_manage_config: true).

---

Schritt 1 — Aktuellen Stand einfrieren

Vor jeder anderen Änderung den Zustand der laufenden Firewall-Rules sichern. Das ist der Referenzwert für den späteren Vergleich mit den Ansible-generierten Rules.

HOSTNAME=<hostname>

ssh -t ${HOSTNAME} '
  sudo iptables-save  | grep -v "^#" | sed "s/\[[0-9]*:[0-9]*\]/[0:0]/g" \
    > /tmp/fw_before_v4.rules
  sudo ip6tables-save | grep -v "^#" | sed "s/\[[0-9]*:[0-9]*\]/[0:0]/g" \
    > /tmp/fw_before_v6.rules
  echo "Stand gesichert."
'

---

Schritt 2 — Aktuelle Konfiguration auslesen

Das Skript extract-fw-host-vars.py liest die vier Conf-Dateien vom Host via SSH, mappt alle Variablen auf die fw_*-Ansible-Variablen und schreibt eine fertige host_vars-Datei:

cd /path/to/ansible/oopen-server
HOSTNAME=<hostname>

./extract-fw-host-vars.py ${HOSTNAME} --sudo \
  -o host_vars/${HOSTNAME}/ipt-server.yml

Das Skript fragt einmalig nach dem sudo-Passwort.

Ergebnis prüfen:

cat host_vars/${HOSTNAME}/ipt-server.yml

Kontrollpunkte:

• Sind fw_ext_interfaces, fw_ext_ips_v4, fw_ext_ips_v6 korrekt?
• Sind aktivierte Dienste (Mail, HTTP, VPN usw.) vorhanden?
• Sind munin_remote_ipv4 / munin_remote_ipv6 eingetragen (falls Munin läuft)?

Fehlende oder falsche Werte können direkt in der YAML-Datei korrigiert werden. Alle Variablen und ihre Bedeutung stehen in defaults/main.yml.

---

Schritt 3 — Erste Ausrollung (Safety-Guard aktiv)

Solange fw_manage_config nicht auf true gesetzt ist (Default: false), überschreibt Ansible keine bestehenden Config-Dateien. Es werden nur installiert:

• Firewall-Skripte → /usr/local/sbin/
• Geteilte Conf-Dateien → /etc/ipt-firewall/
• Systemd-Units → /etc/systemd/system/

HOSTNAME=<hostname>

# Vorschau:
ansible-playbook ipt-server.yml --limit ${HOSTNAME} --check --diff

# Ausrollen:
ansible-playbook ipt-server.yml --limit ${HOSTNAME}

Die host-spezifischen Config-Dateien (main_ipv4.conf, main_ipv6.conf, interfaces_ipv4.conf, interfaces_ipv6.conf) bleiben unangetastet.

Ändern sich jedoch Firewall-Skripte, geteilte Conf-Dateien oder Systemd-Units (typisch bei Erstinstallation), wird die Firewall neu gestartet — mit den bestehenden Config-Dateien, also ohne inhaltliche Regeländerung.

---

Schritt 4 — Ansible als autoritative Quelle freischalten und verifizieren

Jetzt wird fw_manage_config: true gesetzt, damit Ansible die vier host-spezifischen Config-Dateien aus den Templates schreibt:

# host_vars/${HOSTNAME}/ipt-server.yml
---
fw_manage_config: true   # ← hinzufügen / auf true setzen

fw_ext_interfaces:
  - "eth0"
# ...

Vorschau: Zeigt genau, was in den Config-Dateien geändert wird — hier sorgfältig prüfen, ob die neuen Werte den alten entsprechen:

HOSTNAME=<hostname>

ansible-playbook ipt-server.yml --limit ${HOSTNAME} --check --diff

Anwenden: Ansible schreibt die neuen Config-Dateien und startet die Firewall automatisch neu (da sich die Dateien geändert haben):

ansible-playbook ipt-server.yml --limit ${HOSTNAME}

Verifizieren: Jetzt die neuen Rules mit dem gesicherten Stand vergleichen:

ssh -t ${HOSTNAME} '
  sudo iptables-save  | grep -v "^#" | sed "s/\[[0-9]*:[0-9]*\]/[0:0]/g" \
    > /tmp/fw_after_v4.rules
  sudo ip6tables-save | grep -v "^#" | sed "s/\[[0-9]*:[0-9]*\]/[0:0]/g" \
    > /tmp/fw_after_v6.rules
  echo "=== IPv4 diff ==="
  diff /tmp/fw_before_v4.rules /tmp/fw_after_v4.rules
  echo "=== IPv6 diff ==="
  diff /tmp/fw_before_v6.rules /tmp/fw_after_v6.rules
'

Erwartetes Ergebnis: Beide Diffs sind leer — die Ansible-generierten Config-Dateien produzieren exakt dieselben Rules wie die bisher händisch verwalteten.

Falls Unterschiede erscheinen: die abweichenden Rules identifizieren, die entsprechenden Variablen in host_vars/${HOSTNAME}/ipt-server.yml nachpflegen, erneut ausrollen und den Diff wiederholen.

Ab jetzt:

• Ansible überschreibt die vier Config-Dateien bei jedem Run aus den Templates.
• Bei Änderungen an Templates oder host_vars wird die Firewall automatisch neu gestartet.
• Direktes Editieren von /etc/ipt-firewall/interfaces_*.conf oder main_*.conf auf dem Host wird beim nächsten Ansible-Run überschrieben.

---

Schritt 5 — Altes System deaktivieren

Altes Ansible-Vorgehen abschalten

Sicherstellen, dass der Host nicht mehr durch die alte firewall-Rolle oder modify-ipt-server-Rolle verwaltet wird. Falls der Host in einem Playbook eingetragen ist, das diese Rollen verwendet, den Host dort entfernen oder das Playbook anpassen.

Altes git-Repository auf dem Host entfernen (optional)

Das Repository /usr/local/src/ipt-server wird von der neuen Rolle nicht mehr benötigt. Es kann entfernt werden:

HOSTNAME=<hostname>

ssh ${HOSTNAME} 'rm -rf /usr/local/src/ipt-server'

Vorher prüfen, ob das Verzeichnis noch anderweitig verwendet wird.

Sicherstellen, dass niemand mehr direkt editiert

Da fw_manage_config: true gesetzt ist, werden direkte Änderungen in /etc/ipt-firewall/ beim nächsten Ansible-Run überschrieben. Als zusätzliche Absicherung enthält jede von Ansible generierte Config-Datei oben folgenden Hinweis (via {{ ansible_managed }}):

# Ansible managed
# DO NOT EDIT - changes will be overwritten on the next Ansible run.
# Edit host_vars/${HOSTNAME}/ipt-server.yml instead.

---

Zusammenfassung

Schritt	Befehl / Aktion	Wann
1	Aktuellen Rules-Stand auf dem Host sichern	Einmalig pro Host
2	extract-fw-host-vars.py ausführen, Ergebnis prüfen	Einmalig pro Host
3	Erste Ausrollung (Safety-Guard aktiv) — Skripte + Units	Einmalig pro Host
4	fw_manage_config: true + --check --diff + ausrollen + Rules vergleichen	Einmalig pro Host
5	Alte Rolle deaktivieren, git-Repo auf Host entfernen	Einmalig pro Host
—	Änderungen: host_vars editieren + ansible-playbook	Ab jetzt immer so