Skip to main content
RunBook Academy

← All break/fix scenarios in OPNsense

advancedServices~30 min

Break/Fix: Service Fails To Start After Major Upgrade

Reported symptoms

  • ●A service that worked before the upgrade fails to start
  • ●Service status in the GUI is "stopped" with no clear reason
  • ●system log shows a config syntax error or missing dependency

Evidence

  • · system log: "config.xml validation failed for service unbound"
  • · /var/log/<service>.log shows a Python or PHP error referencing a deprecated option
  • · pkg info shows the upgrade replaced the service binary and the old config is incompatible
Diagnosis and resolutionclick to reveal

Root cause

Major OPNsense upgrades can change config schema or service configuration format. The old config is no longer parsed cleanly and the service refuses to start.

Remediation

1. Inspect /var/log/<service>.log and the system log for the exact error. 2. Identify the deprecated or renamed option in the new schema. 3. Apply the migration via the GUI (the migration wizard usually prompts), or edit /conf/config.xml by hand to align with the new schema. 4. Restart the service and verify status.

Verification

Service starts cleanly; GUI status is "running"; functional test (DNS resolution, tunnel establishment) succeeds.

Prevention

Before any major upgrade, read the release notes for breaking changes. Test in a lab identical to production. Always have a known-good config.xml backup and a console/SSH session ready. If a service is mission-critical, roll forward on the new version within a maintenance window, do not let it linger.

Scenario

You are operating an OPNsense edge and just ran a major version upgrade. The following symptoms appear:

  • A service that worked before the upgrade fails to start
  • Service status in the GUI is “stopped” with no clear reason
  • system log shows a config syntax error or missing dependency

Available evidence:

  • system log: “config.xml validation failed for service unbound”
  • /var/log/<service>.log shows a Python or PHP error referencing a deprecated option
  • pkg info shows the upgrade replaced the service binary and the old config is incompatible

Your task

Determine the cause, recover, document, and validate.

Investigation

The investigation follows the discipline taught in Part XLI:

  1. Form hypothesis, find evidence, test, validate.
  2. Use the available evidence above to bound the search.
  3. Reach one of the likely root causes.

Recovery procedure

(Do not reveal until you have reasoned through the problem.)

  1. Identify the failing component.
  2. Apply the remediation pathway.
  3. Validate with the verification step.
  4. Document the incident.

Remediation

  1. Inspect /var/log/<service>.log and the system log for the exact error. 2. Identify the deprecated or renamed option in the new schema. 3. Apply the migration via the GUI (the migration wizard usually prompts), or edit /conf/config.xml by hand to align with the new schema. 4. Restart the service and verify status.

Verification

Service starts cleanly; GUI status is “running”; functional test (DNS resolution, tunnel establishment) succeeds.

Rollback

Boot from the previous firmware via the boot menu and restore the pre-upgrade config.xml.

Prevention

Before any major upgrade, read the release notes for breaking changes. Test in a lab identical to production. Always have a known-good config.xml backup and a console/SSH session ready. If a service is mission-critical, roll forward on the new version within a maintenance window, do not let it linger.