SimpleVirt Guest Tools

SimpleVirt Guest Tools is the first-party guest integration suite for SimpleVirt. It gives SimpleVirt reliable guest awareness and controlled guest operations without depending on SSH, WinRM, or the guest's own network — everything travels over a dedicated virtio-serial channel. It is SimpleVirt-native, built on KVM/QEMU/libvirt; it copies no third-party tools, protocols, or branding, and it coexists with the qemu-guest-agent rather than replacing it.

SimpleVirt-Command → simplevirtd → QEMU / virtio-serial (org.simplevirt.guest.0) → simplevirt-guestd → guest OS

Components

Transport & security

• Channel: org.simplevirt.guest.0, a virtio-serial channel added to every new VM alongside org.qemu.guest_agent.0. The host connects to the bind-mode unix socket libvirt creates (path read from the live domain XML). simplevirtd reaches it via the libvirt-qemu group — never as root.
• No guest network surface: simplevirt-guestd listens on no TCP port; its only interface is the virtio channel, so it keeps working with no guest IP, broken DNS, disabled SSH, or a hostile guest firewall.
• Framing: length-prefixed frames, hard 1 MiB bound checked before the body is read; malformed/oversized input tears the channel down (reconnect) rather than resyncing.
• Typed operations only. There is deliberately no generic "run command" op. Any future arbitrary execution must be a separate, RBAC'd, audited surface.
• Version & capability negotiation: a newer host still talks to an older daemon; the host enables an action only if the daemon advertises the capability.

v1 operations

guest-info (OS, hostname, kernel, arch, uptime, boot id) · network-info (interfaces, MACs, IPv4/IPv6, default route) · filesystem-info (mounted real filesystems, capacity) · shutdown / reboot (OS-native graceful — never a silent escalation to force) · freeze / thaw (filesystem quiesce with a mandatory deadman) · time-sync (conservative one-shot correction) · disk-rescan (notice an expanded virtual disk; never touches partitions/filesystems). Plus a periodic heartbeat so SimpleVirt can tell a responsive guest OS from a merely-running QEMU process.

Freeze safety (data-loss prevention)

A freeze is bracketed by a lease and can never be left hanging: the daemon auto-thaws when the per-lease deadman fires, and immediately when the channel drops (controller/host gone). This is the foundation for future quiesced snapshots/backups.

Getting the agent into VMs (deployment models)

Every major platform (VMware, Nutanix, Proxmox, and all public clouds) makes the agent already being present in the image before first boot the primary production path — VMs are cloned from a golden template/image that already carries the agent, so nothing is installed at runtime. Runtime install (cloud-init on first boot, or mounting an ISO and running an installer) is universally the secondary/one-off path. SimpleVirt follows the same order. Prefer them top to bottom:

Build the medium once: make guest-tools → deploy/guest-tools/out/ (.deb, .rpm if nfpm present, simplevirt-guest-tools.iso). The ISO is also baked into every host appliance at /var/lib/simplevirt/isos/, so it always resolves fleet-wide with no internet.

1. Pre-baked template (preferred, air-gapped) — agent present at first boot

Bake simplevirt-guestd into a base Linux cloud image with the offline template injector shipped alongside SimpleVirt Guest Tools, then import the result, mark a VM built from it as a template, and deploy VMs from that template. Each clone boots with the agent already installed, enabled, and a fresh identity (the injector blanks /etc/machine-id, resets cloud-init, and clears SSH host keys so clones never collide). No runtime install; nothing fetched from the network. This is the industry's dominant model and the recommended default.

2. Create-time cloud-init (raw cloud images) — offline first-boot install

When you create a VM from a raw Linux cloud image (not a pre-baked template), the New-VM wizard's Guest-customization step offers Install SimpleVirt Guest Tools on first boot (default on). It attaches the baked-in tools ISO and injects a cloud-init runcmd that mounts it by label (SIMPLEVIRT_GUEST_TOOLS) and runs install.sh offline — unlike a generic cloud-init packages: pull, this needs no mirror, so it works air-gapped. It also best-effort enables qemu-guest-agent. It is idempotent (a clone that already has the agent skips), never fails the create, and applies only to Linux cloud images that run cloud-init.

3. Mount-ISO one-off (existing / legacy VMs)

For a VM that already exists and has no agent, a VM's Guest card offers Mount SimpleVirt Guest Tools ISO (reuses the CD/DVD tray). Inside the guest, as root:

mount /dev/sr0 /mnt && /mnt/Linux/install.sh          # Linux
D:\Windows\SimpleVirtGuestTools-x64.msi   (msiexec /qn)    # Windows (silent)

This matches how VMware/Nutanix/Proxmox handle first install too. An air-gapped, agent-less VM has no bulk remote-push path (with no agent there is no channel to trigger and no assumed guest network) — the answer for those is a one-off mount or a template redeploy, not a mass push.

After the daemon connects (any path), the Guest card shows Running with the guest's OS, hostname, uptime, and IP addresses (labelled as an inside-the-guest source, distinct from the host's DHCP-lease observation), and the Shut down / Restart (guest tools) actions become effective.

Windows

Windows first-install follows the same industry reality as the competitors: there is no reliable CD autorun on modern Windows, so bake the silent MSI into a golden template (model 1) or mount the ISO and run it once (model 3). The create-time cloud-init path is Linux-only (Windows uses cloudbase-init/MSI, a separate flow).

Roadmap: host-driven upgrade-at-power-on

The models above cover getting the agent installed. Keeping an already-installed agent current — the equivalent of VMware's opt-in "check and upgrade tools at power-on" — is a planned day-2 addition: simplevirtd knows each guest's reported version and the on-host manifest.json version, so a per-VM policy can, on power-on, mount the on-host ISO and run a silent upgrade (control channel triggers; the on-host ISO carries the bits — never the payload over the serial channel). It upgrades only; it never bootstraps a bare guest, and it is fail-open so a bad upgrade cannot block power-on.

Status

Linux v1 is implemented and tested end-to-end: protocol, daemon, simplevirtd integration, UI, HA manifest survival, and packaging. All three deployment models above are available: pre-baked template (offline injector, make guest-image), create-time cloud-init (default-on for Linux cloud images), and mount-ISO one-off. Windows (simplevirt-guestd as a Windows Service + SimpleVirtGuestTools-x64.msi) is software-complete; template/MSI is the supported path. Host-driven upgrade-at-power-on is the next milestone.