OPNsense Auto Minor-Update mit ZFS-Snapshot

Automatisiert folgenden Ablauf auf einer OPNsense-Firewall mit ZFS-Root:

1. Prüfen, ob ein Minor-Update verfügbar ist
2. Falls ja: ZFS Boot Environment (Snapshot) erstellen
3. Nur bei erfolgreichem Snapshot: Minor-Update automatisch ausführen
4. Alte Snapshots rotieren (letzte 7 behalten)

Major-Upgrades werden erkannt und bewusst nicht automatisch ausgeführt, da diese offline laufen und laut OPNsense-Empfehlung beaufsichtigt durchgeführt werden sollten.

---

Voraussetzungen

• OPNsense mit ZFS-Root (bectl muss verfügbar sein)
• Root-/SSH-Zugriff auf die Firewall
• Getestet für OPNsense 26.7

---

1. Installation des Skripts

Skript ablegen

fetch -o /usr/local/bin/opn-auto-minor-update.sh <deine-raw-url>
chown root:wheel /usr/local/bin/opn-auto-minor-update.sh
chmod 500 /usr/local/bin/opn-auto-minor-update.sh

500 (r-x------) ist das Minimum, das für die Ausführung als root nötig ist: lesbar und ausführbar, aber nicht beschreibbar. Reicht für Cron/configd völlig aus, da niemand außer root das Skript je aufrufen soll.

Syntax-Check

sh -n /usr/local/bin/opn-auto-minor-update.sh

Manueller Testlauf (mit Ausgabe)

/usr/local/bin/opn-auto-minor-update.sh -v

Für Cron (ohne Ausgabe, nur Syslog):

/usr/local/bin/opn-auto-minor-update.sh

Zum Bearbeiten des Skripts

chmod 700 /usr/local/bin/opn-auto-minor-update.sh
vi /usr/local/bin/opn-auto-minor-update.sh
chmod 500 /usr/local/bin/opn-auto-minor-update.sh

Optional: Skript vor versehentlicher Änderung zusätzlich schützen

chflags schg /usr/local/bin/opn-auto-minor-update.sh

Zum Bearbeiten später wieder aufheben:

chflags noschg /usr/local/bin/opn-auto-minor-update.sh

Hinweis: Dieses Flag schützt nur vor Unfällen/Fehlbedienung, nicht vor einem kompromittierten Root-Zugang (OPNsense hebt kern.securelevel nicht an).

---

2. Skript in der Cron-GUI verfügbar machen

Damit das Skript im Command-Dropdown unter System ‣ Settings ‣ Cron auswählbar ist, muss es als configd-Action registriert werden.

Action-Datei anlegen

vi /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf

Inhalt (reine Unix-Zeilenenden, keine Einrückung, keine Tabs):

[start]
command:/usr/local/bin/opn-auto-minor-update.sh
parameters:
type:script
message:Auto Minor-Update mit ZFS-Snapshot
description:Auto Minor-Update mit ZFS-Snapshot

Rechte setzen (Konfigurationsdatei, wird nie ausgeführt - kein Execute-Bit nötig):

chown root:wheel /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf
chmod 400 /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf

configd neu laden

service configd restart

Testen

configctl autominorupdate start

Erwartete Ausgabe: kein Action not found or not allowed, sondern der Output deines Skripts (bzw. bei -v-losem Aufruf: keine Ausgabe, nur Syslog-Einträge).

In der GUI einrichten

1. System ‣ Settings ‣ Cron → +
2. Zeitplan wählen, z. B. täglich 03:00 Uhr:
   • Minutes: 0
   • Hours: 3
   • Rest: *
3. Command: "Auto Minor-Update mit ZFS-Snapshot" auswählen
4. Save → Apply

---

3. Troubleshooting

Action not found or not allowed

Prüfen in dieser Reihenfolge:

1. configd neu gestartet?

   service configd restart
   

2. Stimmt der Action-Name mit dem Dateinamen überein?

   ls -la /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf
   

   Aufruf muss lauten: configctl autominorupdate start

3. Versteckte Zeichen in der .conf-Datei?

   cat -A /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf
   

   Bei ^I (Tab) oder ^M (Windows-Zeilenende \r) am Zeilenende: Datei neu anlegen, ohne Copy-Paste aus Windows-Editoren.

   Falls die Datei auf 400 gesetzt ist und bearbeitet werden muss:

   chmod 600 /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf
   vi /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf
   service configd restart
   chmod 400 /usr/local/opnsense/service/conf/actions.d/actions_autominorupdate.conf
   

4. Kompletter configd-Neustart statt nur restart:

   pkill -f configd
   service configd start
   

Snapshot-Namen zur Kontrolle ansehen

bectl list -H | grep autosnap-preupdate

Format: autosnap-preupdate-<Zeitstempel>-<Version> Beispiel: autosnap-preupdate-20260726-141530-26.7.1

Logs einsehen

GUI: System ‣ Log Files ‣ General Konsole:

grep opn-auto-minor-update /var/log/system/system_*.log

Manuelles Rollback bei Bedarf

bectl list
bectl activate -t <BE-Name>   # temporär, nur nächster Boot
reboot

---

4. Rechte-Übersicht

Datei	Owner	Normalbetrieb	Zum Bearbeiten
opn-auto-minor-update.sh	root:wheel	500 (r-x------)	700 (rwx------)
actions_autominorupdate.conf	root:wheel	400 (r--------)	600 (rw-------)

Beide Dateien werden ausschließlich von root (Cron/configd) benötigt - Gruppen- und Andere-Rechte sind bewusst auf 0 gesetzt. Das Execute-Bit ist nur beim .sh-Skript nötig (Kernel muss es direkt starten können), bei der .conf-Datei komplett überflüssig, da sie nur gelesen wird.

---

5. Sicherheits-/Härtungshinweise

• Cron-Konfiguration nur lokal/über VPN ändern, nicht über direkt aus dem WAN erreichbare GUI-Sessions
• Skript-Herkunft (Git-Server) nur über verifiziertes HTTPS beziehen, kein -k/--no-verify-peer
• Snapshots ersetzen keine Config-Backups – config.xml zusätzlich getrennt sichern
• Automatisierung niemals über einen von außen erreichbaren Trigger/Webhook auslösbar machen

---

Offene Baustelle (noch nicht umgesetzt)

Automatisches Rollback bei fehlgeschlagenem Boot nach Update (Boot-Counter-Property + früher rc.d-Hook + bectl activate -t). Ist ein separates Vorhaben, unabhängig von diesem Update-Skript.