Generic QEMU guest agent (host side of things)
Project description
The Python packages negotiator-host, negotiator-guest and negotiator-common together implement a generic KVM/QEMU guest agent infrastructure in Python. This infrastructure enables realtime bidirectional communication between hosts and guests which allows user defined metadata to be transferred between them.
Status
Right now this project is a proof of concept. It can already be useful (it’s definitely useful for me) but it is still very primitive and it may have sharp edges and/or eat your pets ;-)
I’m playing with the idea of converting the host’s side of things to a daemon that’s always running and available to the guest agents to answer questions about their host environment, however at the moment all communication is initiated from the host towards the guests and I’m not yet sure how to elegantly implement the architecture I’m envisioning.
Installation
The negotiator packages and their dependencies are compatible with Python 2.6 and newer and are all pure Python. This means you don’t need a compiler toolchain to install the negotiator packages. This is a design decision and so won’t be changed.
On KVM/QEMU hosts
Here’s how to install the negotiator-host package on your host(s):
sudo pip install negotiator-host
If you prefer you can install the Python package in a virtual environment:
sudo apt-get install --yes python-virtualenv virtualenv /tmp/negotiator-host source /tmp/negotiator-host/bin/activate pip install negotiator-host
After installation the negotiator-host program is available. The usage message will help you get started, try the --help option.
On KVM/QEMU guests
Install the negotiator-guest package on your guest(s):
sudo pip install negotiator-guest
If you prefer you can install the Python package in a virtual environment:
sudo apt-get install --yes python-virtualenv virtualenv /tmp/negotiator-guest source /tmp/negotiator-guest/bin/activate pip install negotiator-guest
After installation you need to find a way to run the negotiator-guest command as a daemon. I have good experiences with supervisord, here’s how to set that up:
sudo apt-get install --yes supervisor cat > /etc/supervisor/conf.d/negotiator-guest.conf << EOF [program:negotiator-guest] command = /usr/local/bin/negotiator-guest --daemon autostart = True redirect_stderr = True stdout_logfile = /var/log/negotiator-guest.log EOF supervisorctl update negotiator-guest
Getting started
First you have to add a virtual device to your QEMU guest. You can do so by editing the guest’s XML definition file. On Ubuntu Linux KVM hosts these files are found in the directory /etc/libvirt/qemu. Open the file in your favorite text editor (Vim? :-) and add the the following XML snippet inside the <devices> section:
<channel type='unix'> <source mode='bind' /> <target type='virtio' name='negotiator-channel.0' /> </channel>
After adding the configuration snippet you have to activate it:
virsh define /etc/libvirt/qemu/NAME-OF-GUEST.xml
Now you need to shut down the guest and then start it again:
virsh shutdown --mode acpi NAME-OF-GUEST virsh start NAME-OF-GUEST
Why another guest agent?
The QEMU project provides an official guest agent and this agent is very useful to increase integration between QEMU hosts and guests. However the official QEMU guest agent has two notable shortcomings (for me at least):
- Extensibility
The official QEMU guest agent has some generic mechanisms like being able to write files inside guests, but this is a far cry from a generic, extensible architecture. Ideally given the host and guest’s permission we should be able to transfer arbitrary data and execute user defined logic on both sides.
- Platform support
Despite considerable effort I haven’t been able to get a recent version of the QEMU guest agent running on older Linux distributions (e.g. Ubuntu Linux 10.04). Older versions of the guest agent can be succesfully compiled for such distributions but don’t support the features I require. By creating my own guest agent I have more control over platform support (given the primitives required for communication).
Note that my project in no way tries to replace the official QEMU guest agent. For example I have no intention of implementing freezing and thawing of file systems because the official agent already does that just fine :-). In other words the two projects share a lot of ideas but have very different goals.
How does it work?
The generic guest agent infrastructure uses the same mechanism that the official QEMU guest agent does:
Inside the guest a special character device is created that allows reading and writing. By default this character device is /dev/vport0p1.
On the host a UNIX socket is created that is connected to the character device inside the guest. On Ubuntu Linux KVM/QEMU hosts, these socket files are created in the directory /var/lib/libvirt/qemu/channel/target.
Contact
The latest version of negotiator is available on PyPI and GitHub. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at peter@peterodding.com.
License
This software is licensed under the MIT license.
© 2014 Peter Odding.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.