negotiator-host 0.12.2

Status

Some points to consider:

• The Negotiator project does what I expect from it: realtime bidirectional communication between Linux based KVM/QEMU hosts and guests.

• The project doesn’t have an automated test suite, although its functionality has been extensively tested during development and is being used in a production environment on more than 100 virtual machines (for non-critical tasks).

• The project has not been peer reviewed with regards to security. My primary use case is KVM/QEMU hosts and guests that trust each other to some extent (think private clouds, not shared hosting :-).

Installation

The negotiator packages and their dependencies are compatible with Python 2.7 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.

$ sudo pip install negotiator-host

$ sudo apt-get install --yes python-virtualenv
$ virtualenv /tmp/negotiator-host
$ source /tmp/negotiator-host/bin/activate
$ pip install negotiator-host

$ sudo apt-get install --yes supervisor
$ sudo tee /etc/supervisor/conf.d/negotiator-host.conf >/dev/null << EOF
[program:negotiator-host]
command = /usr/local/bin/negotiator-host --daemon
autostart = True
stdout_logfile = /var/log/negotiator-host.log
stderr_logfile = /var/log/negotiator-host.log
EOF
$ sudo supervisorctl update negotiator-host

$ sudo pip install negotiator-guest

$ sudo apt-get install --yes python-virtualenv
$ virtualenv /tmp/negotiator-guest
$ source /tmp/negotiator-guest/bin/activate
$ pip install negotiator-guest

$ sudo apt-get install --yes supervisor
$ sudo tee /etc/supervisor/conf.d/negotiator-guest.conf >/dev/null << EOF
[program:negotiator-guest]
command = /usr/local/bin/negotiator-guest --daemon
autostart = True
stdout_logfile = /var/log/negotiator-guest.log
stderr_logfile = /var/log/negotiator-guest.log
EOF
$ sudo supervisorctl update negotiator-guest

Getting started

If the instructions below are not enough to get you started, take a look at the Debugging section below for hints about what to do when things don’t work as expected.

1. First you have to add two virtual devices to your QEMU guest. You can do so by editing the guest’s XML definition file. On Ubuntu Linux KVM/QEMU 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' path='/var/lib/libvirt/qemu/channel/target/GUEST_NAME.negotiator-host-to-guest.0' />
      <target type='virtio' name='negotiator-host-to-guest.0' />
   </channel>
   
   <channel type='unix'>
      <source mode='bind' path='/var/lib/libvirt/qemu/channel/target/GUEST_NAME.negotiator-guest-to-host.0' />
      <target type='virtio' name='negotiator-guest-to-host.0' />
   </channel>

   Replace GUEST_NAME with the name of your guest in both places. If you use libvirt 1.0.6 or newer (you can check with virsh --version) you can omit the path='...' attribute because libvirt will fill it in automatically when it reloads the guest’s XML definition file (in step 2).

2. After adding the configuration snippet you have to activate it:

   $ sudo virsh define /etc/libvirt/qemu/GUEST_NAME.xml

3. Now you need to shut down the guest and then start it again:

   $ sudo virsh shutdown --mode acpi GUEST_NAME
   $ sudo virsh start GUEST_NAME

   Note that just rebooting the guest will not add the new virtual devices, you have to actually stop the guest and then start it again!

4. Now go and create some scripts in /usr/lib/negotiator/commands and try to execute them from the other side! Once you start writing your own commands it’s useful to know that commands on the KVM/QEMU host side have access to some environment variables.

Usage

This section documents the command line interfaces of the programs running on hosts and guests. For information on the Python API please refer to the online documentation on Read the Docs.

Debugging

This section contains hints about what to do when things don’t work as expected.

$ CHANNELS_DIRECTORY=/var/lib/libvirt/qemu/channel/target
$ sudo mkdir -p $CHANNELS_DIRECTORY
$ sudo chown libvirt-qemu:kvm $CHANNELS_DIRECTORY

$ diff -u /etc/apparmor.d/abstractions/libvirt-qemu.orig /etc/apparmor.d/abstractions/libvirt-qemu
--- /etc/apparmor.d/abstractions/libvirt-qemu.orig      2015-09-19 12:46:54.316593334 +0200
+++ /etc/apparmor.d/abstractions/libvirt-qemu   2015-09-24 14:43:43.642064576 +0200
@@ -49,6 +49,9 @@
   /run/shm/ r,
   owner /run/shm/spice.* rw,

+  # Local modification to enable the QEMU guest agent.
+  owner /var/lib/libvirt/qemu/channel/target/* rw,
+
   # 'kill' is not required for sound and is a security risk. Do not enable
   # unless you absolutely need it.
   deny capability kill,

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 scriptable guest agent infrastructure uses the same mechanism that the official QEMU guest agent does:

• Inside the guest special character devices are created that allow reading and writing. These character devices are /dev/vport[0-9]p[0-9].

• On the host UNIX domain sockets are created that are connected to the character devices inside the guest. On Ubuntu Linux KVM/QEMU hosts, these UNIX domain sockets are created in the directory /var/lib/libvirt/qemu/channel/target.

Contact

The latest version of negotiator is available on PyPI and GitHub. You can find the documentation on Read The Docs. 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.

© 2019 Peter Odding.