98 lines
2.5 KiB
Markdown
98 lines
2.5 KiB
Markdown
# 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() {
|
|
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.
|