Phoenix is a guest-side agent for qemu-kvm virtual machines. It provides communication with the guest system using virtio-serial port, and allows to perform some commands in the guest system from the master.

• working with guest's files and directories: reading/writing files, setting mode/uid/gid, creating directories, listing directories etc.
• querying and setting network parameters: adding/removing IP-adresses, getting summary information.
• freezing/thawing guest filesystems.
• querying summary information about the guest: uptime, load average, utsname, logged in users, ram/swap usage, block devices stat, etc.

Launch a qemu-kvm process with additional options for the character device driver required to communicate with the guest agent:

qemu-system-x86_64 \
    -chardev socket,id=ga0,path=/var/run/guestagent.sock,server,nowait \
    -device virtio-serial-pci \
    -device virtserialport,chardev=ga0,name=org.guest-agent.0

On the guest system, launch the guest agent like this:

phoenix-ga -p /dev/virtio-ports/org.guest-agent.0

Now, we can talk to guest agent from the master server:

master# socat - UNIX-CONNECT:/var/run/guestagent.sock
{ "execute": "get-commands", "tag": "abc" }
{ "return": ["get-commands", "agent-shutdown", "ping", "get-netifaces", "linux-ipaddr-add", "linux-ipaddr-del", "file-open", "file-close", "file-read", "file-write", "get-file-md5sum"], "tag": "abc" }

{ "execute": "ping", "tag": "def" }
{ "return": "0.1", "tag": "def" }

Communication with the guest agent occurs at QMP-like protocol. The success response contains the field "return" with the results of command execution. The error response contains the field "error" with a base64-encoded description. For details see the commands documentation.

Since version 0.4 the field "error" also contains an extended code status, which can take next values:

• an unsigned number (errno) describing an error condition
• and -1 in case if an extended code is not defined

E.g:

{ "error": { "bufb64": "anVzdCBhIHRlc3QgZXJyb3I=", "code": -1 }, "tag": "8be" }

Measurements were performed using the cpuacct cgroups controller and pmap.

In the idling agent consumed about 17 seconds of CPU time per day and about 2.5 Mb RSS.

Latest version is available here

mkdir phoenix-ga && cd phoenix-ga
export GOPATH=$(pwd); go get -v -tags netgo -ldflags '-s -w' github.com/0xef53/phoenix-guest-agent/...
mv bin/phoenix-guest-agent bin/phoenix-ga

GNU/Linux

MIT