From Libvirt Wiki
Revision as of 14:30, 6 April 2011 by AnthonyLiguori (talk | contribs) (Summary)
Jump to: navigation, search


Provide a simplified API that implements reasonable default policies for creating highly optimized KVM guests.

The API is targeted toward third party tool makers who need to integrate with virtualization but are not trying to build advanced virtualization management tools.


1. Virtual hardware should be transparent to the API consumer. Library users shouldn't have to worry about the use of virtio vs. e1000.

2. An minimal barrier to entry for creating a new guest. It should be possible to create a guest without filling in a lot of boiler plate information.

3. High level functionality should be exposed in a simple fashion--the interface to pause a VM should be just as simple as the interface to copy a file into a guest.

4. Configuration file should be extensible with user specified data.


These are not meant to be exhaustive but rather to provide examples of interesting API entry points.

Guest Creation

virSimplePtr virSimpleCreate(virConnectionPtr ptr, const char *filename);

Where file contains:

<?xml verison="1.0"?>
<guest xmlns:virtman="http://virt-manager.org/ns">
 <disk id="vda">/home/anthony/foo.img</disk>
 <nic id="eth0" mac="52:10:00:02:32:43"/>
 <nic id="eth1" mac="52:10:00:02:32:44"/>



Both formats are shown but the suggestion isn't to support both. The point is that it should be easy to author a good guest's configuration file. One important point is that there isn't any explicit host network configuration.

The default should be to use bridging.

Guest tooling

// Returns true if guest is using guest addons, false otherwise
bool virSimpleIsGuestAddonsPresent(virSimplePtr guest);

// Either fail or return when virSimpleIsGuestAddonsPresent() would return true
void virSimpleInstallGuestAddons(virSimplePtr guest);

Managing guest tools is one of the more complicated parts of KVM management today. We ought to provide a standard guest tool package and provide standard APIs to install said package.

A common problem in the field is figuring out whether a VM is "optimal" or not when a performance problem is reported. The idea is that virSimpleIsGuestAddonsPresent() becomes a short hand for checking whether the VM is optimally configured.


// Return true when disk is present and usable in guest--not when hotplug
// succeeds.
void virSimpleAddDisk(virSimplePtr guest, const char *id, const char *filename);

This isn't all that different from current APIs. The main difference is the lack of XML descriptions. To make this API work very well actually requires a guest agent that can verify that acpiphp is loaded and that the hot plug was successful.

Interacting with the Guest

// File transfer to and from guest
void virSimpleCopyFileToGuest(virSimplePtr guest, const char *src, const char *dst);
void virSimpleCopyFileFromGuest(virSimplePtr guest, const char *src, const char *dst);

This API demonstrates very high level functionality. It requires the guest addons.

Resource Control

// Simple resource allocation APIs
void virSimpleSetCpuGuarantee(virSimplePtr guest, int cpu, double percentage);
void virSimpleSetCpuEntitlement(virSimplePtr guest, int cpu, double percentage);

void virSimpleSetNetworkGuarantee(virSimplePtr guest, const char *id, double percentage);
void virSimpleSetNetworkEntitlement(virSimplePtr guest, const char *id, double percentage);

This is not a critical base API but the purpose is to illustrate that we ought to treat guest resources in terms that users will expect. Network rate limiting can be done in a ton of different ways with tremendous flexibility. The scope of this API though is to provide a simple interface that covers the most common case.