Out of the box, Proxmox VE treats an OPNsense VM as a black box: it can start it and force-stop it, but asking it to shut down politely, reading its IP addresses in the Proxmox summary, and taking clean guest-aware snapshots all need help from inside the VM. That help is the QEMU Guest Agent. In OPNsense it is delivered as the os-qemu-guest-agent plugin, and this guide shows you how to enable it on the Proxmox side, install it in OPNsense, and verify with your own eyes that it is actually working. One fact up front, because it shapes how you should think about the plugin: it is a Tier 3 community plugin, maintained by the community rather than shipped as part of the OPNsense base system.
What the guest agent actually does
The QEMU Guest Agent is a small service that runs inside a virtual machine and answers requests from the hypervisor over a virtual serial channel. For an OPNsense VM on Proxmox, the practical benefits are:
- Clean shutdowns and reboots: when you click Shutdown in Proxmox, or the host itself shuts down (for example on a UPS event), the request is delivered to OPNsense as an orderly system shutdown instead of a power cut. Firewalls dislike power cuts: an orderly shutdown closes connections, writes out state cleanly and avoids file system repairs on the next boot.
- IP address reporting: Proxmox can display the VM's interface addresses in its summary view, which is genuinely useful for a firewall whose LAN address you may have changed from the default.
- Coordinated snapshots: with the agent present, Proxmox can ask the guest to quiesce its file systems around a snapshot, which makes backups of a running VM more consistent.
- Proof of life: the hypervisor can ping the agent, which gives Proxmox a reliable answer to "is the guest actually up?" beyond "the process is running".
What it does not do is equally worth knowing. The agent is not a management interface, it does not replace the OPNsense web GUI or console, and it does not improve network performance. It is purely a cooperation channel between guest and host.
The honest part: it is a Tier 3 community plugin
OPNsense plugins come in tiers. The base system and core plugins are maintained by the OPNsense team; Tier 3 plugins are community-maintained packages that the project makes available through the same plugin system but does not develop itself. os-qemu-guest-agent is one of those: the official virtual machines documentation tells you to install it from the plugin list after ticking "Show (Tier 3) community plugins", which is the system being transparent about its status.
What does that mean for you in practice? The plugin is widely used and the underlying QEMU guest agent is a mature, standard component across KVM platforms. But updates arrive on a community schedule, support is a community affair, and if a future OPNsense update ever conflicts with it, the fix may lag behind core fixes. For a component this small and this standard, most Proxmox users accept that trade happily. Just make the decision with your eyes open, and re-check the plugin's status after major OPNsense upgrades.
How the agent talks to the host
Understanding the plumbing makes the troubleshooting table at the end of this guide much less mysterious. The agent does not communicate over your network. When the Qemu Agent option is enabled, Proxmox adds a virtual serial device to the VM, backed by a socket on the host. The guest agent inside OPNsense listens on that serial channel; Proxmox sends small commands down it ("report your network interfaces", "begin shutdown", "freeze file systems for a snapshot") and reads the replies. Three consequences follow. First, the channel works even if the VM's networking is completely broken, which is why the agent can still shut a misconfigured firewall down cleanly. Second, the channel exists only if both ends are set up: the Proxmox option creates the device, and the plugin provides the listener, so missing either one looks exactly like the agent "not working". Third, nothing about the agent is reachable from the LAN or WAN, so installing it does not add an exposed service to your firewall's network surface.
What it means for backups and host shutdowns
Two Proxmox routines change behaviour once the agent answers. The first is backup. When Proxmox takes a snapshot-mode backup of a running VM, it can ask the guest agent to freeze the file systems briefly while the snapshot is taken and thaw them immediately afterwards. The result is a backup that looks as if the disk had been at rest, rather than a crash-consistent copy caught mid-write. For a firewall whose configuration and logs are always in motion, that difference is the difference between a restore you trust and a restore you hope for.
The second is the host itself shutting down. When Proxmox stops, because you asked it to, because a UPS told it to, or because an update needs a reboot, it works through its VMs and asks each one to shut down. With the agent, OPNsense receives that as a proper shutdown request and closes down in an orderly fashion: connections end, the configuration is already saved, file systems unmount cleanly. Without it, the host waits for a timeout and then stops the VM the hard way, which is the virtual equivalent of pulling the plug. A single hard stop rarely destroys a modern file system, but a firewall is the one VM whose abrupt disappearance the whole network notices, and repeated hard stops are how small corruptions accumulate. The agent is cheap insurance against both.
Security and maintenance notes
Because the agent accepts instructions from the hypervisor, it is worth a moment's thought about trust. The channel is local to the host: only someone who controls Proxmox can send commands down it, and anyone who controls Proxmox already controls the VM completely, including its disks and console. Installing the agent therefore does not widen your trust boundary in any meaningful way; it formalises control the host already has. Inside the guest, the agent runs with system privileges, which is normal for its job and another reason to keep it updated through the normal plugin and firmware process.
Maintenance is light. The plugin updates through System → Firmware like everything else; check for an available update whenever you update OPNsense itself, and re-run the three verification tests after any major version upgrade, since major upgrades are when community plugin behaviour is most likely to change. If you ever migrate the VM to a different KVM platform, the same plugin serves you there too, because the agent is a standard QEMU component rather than something Proxmox-specific.
Before you start
- Your OPNsense VM is installed and reachable in the web GUI (see How to Install OPNsense on Proxmox VE if it is not).
- You have console or GUI access to Proxmox to change one VM option and to watch the VM console during a test shutdown.
- You have taken a configuration backup (System → Configuration → Backups) so you can roll back your plugin experiments easily.
- The VM can be rebooted once during this task without upsetting anyone using the network.
Step 1: Enable the agent option in Proxmox
The guest agent needs a channel to talk on, and Proxmox only creates that channel when you ask for it. Shut down the VM (or plan to reboot it), open the VM's Options in the Proxmox web interface, find the Qemu Agent setting and set it to enabled. While you are there, this is also a good moment to confirm the VM's shutdown-related behaviour is sane: Proxmox sends shutdown requests with a timeout, and if the guest does not respond in time the host may eventually force the issue, which is exactly what the agent helps you avoid.
Start the VM again so the channel exists before you install the software that uses it. Installing the plugin first and enabling the option later also works, but doing the hypervisor side first means your verification at the end tests the whole chain in one go.
Step 2: Install the plugin in OPNsense
Log in to the OPNsense web GUI and go to System → Firmware → Plugins. The plugin list hides community plugins by default, so tick the Show (Tier 3) community plugins option first; without that tick, the package simply will not appear and you will conclude it does not exist. Find os-qemu-guest-agent in the list and click the install button (the + icon) next to it. OPNsense downloads and installs the package and its dependencies; watch the output until it reports completion. The plugin page afterwards shows the package as installed, and its description identifies it as the QEMU Guest Agent for use with Proxmox VE and other QEMU/KVM hosts.
If the plugin does not appear even with community plugins shown, run a firmware update check first (System → Firmware → Status, then check for updates) so your plugin list is current, and confirm the VM has working internet access for the package download.
Step 3: Start the agent and make it survive reboots
Installing the package places the agent on the system; depending on the state of your install it may start immediately or need a nudge. The reliable approach is to reboot the VM once after installation. A reboot proves three things at once: the service starts automatically as part of the normal boot, the Proxmox channel (enabled in Step 1) is present when it starts, and your firewall still comes up cleanly with the plugin installed. Watch the console during the boot if you can; the agent's start is uneventful when things are healthy, which is what you want.
How to confirm it worked
Do not trust the installed checkmark; test the behaviours the agent exists for.
- IP reporting: in the Proxmox summary for the VM, the guest's IP addresses are displayed (Proxmox pulls them from the agent). If the summary shows your LAN address (192.168.1.1 by default, or the address you changed it to), the channel works.
- Clean shutdown: open the VM console in Proxmox so you can watch, then use Proxmox's Shutdown action on the VM. On the console you should see OPNsense run through an orderly shutdown sequence and power off, rather than the display simply vanishing. Start the VM again afterwards.
- Agent responds: Proxmox no longer reports the guest agent as not running for this VM, and agent-dependent actions (such as guest-aware snapshot options) stop warning that the agent is missing.
If all three pass, you are done: host shutdowns, UPS events and snapshot backups will now treat your firewall politely.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Plugin not in the list | Community plugins are hidden | Tick "Show (Tier 3) community plugins" on the Plugins page, then search again. |
| Plugin installed, but Proxmox says the agent is not running | The Qemu Agent option is disabled in the VM's Proxmox options, or the VM has not been restarted since enabling it | Enable the option, then fully shut down and start the VM so the channel is created. |
| Shutdown still cuts power | The agent service did not start, or the shutdown timed out | Reboot the VM and retest while watching the console; check the plugin is still listed as installed after any OPNsense update. |
| No IP addresses in the Proxmox summary | The agent is running but Proxmox has not refreshed, or the channel is one-way | Wait a minute and reload the summary; if it persists, restart the VM and verify the shutdown test, which exercises the same channel. |
| Agent vanished after an OPNsense upgrade | Community plugin lagging a core change | Check the Plugins page for an available update or reinstall the plugin; this is the known Tier 3 trade-off. |
Worth it?
For a firewall that other machines depend on, yes. The agent turns the two scariest hypervisor moments, host shutdowns and backups of a running system, into orderly events, and it costs you one small community plugin. Pair it with sensible VM sizing and the networking layout covered in this category, and your virtual firewall behaves like a well-kept appliance instead of a tolerated experiment. The official pointer for this plugin lives in the OPNsense virtual machines documentation.