I assume readers of the blog post are already familiar with FreeBSD and its bhyve hypervisor. Some might not be familiar with the qemu guest agent. Briefly, it's a process running within the guest which allows communicating between the hypervisor and the guest. It allows both querying information, such as disks, filesystems, network interfaces and a lot more. It also allows to manage guests, for example triggering a graceful reboot or shutdown, setting time, updating SSH keys and so forth.
Here's an overview on how to use the qemu guest agent on a FreeBSD guest running on a FreeBSD host with bhyve.
Host (bhyve) configuration
On the bhyve side, it needs to be started like that:
bhyve -c 4 -m 4096 -S -A -I -u -H -P \
-s 0:0,hostbridge -l bootrom,/usr/local/share/uefi-firmware/BHYVE_UEFI.fd \
-s 1:0,lpc \
-s 2:0,virtio-console,org.qemu.guest_agent.0=/var/run/bhyve/bhyve.agent \
-s 3:0,virtio-net,tap1 \
-s 4:0,virtio-blk,/var/img/disk-freebsd.img \
-l com1,stdio \
freebsd
Here, the most important part for us is -s 2:0,virtio-console,org.qemu.guest_agent.0=/var/run/bhyve/bhyve.agent. This connects the org.qemu.guest_agent.0 to the /var/run/bhyve/bhyve.agent UNIX socket. It is not needed to create this socket manually, but it needs to be removed manually when the VM is destroyed.
Guest configuration
Install the qemu-guest-agent package:
# pkg install qemu-guest-agent
Enable it to start automatically on boot:
# sysrc qemu_guest_agent_enable="YES"
service qemu-guest-agent start
Testing
To test if the agent is actually working, run the following on the host:
echo '{"execute":"guest-get-host-name"}' | sudo nc -U /var/run/bhyve/bhyve.agentThat queries the guest's hostname. Now you should see a response similar to:
{"return": {"host-name": "freebsd"}}And that's it, it's just that simple! If you want to use the guest agent manually or build something on top of it, please refer to the QEMU Guest Agent Protocol Reference.
Thanks for reading!
