[Feature]: Native QEMU Guest Agent support via GUEST_AGENT environment variable

[cedric-marcoux]

Is your proposal related to a problem?

The virtio-serial channel is not configured by default. Even with the agent installed in Windows, it cannot communicate with the host. Related to #664

Cannot stop windows properly when rebooting

Describe the solution you'd like.

Add native support for QEMU Guest Agent through a simple GUEST_AGENT=Y environment variable

Describe alternatives you've considered.

ACP shutdown but host is not aware

Additional context

Summary

Add native support for QEMU Guest Agent through a simple GUEST_AGENT=Y environment variable.

Problem

1. The virtio-serial channel is not configured by default in QEMU
2. Even with the agent installed in Windows, it cannot communicate with the host
3. Related to [Feature]: Adding QEMU Guest Agent to Unattend XML #664 which didn't address the QEMU-side configuration

Tested Solution

Works perfectly with:

ARGUMENTS: "-chardev socket,path=/storage/qga.sock,server=on,wait=off,id=qga0 -device virtio-serial -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0"

Important: The socket must be in /storage (not /tmp) so it's accessible from the host through the mounted volume.

Results:
- ✅ Socket accessible at ./data/qga.sock from host
- ✅ guest-ping responds: {"return": {}}
- ✅ guest-shutdown triggers proper Windows shutdown

Usage from host

# Graceful shutdown
echo '{"execute":"guest-shutdown"}' | nc -U ./storage/qga.sock

Suggested Implementation

environment:
  GUEST_AGENT: "Y"  # Creates /storage/qga.sock

Benefits

- Graceful shutdown before container stops
- Systemd integration: send shutdown command before host reboot
- Filesystem freeze for consistent snapshots
- Guest monitoring (OS info, users, network)

Tested with Windows 10 LTSC 2021

[kroese]

Gracefully shutdown is already implemented? When the container stops it sends the ACPI signal via the QEMU monitor serial port. See https://github.com/dockur/windows/blob/master/src/power.sh for more details.

[cedric-marcoux]

Gracefully shutdown is already implemented? When the container stops it sends the ACPI signal via the QEMU monitor serial port. See https://github.com/dockur/windows/blob/master/src/power.sh for more details.

You're right, I wasn't aware of the ACPI shutdown via system_powerdown - thanks for pointing that out!

However, the Guest Agent provides additional capabilities beyond shutdown:

• guest-fsfreeze-freeze/thaw for consistent snapshots
• guest-get-osinfo, guest-get-users for monitoring
• guest-exec for running commands inside Windows

Would you consider adding optional Guest Agent support for these use cases? The workaround via ARGUMENTS works, but native support would be cleaner.

If not needed, feel free to close this issue. Thanks for the great project!

[kroese]

You can already execute those commands (snapshots/os-info/etc) if you connect to the QEMU monitor port (7100).

The only thing your ARGUMENTS does is to use a file-based socket (./data/qga.sock) instead of the already available tcp port 7100. But I think it makes more sense to stick to that port, because it allows you to use the docker compose syntax to perform port mapping to another port if needed. And all the other connections (like VNC) are also port-based and not file-based.

[cedric-marcoux]

You can already execute those commands (snapshots/os-info/etc) if you connect to the QEMU monitor port (7100).

The only thing your ARGUMENTS does is to use a file-based socket (./data/qga.sock) instead of the already available tcp port 7100. But I think it makes more sense to stick to that port, because it allows you to use the docker compose syntax to perform port mapping to another port if needed. And all the other connections (like VNC) are also port-based and not file-based.

I think there might be a confusion here. Port 7100 is the QEMU Monitor (QMP), not the Guest Agent (QGA).

They are two separate channels:

• QEMU Monitor (port 7100): Controls the VM itself (system_powerdown, info status, migrate, etc.)
• QEMU Guest Agent (virtio-serial): Communicates with the OS inside the VM (guest-fsfreeze, guest-exec, guest-get-osinfo, etc.)

The Guest Agent requires a virtio-serial channel - it cannot work over the QMP monitor port. That's why I added the ARGUMENTS with -device virtio-serial.

For example, guest-fsfreeze-freeze (to freeze I/O for consistent snapshots) is only available through the Guest Agent, not the Monitor.