https://github.com/gechandesu/qga
QEMU Guest Agent Protocol client
https://github.com/gechandesu/qga
qemu qemu-ga qemu-guest-agent virtualization vlang vlang-module vlang-package
Last synced: 4 months ago
JSON representation
QEMU Guest Agent Protocol client
- Host: GitHub
- URL: https://github.com/gechandesu/qga
- Owner: gechandesu
- License: lgpl-3.0
- Created: 2025-06-09T21:04:50.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-06-11T16:32:48.000Z (about 1 year ago)
- Last Synced: 2025-06-18T09:48:55.881Z (about 1 year ago)
- Topics: qemu, qemu-ga, qemu-guest-agent, virtualization, vlang, vlang-module, vlang-package
- Language: V
- Homepage: https://gechandesu.github.io/qga/
- Size: 25.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: COPYING
Awesome Lists containing this project
README
# QEMU Guest Agent Protocol client for V
`qga` is full featured QGA client for interacting with guest operating systems
in QEMU-powered virtual machine from virtualisation host.
See also:
- Guest Agent in QEMU Wiki: https://wiki.qemu.org/Features/GuestAgent
- QEMU Guest Agent Protocol Reference: https://qemu-project.gitlab.io/qemu/interop/qemu-ga-ref.html
## Usage
Run the virtual machine. In this example `disk.qcow2` contains Debian 12 Bookworm
with `qemu-guest-agent` package installed.
```
/usr/bin/qemu-system-x86_64 \
-name testvm \
-accel kvm \
-cpu host \
-smp 1 \
-m 1024M \
-drive file=disk.qcow2,media=disk,if=virtio \
-chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
-device virtio-serial \
-device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0
```
Then connect to a guest agent server socket `/tmp/gqa.sock`:
```v
import qga
fn main() {
mut ga := qga.Client.new('/tmp/qga.sock')!
agent_version := ga.info()!.version
println('everything is fine! guest agent version is ${agent_version}')
}
```
## Error handling
`GuestAgentError` contains extended error information. See the description of
the structure fields.
The error can be returned either directly by the guest agent or when trying to
communicating it. `GuestAgentError` has an explicit flag to distinguish such
errors. If for some reason the guest agent could not be reached, `is_unreachable`
will be true. The error information will be in the underlying error stored in the
`err` field and in the error text itself.
```v
module main
import qga
fn main() {
mut ga := qga.Client.new('/tmp/qga.sock')!
ga.get_devices() or {
if err is qga.GuestAgentError {
if err.is_unreachable {
println('agent is unreachable')
return
} else {
println('error info from guest agent: class=${err.class} desc=${err.desc}')
return
}
}
}
}
```
Prints this (so `guest-get-devices` is disabled on Debian):
```
error info from guest agent: class=CommandNotFound desc=Command guest-get-devices has been disabled
```
In addition, `qga` module provides a small set of specific error codes.
They can be checked in this way without `err` smartcasting:
```v ignore
ga.ping() or {
match err.code() {
qga.err_no_connect { panic('socket connection error') }
qga.err_timed_out { panic('timeout reached') }
qga.err_from_agent { panic('error ocurred in guest agent') }
else { panic(err) }
}
}
```
## License
`LGPL-3.0-or-later`
See [COPYING](COPYING) and [COPYING.LESSER](COPYING.LESSER) for information.