Hello everyone, I am hoping for some guidance after a concerning incident with my OPNsense firewall. I have been running OPNsense 23.7 on a dedicated appliance for several months, primarily to manage VLANs for our manufacturing floor network segments and to handle site-to-site VPNs for our warehouse. I rely heavily on the web interface for daily monitoring and configuration adjustments.
My practice is to wait for the point releases and read through the community feedback before applying any updates. Yesterday, after seeing positive reports on the 23.7.11 patch, I enabled the auto-update function with the intention of letting it run overnight. This morning, I found that the update process had failed partway through. The system itself seems to be running—basic network connectivity and my existing firewall rules are still passing traffic—but the web GUI is completely inaccessible. I can reach the login page, but after entering credentials, I am presented with a blank, white screen. SSH access is still functional, which is the only reason I am not completely locked out.
I have logged in via SSH and attempted to gather some information. The output of `opnsense-version` shows a mix of versions, with some components still at 23.7.10 and others reporting 23.7.11, which confirms the partial update. I have checked the `/usr/local/opnsense/log/` directory and found several PHP-related errors in the system log, mentioning missing classes and failed includes. This aligns with the GUI failure. I have not attempted any further corrective actions, as my experience with FreeBSD internals is limited and I am wary of making the situation worse.
My primary goal is to restore the GUI without a full factory reset, if possible, as I have numerous custom firewall rules, VLAN assignments, and Unbound DNS overrides that are not fully documented elsewhere. I understand that a backup config restore might be necessary, but I am uncertain of the proper sequence. Should I first attempt a manual reinstallation of the `opnsense` package via `pkg`? Or is the recommended path to boot from the installation media and use the recovery option? I am looking for a step-by-step recovery process that prioritizes the preservation of the current configuration state. Any insight into what might have caused the auto-update to fail in this manner would also be greatly appreciated, as I need to assess whether I can safely use that feature in the future or if I must stick to manual updates. Thank you in advance for your expertise.
That's a stressful situation, and you've done the right thing by checking SSH access first. Seeing a mixed output from `opnsense-version` after a failed auto-update is the key clue here; it usually means the package set is in an inconsistent state.
Since the core traffic forwarding is working, the immediate goal is to repair the web GUI packages without disrupting your network. From the console, try running `opnsense-update -vk` to force a verification and reinstall of all packages. If that doesn't resolve it, you might need to target the GUI components specifically, but let's start with the full package check.
Have you checked the system logs via SSH for any specific error messages related to the update or the web server? That could point us to which component is actually broken.
Keep it constructive.
Good advice on starting with the package verification. I'd add that if the `-vk` run seems to hang or errors out, it's often because the local package cache is also corrupted from the failed update. In that case, you can try clearing it first with `pkg clean -ay` and then running the update again.
And absolutely seconding the log check. The specific error often lives in `/var/log/pkg.log` or the general `/var/log/messages` around the time of the failure. That'll tell you if it's a webconfigurator package issue or something deeper like a broken PHP dependency, which would need a different fix.