QEMU guest agent

MacVisor's own guest tools, the MacVisor Agent, give a VM the most: shells, clipboard, file transfer, port forwarding, the guest's memory, and more. Where you can't install them, a QEMU guest agent (qemu-ga) in the guest gives MacVisor a little of that. Use it for:

• Appliances that ship it, such as Home Assistant OS, or that offer it as a package or plugin.
• Linux systems MacVisor's agent doesn't run on, such as those with neither systemd nor OpenRC, or a system you'd rather not add MacVisor's agent to.
• FreeBSD-based appliances, such as pfSense-based or OPNsense-based ones, where MacVisor has no account to install its agent with.

MacVisor ships no QEMU guest agent. The guest installs it from its own packages, and MacVisor talks to it over a port of the VM, not the network.

What it gives

While MacVisor's agent isn't connected and a QEMU guest agent answers, MacVisor uses it for:

MacVisor asks it every 10 seconds for the guest's addresses, and every minute for its details. An agent you install later is found by itself, within 30 seconds.

What it doesn't give

These still need MacVisor's agent:

• mvz shell and mvz exec through the agent, without the network. With the QEMU guest agent only, they go over the network, to an account that has your SSH key. In an appliance they're refused: it has no MacVisor account.
• mvz wait in a VM made from a cloud image, which waits for MacVisor's agent and cloud-init. In a VM installed from an ISO or imported, a QEMU guest agent that answers counts as ready, and an appliance is ready once it runs. mvz ip <vm> --wait waits for an address either way.
• Clipboard sharing and file transfer.
• Port forwarding, set by hand or automatic.
• The guest's memory use and pressure on the Memory card.
• Flushing the guest's writes before a snapshot, and setting its clock after a pause or a resume.
• The Docker socket and mvz trim.

MacVisor never runs commands or reads files through a QEMU guest agent. It sends only guest-sync-delimited, guest-info, guest-ping, guest-network-get-interfaces, guest-get-osinfo, guest-get-host-name and guest-shutdown.

The Guest Tools card

Limited shows whether Enable Guest Tools is on or off, and in appliances and other VMs alike. The VM window's guest tools item reads Limited too, and its tooltip names the version.

From the CLI, mvz show <vm> of a running VM says Guest tools: limited (MacVisor's agent isn't connected; the QEMU guest agent answers), followed by a QEMU Guest Agent row with its version and, while it's limited, Guest OS, Hostname and Kernel rows. With MacVisor's agent connected, only the version row stays.

mvz show homeassistant
mvz show homeassistant --json

mvz show --json has guestToolsStatus (running, outdated, updating, updateNeeded, untrusted, limited, notDetected, notInstalled, unknown or disabled) and a qemuGuestAgent object with version, prettyName, osName, osVersion, hostname and kernelRelease.

Set it up in a Linux VM

1. Give the VM the port

The agent talks to MacVisor over a named port, org.qemu.guest_agent.0, which shows in the guest as /dev/virtio-ports/org.qemu.guest_agent.0.

To turn it on, shut the VM down, then:

• In the app: in VM Settings → Guest Tools → Agent Channel, turn on QEMU Guest Agent Port. It saves by itself.
• From the CLI: mvz set <vm> --qemu-ga on.

It applies at the next start from shut down. A suspended VM resumes with the devices it was saved with, so shut it down rather than suspending it. The port is for Linux VMs only: --qemu-ga on another VM is refused, and a FreeBSD VM has a serial port of its own.

2. Install the agent in the guest

Install your distribution's package. On most systemd distributions it starts by itself once the port is there.

sudo apt install qemu-guest-agent          # Debian, Ubuntu, Kali
sudo dnf install qemu-guest-agent          # Fedora, Rocky Linux, AlmaLinux, Oracle Linux
sudo zypper install qemu-guest-agent       # openSUSE
sudo pacman -S qemu-guest-agent            # Arch Linux

If it isn't running, start it:

sudo systemctl start qemu-guest-agent
systemctl status qemu-guest-agent

On Alpine Linux, with OpenRC:

sudo apk add qemu-guest-agent
sudo rc-update add qemu-guest-agent
sudo rc-service qemu-guest-agent start

An appliance installs it its own way, from its add-ons, plugins or package manager, if it offers it.

3. Check it

Within a few seconds of the agent starting, the Overview's Guest Tools card shows QEMU Guest Agent with its version. If it doesn't:

• ls /dev/virtio-ports/ in the guest must list org.qemu.guest_agent.0. If it's missing, the port is off, or the VM hasn't been started from shut down since you turned it on.
• Some distributions limit which commands their agent answers, such as Fedora and the RHEL family in /etc/sysconfig/qemu-ga. Without guest-network-get-interfaces, guest-get-osinfo or guest-get-host-name, the card shows less. Without guest-shutdown, MacVisor doesn't shut the guest down through it.

Set it up in FreeBSD

Every FreeBSD VM has a serial port for a QEMU guest agent, /dev/ttyV1.0. There is no setting to turn on. A FreeBSD VM made before MacVisor 27.2.1 gets the port once it has been shut down since the update. In the guest, run:

sudo pkg install -y qemu-guest-agent
sudo sysrc qemu_guest_agent_enable=YES qemu_guest_agent_flags="-d -m isa-serial -p /dev/ttyV1.0"
sudo service qemu-guest-agent start

In a FreeBSD-based appliance, install its QEMU guest agent package or plugin, if it has one, and point it at /dev/ttyV1.0 with -m isa-serial -p /dev/ttyV1.0. See FreeBSD guests.

Shut down

MacVisor asks the QEMU guest agent to shut the guest down only once it has answered in this run.

• Linux guests get the virtual power button first, as always. If a guest hasn't started shutting down 15 seconds later, nothing in it took the button, and MacVisor's agent can't be asked, MacVisor asks the QEMU guest agent, once. A Restart shuts the guest down and starts the VM again.
• FreeBSD guests go through MacVisor's agent first, then the QEMU guest agent, then SSH, then the power button. A Restart shuts FreeBSD down the same way and starts the VM again.

So a Linux appliance that ignores the power button, which used to need Power Off, shuts down cleanly once it runs a QEMU guest agent. See Run and control VMs.

MacVisor's agent and qemu-ga together

Both can run in one guest. Leave a QEMU guest agent installed when you add MacVisor's agent: MacVisor uses its own agent while it's connected, and falls back to the QEMU guest agent for addresses and shutdown when its agent stops. Many VMs imported from UTM already run one, so they show Limited until you install MacVisor's agent.