QEMU Guest Agent

The QEMU Guest Agent when FreeCORE runs as a guest under QEMU/KVM or Proxmox VE.

FreeCORE 15.1 ships the QEMU Guest Agent for systems that run as a virtual machine under QEMU/KVM, including Proxmox VE. It lets the hypervisor read the guest's host name, operating system and interface addresses, and request an orderly shutdown, without a network path to the guest.

It does not add a hypervisor to FreeCORE; the bhyve virtual machines FreeCORE hosts are unaffected. The agent is inert on bare metal and under hypervisors that do not offer a guest-agent channel.

The Guest-Agent Channel

The hypervisor must present the guest-agent channel to the virtual machine. FreeCORE cannot create it.

Proxmox VE: enable QEMU Guest Agent in the VM's Options, then stop and start the VM. A reboot from inside the guest does not add the device.
libvirt / plain QEMU: attach a virtio-serial channel whose target name is org.qemu.guest_agent.0.

When the channel is present, /dev/vtcon/org.qemu.guest_agent.0 exists in the guest.

Turn the Agent On or Off

The agent is the QEMU Guest Agent service under Services. On the first boot where the hypervisor offers the channel, FreeCORE turns the service on, sets it to start automatically and starts it. It does this once: from then on, the service's Running and Start Automatically settings are yours, and FreeCORE does not change them again. A system without the channel is left as it is; if the channel is added later, the next boot turns the agent on.

Use Running to start or stop the agent and Start Automatically to choose whether it starts at boot. Starting it without the channel is refused with a message that names the missing channel. The service has no settings to configure. service qemu-guest-agent status reports the running agent, and the hypervisor shows the guest-agent channel as connected.

Do not add a qemu_guest_agent_enable tunable: the service owns that setting, and a tunable would override the service's choice. An existing qemu_guest_agent_enable tunable is turned into the service setting when the system is updated.

What the Agent Is Allowed to Do

FreeCORE ships a restricted policy. Only these commands are enabled:

Command	Purpose
`guest-ping`	Liveness check.
`guest-info`	Agent version and the enabled command set.
`guest-sync`, `guest-sync-delimited`	Protocol resynchronization.
`guest-get-host-name`	The guest's host name.
`guest-get-osinfo`	Operating system and kernel identification.
`guest-network-get-interfaces`	Interface names, MAC addresses and IP addresses.
`guest-shutdown`	Orderly power-off or reboot requested by the hypervisor.
`guest-fsfreeze-status`, `guest-fsfreeze-freeze`, `guest-fsfreeze-freeze-list`, `guest-fsfreeze-thaw`	Filesystem freeze requests from hypervisor backups. On FreeCORE they succeed without suspending anything; see below.

Every other command the FreeBSD agent implements is refused, and the refusal is enforced by the agent rather than merely advertised:

guest-exec                    -> Command guest-exec has been disabled: the command is not allowed
guest-file-open               -> ... has been disabled: the command is not allowed
guest-set-time                -> ... has been disabled: the command is not allowed
guest-ssh-add-authorized-keys -> ... has been disabled: the command is not allowed

Command execution, file access, clock changes and SSH key injection from the hypervisor are therefore not available, by design. Do not widen the policy on a production appliance.

Shutdown Behavior

guest-shutdown in its default powerdown mode runs shutdown -p +0, which goes through the normal shutdown scripts and stops services cleanly. This is the mode Proxmox uses for Shutdown.

The RPC itself usually returns Guest agent disappeared while executing command. That is the expected result: the agent stops with the rest of the system before it can reply. The guest's power state, not the RPC's return value, is the outcome to check.

The agent's reboot and halt modes call /sbin/reboot and /sbin/halt directly and skip the shutdown scripts. Prefer powerdown.

Backups Are Crash-Consistent

The FreeBSD guest agent freezes UFS file systems only. FreeCORE's storage is ZFS, so a freeze request succeeds without suspending anything: a hypervisor backup that asks the agent to freeze the guest completes without freeze errors, but what it captures is crash-consistent. That is equivalent to pulling power, which OpenZFS is designed to survive, but it is not a quiesced, application-consistent snapshot.

For consistent backups of data, use FreeCORE's own periodic snapshot and replication tasks rather than relying on the hypervisor.

guest-fstrim is not implemented by the FreeBSD agent at all, so guest-initiated TRIM through the agent is unavailable. It is absent from the command list rather than disabled — a client that only checks the disabled set may report it as available.

Services