Skip to content

OPNsense HA-Updates (CARP-Paare) ​

Seit v3.7.0 fuehrt DATAZONE Control OPNsense-Updates als Update-Laeufe aus. Ein Lauf ist eine Zustandsmaschine im Backend, die mehrere Firewalls in der richtigen Reihenfolge aktualisiert, jeden Schritt nachpruefbar verifiziert und bei jeder bekannten Stoerung selbst entscheidet: wiederholen, sauber abbrechen oder den Zustand heilen. Ziel ist der unbeaufsichtigte Nachtlauf - ohne dass morgens ein Techniker einen halb fertigen Job retten muss.

Fuer wen?

Diese Seite beschreibt das Verhalten im Detail. Wer nur einen Zeitplan anlegen will: OPNsense > Jobs > Neu, Typ Update + Reboot, HA-Modus Rollierend (Standard), fertig.

Update-Typen ​

TypWas passiertReboot
System UpdateNur Pakete (opnsense-update -pt). Base/Kernel-Updates werden nicht installiert, sondern als Reboot ausstehend gemeldetnie
Update + RebootPakete + Base/Kernel; Reboot nur, wenn OPNsense ihn tatsaechlich verlangt (Base/Kernel installiert oder system.firmware.reboot)wenn noetig
Major UpgradeHauptversionen Sprung fuer Sprung bis zur Zielversion oder zur neuesten angebotenen Version (z. B. 23.7 → 24.1 → … → 26.7), mit normalem Update vor jedem Sprungzwei Reboots je Sprung

Alle drei Typen laufen ueber dieselbe Maschine. Der Unterschied ist nur, was der Agent darf.

Voraussetzungen ​

  • Agent ≥ 3.7.0 auf jeder Firewall. Aeltere Agents werden in einem Lauf immer uebersprungen (Grund Agent zu alt), denn der alte Agent rebootet bedingungslos und kennt kein CARP.
  • Fuer rollierende Updates: beide Nodes online, CARP-Rollen genau ein MASTER und ein BACKUP, kein aktiver Maintenance-Modus, Peer-Zuordnung bekannt (siehe unten).
  • pfsync und Konfigurations-Synchronisation wie von OPNsense empfohlen eingerichtet.

Spalte „Update“: ist die Firewall bereit? (seit v3.12.0) ​

Die OPNsense-Liste zeigt in der Spalte Update je Firewall einen Punkt:

  • gruen „bereit“: Ein Update mit Neustart wuerde diese Firewall jetzt anfassen.
  • rot mit Grund: Der Lauf wuerde sie ueberspringen. Beim Ueberfahren steht, was zu tun ist.
  • blau „Update laeuft gerade“: Die Firewall steckt in einem Lauf.

Die Spalte nutzt dieselben Regeln wie der Update-Lauf. Was dort rot ist, wird im Lauf mit demselben Satz uebersprungen. Derselbe Satz steht im Lauf-Detail und in der Benachrichtigung (Teams, E-Mail).

GrundWas tun
Agent zu alt (unter 3.7.0)Zuerst den Agent aktualisieren.
Agent des HA-Partners zu altAgent auf dem Partner aktualisieren.
Firewall offline / HA-Partner offlineVerbindung pruefen. Ein Paar wird nur mit beiden Nodes neu gestartet.
CARP-Wartungsmodus aktivIn OPNsense unter Interfaces > Virtual IPs > Status aufheben, wenn niemand mehr daran arbeitet.
HA-Rollen unklarCARP-Status beider Nodes pruefen. Es muss genau ein MASTER und ein BACKUP geben.
HA-Partner nicht erkanntBeide Nodes muessen in Control sein. HA-Sync pruefen (System > High Availability).
HA-Zuordnung strittigEine andere Firewall meldet sich als Partner. Den richtigen Partner als Admin festlegen (siehe Beidseitige Bestaetigung).

Firewalls ohne CARP-VIPs pruefen nur Agent-Version und Online-Status. Ein reines Paket-Update ohne Neustart laeuft bei einem Paar mit offline Partner trotzdem auf dem erreichbaren Node, die Spalte zeigt den strengeren Fall mit Neustart.

Es gibt dafuer keine Einstellung im Job. Legacy-IPsec, Legacy-Regeln und MSS werden bewusst nicht im Update geprueft, sondern ueber die Checks gleichen Namens.

Waehrend eine Firewall in einem Update-Lauf steckt, meldet die Benachrichtigung sie nicht als offline. Das gilt bis zum Ende des Health-Checks nach dem Schritt. Der geplante Neustart loest also keinen Offline-Alarm mit Entwarnung mehr aus. Das Ergebnis des Laufs wird wie bisher gemeldet.

HA-Paar-Erkennung ​

Der Agent meldet im Heartbeat den CARP-Zustand (Rolle je VHID, Maintenance, Demotion, pfsync-Peer-IP aus config.xml). Control bildet daraus Paare:

  1. Die pfsync-Peer-IP einer Firewall ist eine Interface-IP einer anderen Firewall desselben Kunden.
  2. Ersatzweise: identische CARP-VIPs (VHID + Adresse) bei zwei Firewalls desselben Kunden.

Die Zuordnung steht in der Firewall-Tabelle (Spalte HA: MASTER / BACKUP / MAINT / INIT, Peer im Tooltip) und im Detail-Panel. Ueber die API (POST /api/firewalls/<id>/ha-peer) kann eine Zuordnung manuell gesetzt und gesperrt werden. Eine gesperrte Zuordnung (locked) gilt ueberall: weder die automatische Erkennung noch die Lauf-Planung oder die Spalte Update paaren eine gesperrte Firewall ueber identische VIPs. Als Paar zaehlt nur, was beidseitig eingetragen ist. Firewalls mit CARP-VIPs, aber ohne bekannten Partner, werden bei Updates mit Reboot uebersprungen (HA-Partner unbekannt) - nie blind rebootet.

Beidseitige Bestaetigung (ab v3.48.13) ​

Die Daten im Heartbeat kommen vom Agent der Firewall selbst. Damit eine einzelne (z. B. kompromittierte) Firewall sich nicht als Partner eines echten Paars eintragen kann, gilt:

  • Ein Paar entsteht automatisch nur, wenn beide Nodes aus ihren eigenen Heartbeats genau den jeweils anderen als Partner ergeben (pfsync-Peer-IP von A ist eine Interface-IP von B und umgekehrt, oder beide melden dieselben CARP-VIPs und finden jeweils nur den anderen). Der Heartbeat einer Firewall aendert die Zuordnung der anderen nur, wenn deren letzter Heartbeat ebenfalls auf sie zeigt.
  • Mitgezaehlt werden nur Firewalls desselben Kunden mit Heartbeat in den letzten 15 Minuten. Firewalls ohne Kunde werden nie automatisch gepaart (dann manuell zuordnen). Paare ueber Kundengrenzen entstehen nie, auch nicht manuell.
  • Nutzen mehrere Standorte eines Kunden dasselbe Sync-Netz, gewinnt der Node, dessen eigene pfsync-Peer-IP auf diese Firewall zeigt bzw. der dieselben VIPs hat.
  • Ein bestehendes, beidseitiges Paar wird nie automatisch umgestellt. Meldet sich eine weitere Firewall mit passender IP oder denselben VIPs, bleibt das Paar, wie es ist, und Control legt einen HA-Konflikt an: Log-Eintrag, Warnung im HA-Kasten der Firewall (Reiter Updates) und in der Spalte Update der Grund HA-Zuordnung strittig. Solange der Konflikt besteht, werden die Firewall und ihr Partner in keinem Update-Lauf angefasst, und die automatische Erkennung fuer diese Firewall ruht.
  • Aufloesen: als Admin den richtigen Partner festlegen (POST /api/firewalls/<id>/ha-peer mit peer_id und locked). Das loescht den Konflikt beider Firewalls. Danach die fremde Firewall pruefen - eine Firewall, die die IP oder VIPs eines anderen Paars meldet, ist falsch konfiguriert oder manipuliert.

Node-IP statt VIP

Seit v3.7.0 meldet der Agent die eigene Interface-Adresse, nicht mehr die CARP-VIP, die auf beiden Nodes identisch ist.

Ablauf eines rollierenden Laufs ​

Zeitplan faellig
   │
   ├─ Planung: Paare bilden, Vorbedingungen pruefen, alte Agents/Offline-Nodes als "uebersprungen" eintragen
   │
   ├─ Schritt 1 ── BACKUP-Node ──────────────────────────────────────────────┐
   │     preflight → backup(config.xml) → packages → basekernel → report   │
   │     → Reboot → Node kommt zurueck (boot_time neu) → Health-Check        │
   │                                                                          │
   ├─ Settle-Zeit (Standard 300 s, pfsync-Resync)                             │
   │                                                                          │
   ├─ Schritt 2 ── MASTER-Node ──────────────────────────────────────────────┤
   │     preflight → ... → CARP-Maintenance EIN → Peer uebernimmt (≤ 90 s)   │
   │     → Reboot → Node kommt zurueck → Agent loest Maintenance selbst      │
   │     → Health-Check (genau ein MASTER im Paar, keine Maintenance)         │
   │                                                                          │
   └─ Ergebnis im Jobs-Tab ──────────────────────────────────────────────────┘

Einzel-Firewalls (ohne HA) laufen parallel zueinander als jeweils ein Schritt. Verschiedene HA-Paare laufen ebenfalls parallel; innerhalb eines Paares strikt nacheinander.

Health-Check nach dem Reboot ​

Ein Node gilt erst als gesund, wenn alle Bedingungen fuer mindestens 60 Sekunden gelten und in dieser Zeit ein weiterer Heartbeat eingetroffen ist (ein einzelner gruener Messwert reicht nicht). Aendert sich die Boot-Zeit waehrend der Pruefung noch einmal (zweiter Reboot beim Major-Upgrade), startet die Uhr neu; bleibt der Heartbeat laenger als 3 Minuten aus, gilt der Node nicht als gesund:

  • Version entspricht der vom Agent gemeldeten Zielversion (bei Major: Prefix der Zielversion)
  • Kernel-Version hat sich geaendert, wenn ein Base/Kernel-Update installiert wurde
  • kein Reboot ausstehend
  • bei HA: Maintenance aus, CARP-Rolle MASTER oder BACKUP, Peer online, im Paar genau ein MASTER
  • mindestens ein Gateway online, sofern vor dem Update eines online war

Zeitfenster: Health-Check Timeout (rollierend mindestens 900 s, Einzel-Firewalls 600 s, Major 2700 s) fuer die Rueckkehr nach dem Reboot, danach 300 s (Major 600 s) fuer die Konvergenz der Bedingungen. Haengt der Node in Maintenance, schickt Control einmal eine Remediation (OPN_CARP_MAINTENANCE off) und verdoppelt dafuer das Konvergenz-Fenster.

Rollen nach dem Lauf

OPNsense hat Preempt standardmaessig aus. Nach dem Lauf kann der vorherige BACKUP-Node MASTER bleiben. Das ist kein Fehler - gefordert ist nur, dass es genau einen MASTER gibt.

CARP-Maintenance ​

Vor dem Reboot des MASTER setzt der Agent den persistenten CARP-Maintenance-Modus (configctl interface carp_set_status maintenance, Demotion 240, in config.xml gespeichert). Der Peer uebernimmt alle VIPs; uebernimmt er nicht innerhalb von 90 Sekunden, nimmt der Agent den Modus zurueck und der Schritt schlaegt fehl - ohne Reboot.

Weil der Modus den Reboot ueberlebt, kommt der Node als BACKUP zurueck. Der Agent hebt den Modus nach dem Start selbst auf (sobald das System 60 s laeuft und configd antwortet, Wiederholung bis 15 Minuten) - unabhaengig davon, ob das Backend erreichbar ist. Der BACKUP-Node bekommt nie Maintenance (er traegt keinen Verkehr).

Seit v3.14.2 gilt zusaetzlich:

  • Maintenance wird nur gesetzt, wenn ein erreichbarer Partner uebernehmen kann. Ein MASTER ohne online-Partner (Policy Online-Node trotzdem updaten, Einzelziel) wird ohne Maintenance neu gestartet - der Reboot ist dann ein kurzer Ausfall, kein Failover. Der Schritt traegt den Hinweis.
  • Antwortet configd nicht, ist der Maintenance-Zustand unbekannt, nicht "aus": der Agent startet kein Update (Fehlerklasse transient, Wiederholung), loescht keinen Freigabe-Marker und meldet bei der manuellen Aktion keinen Erfolg.
  • Die Rolle wird unmittelbar vor der Maintenance-Entscheidung neu gelesen (nach einer Stunde Paketinstallation kann der Peer inzwischen ausgefallen sein).
  • Der Agent bleibt bis zum tatsaechlichen Reboot gesperrt (kein Agent-Update, kein zweiter Task) und gibt die Maintenance nach einem Neustart erst frei, wenn OPNsense keinen weiteren Reboot mehr vorgemerkt hat (zweiter Reboot beim Major-Upgrade).

Seit v3.48.3:

  • Control erlaubt die Maintenance fuer jeden Node eines Paars mit erreichbarem Partner - nicht mehr nur fuer den Node, der beim Start MASTER war. Der Agent entscheidet unmittelbar vor dem Neustart nach der Rolle, die er dann liest: Maintenance bekommt nur ein Node, der auf mindestens einer VHID MASTER ist. Ein BACKUP, der inzwischen MASTER geworden ist, ein mixed-Node und Paare, die nur ueber identische VIPs erkannt wurden, schwenken damit sauber um; ein reiner BACKUP (auch BACKUP + INIT) bekommt nie Maintenance. Noetig ist Agent 3.48.3 (aeltere Agents schalteten auch mixed-Nodes ohne MASTER-VHID in Maintenance).
  • Scheitert ein Schritt, nachdem der Agent die Maintenance schon gesetzt hatte, schickt Control sofort die Freigabe (OPN_CARP_MAINTENANCE off) - vorher bekam sie nur ein Schritt im Health-Check.

Manuell: Detail-Panel > Updates > CARP-Maintenance aktivieren/aufheben.

Optionen im Zeitplan ​

OptionBedeutungStandard
HA-ModusRollierend (Backup → Master), HA-Paare ueberspringen, Parallel (altes Verhalten, Komplettausfall beim Reboot)Rollierend
Settle-ZeitWartezeit zwischen den beiden Nodes300 s (Major mind. 60 s)
Wenn ein Peer offline istPaar ueberspringen oder Online-Node trotzdem updaten - dann ohne CARP-Maintenance, der Reboot ist ein kurzer Ausfallueberspringen
WiederholungenErneute Versuche bei Mirror-/Netzfehlern oder abgebrochenem Agent (5/10/15 min Abstand)3
Health-Check TimeoutWartezeit auf die Rueckkehr nach dem Reboot (rollierend mindestens 900 s)900 s
WartungsfensterNach Ablauf wird kein weiterer Schritt gestartet (laufender wird zu Ende verifiziert); erlaubt 15-720 min180 min in der Oberflaeche (API-Standard 60)
ZielversionNur Major Upgrade: Neueste oder JJ.1 / JJ.7 (Community) bzw. JJ.4 / JJ.10 (Business)Neueste

Ein Zeitplan, der nur einen Node eines Paares adressiert, zieht den Partner nicht still mit: Er aktualisiert nur diesen Node (mit Maintenance, falls er MASTER ist und der Partner online ist). Ist auf dem Node bereits Maintenance aktiv, wird er uebersprungen (Wartungsmodus aktiv), nicht fehlgeschlagen. Die Belegt-Pruefung gilt fuer das ganze Paar: solange ein Schritt auf gw1 laeuft, wartet ein zweiter Lauf auf gw2 bzw. ein manueller Task wird mit HTTP 409 abgelehnt. Seit v3.48.3 gilt das auch fuer einfache Tasks: Install + Reboot, Neustart, Major-Upgrade, CARP-Maintenance an oder Config-Wiederherstellung auf gw2 werden abgelehnt (HTTP 409 mit dem belegten Node), solange auf gw1 ein Update-, Neustart- oder Wiederherstellungs-Task offen ist; eine Sammelaktion laesst den zweiten Node eines Paars aus. Agent-Updates und CARP-Maintenance aufheben werden nie gesperrt.

Bevor der zweite Node eines rollierenden Paars mit Reboot-Erlaubnis angefasst wird, prueft Control seinen Partner erneut (v3.48.3): online (Heartbeat innerhalb von 3 Minuten, dieselbe Regel wie bei der Planung), keine CARP-Maintenance, sein Schritt nicht gescheitert. Sonst bleibt der Node, wie er ist - unangetastet wird er uebersprungen (HA-Partner offline / CARP-Wartungsmodus aktiv / Partner-Node nicht erfolgreich), eine Major-Kette, die ihn schon veraendert hat, stoppt auf der erreichten Version (Lauf mit Warnungen). Das gilt auch zwischen allen Schritten einer Major-Kette.

Was passiert bei Stoerungen? ​

StoerungVerhalten
Mirror/Repository nicht erreichbarSchritt wird wiederholt (5/10/15 min), dann Lauf fehlgeschlagen, Paar unangetastet
Platte zu voll (weniger als 1 GB frei, Major weniger als 2 GB; einstellbar unter Einstellungen > Parameter: opnsense_update_min_free_gb / opnsense_update_min_free_gb_major, Agent ab 3.17.8, aeltere Agents pruefen 15 %)Schritt fehlgeschlagen, kein Wiederholen
opnsense-update/pkg laeuft bereits (auch verwaist)bis 10 min warten, dann wiederholen
Agent stirbt mitten im UpdateErgebnis unterbrochen beim Reconnect, Wiederholung (das Update ist idempotent)
Agent ist noch mit dem vorigen Versuch beschaeftigt (busy)wird wie transient wiederholt
Zeitbudget ueberschritten (150 min, Major 225 min - mehr als alle Agent-Timeouts)Schritt timeout, kein zweiter Start auf dem Node, Lauf fehlgeschlagen
Major: Zielversion wird nicht angebotenDie Kette stoppt auf der letzten erreichten Version (Zielversion wird nicht angeboten), Partner wird nicht angefasst
Major: Firmware-Pruefung zwischen zwei Spruengen schlaegt fehlWiederholung wie transient, dann Firmware-Pruefung fehlgeschlagen
configd antwortet nicht (CARP-Zustand unbekannt)Schritt transient, Wiederholung - kein Update ohne bekannten Maintenance-Zustand
Node kommt nach dem Reboot nicht zurueckLauf fehlgeschlagen, Peer bleibt MASTER, zweiter Node wird nicht angefasst
Partner geht vor dem zweiten Node (oder zwischen dessen Schritten) offline oder scheitertzweiter Node wird nicht neu gestartet - uebersprungen bzw. Kette mit Grund gestoppt
Befehl haengt (Mirror antwortet nicht)der Agent beendet bei der Zeitgrenze der Phase die ganze Prozessgruppe, die Phase endet (Agent 3.48.3; vorher konnte ein haengendes pkg das Update endlos blockieren)
Node zurueck, Maintenance haengtRemediation-Task, erneuter Health-Check
Rollen nicht MASTER/BACKUP (INIT, Split-Brain)Paar uebersprungen, bevor etwas veraendert wird
Zeitplan startet > 30 min zu spaet (Backend/Worker war down)Lauf verpasst, nichts wird ausgefuehrt - kein Failover um 9 Uhr morgens
Wartungsfenster ueberschrittenkeine neuen Schritte, Lauf unvollstaendig
Zweiter Zeitplan oder manueller Klick auf dieselbe Firewall oder ihren HA-Partnerwartet bzw. wird mit HTTP 409 abgelehnt
Agent-Auto-Update oder Reboot-Task waehrend des Updateswird abgelehnt/verschoben
Backend-Neustart mitten im LaufZustand liegt in der Datenbank, der naechste Tick macht weiter

Ergebnis lesen (Jobs-Tab) ​

  • Banner oben: laufende Laeufe und Laeufe der letzten 24 h mit Problemen.
  • Status-Punkt des Zeitplans: gruen = erfolgreich, orange = teilweise/unvollstaendig/verpasst, rot = fehlgeschlagen.
  • Zeile aufklappen: die letzten fuenf Laeufe mit Schritt-Chips (gw2 BACKUP ✓ → gw1 MASTER ✗ health_timeout).
  • Klick auf einen Lauf: Detail mit Phasen, Versionen, Fehlerklasse, vollstaendiger Ausgabe und Live-Fortschritt.
  • Fortsetzen: plant nur die fehlgeschlagenen/uebersprungenen Nodes als neuen Lauf; Rollen werden neu aus dem CARP-Zustand gelesen.
  • Abbrechen: keine neuen Schritte. Ein Task, den der Agent noch nicht abgeholt hat, verfaellt sofort (er wird nie mehr ausgefuehrt); ein Schritt, der auf dem Agent schon laeuft, wird noch zu Ende verifiziert. Der Lauf endet danach mit Status abgebrochen und Zusammenfassung.

Im Logs-Tab tragen die Einzel-Tasks ein Badge Lauf #n.

API ​

EndpunktZweck
GET /api/update-runs?schedule_id=&status=&firewall_id=&limit=Laeufe listen
GET /api/update-runs/<id>Lauf mit Schritten und Task-Ergebnissen
POST /api/update-runsLauf sofort starten (firewall_ids / host_group_id / customer_id, update_type, ha_mode, include_peers)
POST /api/update-runs/<id>/abort · /resumeAbbrechen / fortsetzen
POST /api/firewalls/<id>/ha-peerPeer manuell setzen (peer_id, locked)
POST /api/firewalls/<id>/carp-maintenanceMaintenance an/aus (`state: on

Major-Upgrade ueber mehrere Versionen (ab 3.17.0) ​

OPNsense bietet immer nur die naechste Hauptversion an (Community: Reihen JJ.1 im Januar, JJ.7 im Juli; Business: JJ.4 und JJ.10). Von 23.7 auf 26.7 sind das sechs Spruenge. Ein Major-Upgrade-Lauf erledigt alle in einem Durchgang:

  1. Normales Update mit Reboot (alle offenen Pakete der aktuellen Version)
  2. Pruefung (OPN_UPGRADE_CHECK): welche Hauptversion bietet der Mirror jetzt an?
  3. Sprung auf diese Version (OPN_MAJOR_UPGRADE, zwei Reboots), Pruefung wie immer
  4. weiter mit 1., bis die Zielversion erreicht ist bzw. bei Neueste keine neuere Version mehr angeboten wird
ZielversionEnde
Neueste (Standard)keine neuere Hauptversion mehr angeboten - die Firewall steht auf dem neuesten Stand
JJ.1 / JJ.7 (Community), JJ.4 / JJ.10 (Business)diese Version erreicht; wird sie unterwegs nicht angeboten, stoppt die Kette mit Grund

Eine feste Zielversion gilt nur fuer Firewalls derselben Edition (ab 3.32.4). Firewalls der anderen Edition ueberspringt der Lauf mit dem Grund Zielversion passt nicht zur Edition. Fuer gemischte Jobs Neueste waehlen: Jede Firewall bekommt dann die neueste Version ihrer Edition.

Im Lauf-Detail steht je Firewall der aktuelle Schritt (Schritt 4: Sprung auf 25.1) und die Liste der erledigten Schritte. Bei HA-Paaren wechseln sich die Nodes je Hauptversion ab: erst der BACKUP (z. B. auf 24.1), dann der MASTER auf 24.1, dann der BACKUP auf 24.7 usw. Nie arbeiten beide gleichzeitig, und das Paar liegt hoechstens eine Hauptversion auseinander. Scheitert ein Node, bleibt der andere auf seinem Stand stehen.

Ist das Wartungsfenster vorbei, stoppt die Kette nach dem laufenden Schritt sauber (Lauf unvollstaendig, der naechste Lauf macht weiter). Ausnahme: Liegt ein Node eines Paars eine Hauptversion zurueck, zieht er noch nach - das Paar endet auf derselben Hauptversion. Neue Spruenge starten ohne Pause, dazwischen nimmt die Firewall keine anderen Update-Tasks an.

Als wiederkehrender Job: Ein Job Major Upgrade → Neueste (z. B. monatlich) haelt Firewalls immer auf dem neuesten Stand, auch ueber neue Hauptversionen hinweg. Ist nichts Neues da, spielt er nur die offenen Updates ein.

Kein Playbook dafuer: Playbook-Schritte legen Tasks direkt an - ohne HA-Ablauf, ohne Sperre und ohne Warten auf den Neustart. Major-Upgrades deshalb immer ueber einen Job oder den Knopf Major Upgrade im Reiter Updates (startet ebenfalls einen Lauf, Ziel Neueste vorbelegt).

Hinweise:

  • Vor dem Sprung auf 26.1 / 26.7 die Checks OPNsense Legacy-Firewall-Regeln und OPNsense Legacy-IPsec ansehen (OPNsense): Legacy-IPsec braucht danach das Plugin os-strongswan-legacy.
  • Der Agent prueft im Preflight, ob der Mirror genau die naechste Version anbietet (upgrade_major_version) und ob mindestens 2 GB frei sind.
  • Rechnen Sie mit 20-45 Minuten pro Sprung und Node (Download, Offline-Installation, zwei Reboots); 23.7 → 26.7 auf einem HA-Paar dauert also mehrere Stunden.

HA-Synchronisation prüfen (ab 3.47.0) ​

OPNsense kopiert die Konfiguration nicht von selbst auf den zweiten Node: Der Master schickt die gewählten Bereiche per XMLRPC an den Backup-Node, wenn du unter System › Hochverfügbarkeit › Status synchronisierst (oder ein Cron-Job das tut). Vergisst man das, läuft der Backup-Node nach einem Failover mit alten Regeln. Control prüft das jetzt selbst – ohne Task auf der Firewall, nur aus den gespeicherten Config-Versionen (Subtab Backups).

Was verglichen wird: genau die Bereiche, die OPNsense synchronisiert – nicht mehr und nicht weniger. Control liest im hasync-Block der config.xml des Masters, welche Dienste für die Synchronisation angehakt sind (syncitems, bei älteren Versionen die Einzel-Schalter synchronize…), und vergleicht die zugehörigen Bereiche der neuesten Config-Versionen beider Nodes. Die Zuordnung Dienst → Bereich stammt aus dem OPNsense-Quelltext (src/etc/rc.filter_synchronize und die *_xmlrpc_sync()-Funktionen in src/etc/inc/plugins.inc.d), zum Beispiel:

Dienst in OPNsenseVerglichener Bereich
Aliasealiases, OPNsense.Firewall.Alias
Firewall-Regelnfilter, OPNsense.Firewall.Filter.rules
NATnat und die MVC-NAT-Regeln (Outbound, 1:1, NPT)
Virtuelle IPsCARP-VIPs (virtualip, nur VIPs mit VHID)
Benutzer und Gruppensystem.user, system.group
Zertifikatecert, ca, crl
IPsec, WireGuard, OpenVPN, Unbound, Kea …der jeweilige Bereich

Was nicht zählt: Hostname, Interface-Adressen und alles andere, was OPNsense nicht synchronisiert; bei CARP-VIPs der advskew (OPNsense setzt ihn auf dem Backup selbst um 100 höher); Einträge mit nicht synchronisieren (nosync); Werte, die nur auf dem Backup stehen, in einfachen Bereichen, die OPNsense beim Sync nur überschreibt. Listen (Regeln, Aliase, Benutzer, VIPs …) ersetzt OPNsense dagegen ganz – ein Alias, der nur auf dem Backup existiert, ist also eine Abweichung. Bei Legacy-Regeln zählt die Reihenfolge.

Wer ist der Master? Der Node, auf dem ein Sync-Ziel (synchronizetoip) und mindestens ein Dienst eingetragen sind – nur er schickt seine Konfiguration. Sind beide Nodes so eingerichtet, entscheidet die aktuelle CARP-Rolle.

Ergebnis je Paar (im HA-Kasten im Reiter Updates, in der Liste als kleines ≠ an der HA-Pill):

StatusBedeutung
synchronalle geprüften Bereiche gleich
abweichendmindestens ein Bereich unterscheidet sich – mit Liste der Bereiche und Beispielen (nur Pfade wie …alias[Admins] abweichend, nie Werte)
unbekanntkeine Config-Version auf einem Node, Versionen älter als 26 Stunden, keine Synchronisation eingerichtet, Master nicht eindeutig, oder es werden nur Plugin-Bereiche synchronisiert, die Control nicht kennt

Plugin-Dienste (z. B. HAProxy, ACME) kennt Control nicht; sie stehen als nicht geprüft unter dem Ergebnis.

Wann geprüft wird: sobald einer der beiden Nodes eine neue Config-Version speichert, eine Stunde nach dem nächtlichen Backup und sonst alle 6 Stunden. Jetzt prüfen im HA-Kasten rechnet sofort aus den gespeicherten Versionen neu. In den ersten 24 Stunden einer Abweichung fordert Control alle 2 Stunden von beiden Nodes ein Backup an (Anlass HA-Prüfung; der Agent schickt nur den Hash, wenn sich nichts geändert hat) – so merkt Control eine nachgeholte Synchronisation innerhalb der Haltezeit. Danach zählt nur noch das nächtliche Backup.

Paar vergleichen öffnet den Vergleich beider Nodes (Master links) und braucht das Recht Config-Backups lesen.

Alarm: Weicht ein Paar länger als alert_ha_sync_hold_hours (Standard 6 Stunden) ab, meldet Control eine Warnung HA-Synchronisation (siehe Benachrichtigungen).

EndpunktZweck
GET /api/firewalls/<id>/ha-syncZustand des Paars (Status, Grund, Bereiche, Zeitpunkt)
POST /api/firewalls/<id>/ha-sync/checksofort neu prüfen (Admin/Ops)

Später möglich

Der Agent meldet heute keinen Fehler der XMLRPC-Synchronisation selbst (z. B. falsches Passwort am Sync-Ziel). Das ließe sich mit einer Agent-Erweiterung ergänzen (Systemlog nach An error occurred while attempting XMLRPC sync durchsuchen); bis dahin zeigt sich so ein Fehler als abweichend.

DATAZONE Control Documentation