This document will outline the support status / guarantees around the very interfaces that libvirt exposes to applications and/or system administrators. The intent is to help users understand what features they can rely upon in particular scenarios, and whether they are likely to suffer disruption during upgrades.
The main public API provided by libvirt.so and described
in libvirt/libvirt.h exposes the primary hypervisor
agnostic management interface of libvirt. This API has the strongest
guarantee of any part of libvirt with a promise to keep backwards
compatibility forever. Specific details are as follows:
A number of hypervisor drivers provide additional libraries with hypervisor specific APIs, extending the core libvirt API. These add-on libraries follow the same general principles described above, however, they are not guaranteed to be preserved forever. The project reserves the right to remove hypervisor specific APIs in any new release, or to change their semantics. That said the project will endeavour to maintain API compatibility for as long as is practical.
Use of some hypervisor specific APIs may result in the running guest being marked as "tainted" if the API is at risk of having unexpected interactions with normal libvirt operations. An application which chooses to make use of hypervisor specific APIs should validate their operation with each new release of libvirt and each new release of the underlying hypervisor. The semantics may change in unexpected ways, or have unforeseen interactions with libvirt's operation.
Most API calls are subject to failure and so will report error codes and messages. Libvirt defines error codes for a wide variety of scenarios, some represent very specific problems, while others are general purpose for broad classes of problem. Over time the error codes reported are liable to change, usually changing from a generic error to a more specific error. Thus applications should be careful about checking for & taking action upon specific error codes, as their behaviour may change across releases.
The main objects exposed via the primary libvirt public API are usually configured via XML documents following specific schemas. The XML schemas are considered to be stable formats, whose compatibility will be maintained forever. Specific details are as follows:
Some hypervisor drivers may choose to allow use of hypervisor specific extensions to the XML documents. These extensions will always be contained within a hypervisor specific XML namespace. There is generally no guarantee of long term support for the hypervisor specific extensions across releases, though the project will endeavour to preserve them as long as is possible. Applications choosing to use hypervisor specific extensions should validate their operation against new libvirt or hypervisor releases.
A number of programs / daemons provided libvirt rely on host filesystem configuration files. These configuration files are accompanied by augeas lens for easy manipulation by applications. There is in general no guarantee that parameters available in the configuration file will be preserved across releases, though the project will endeavour to preserve them as long as is possible. If a configuration option is dropped from the file, the augeas lens will retain the ability to read that configuration parameter, so that it is able to read & update historically modified files. The default configuration files ship with all parameters commented out such that a deployment relies on the built-in defaults of the application in question. There is no guarantee that the defaults will remain the same across releases. A deployment that expects a particular value for a configuration parameter should consider defining it explicitly, instead of relying on the defaults.
The libvirt project provides support for a wide variety of hypervisor drivers. These drivers target certain versions of the hypervisor's underlying management APIs. In general libvirt aims to work with any hypervisor version that is still broadly supported by its vendor. When a vendor discontinues support for a particular hypervisor version it will be dropped by libvirt. Libvirt may choose to drop support for a particular hypervisor version prior to the vendor ending support, if it deems that the likely usage is too small to justify the ongoing maintenance cost.
Each hypervisor release will implement a distinct subset of features that can be expressed in the libvirt APIs and XML formats. While the XML schema syntax will be stable across releases, libvirt is unable to promise that it will always be able to support usage of the same features across hypervisor releases. Where a hypervisor changes the way a feature is implemented, the project will endeavour to adapt to the new implementation to provide the same semantics. In cases where the feature is discontinued by the hypervisor, libvirt will return an error indicating it is not supported. Likewise libvirt will make reasonable efforts to keep API calls working across hypervisor releases even if the underlying implementation changes. In cases where this is impossible, a suitable error will be reported. The list of APIs which have implementations is detailed separately.
For some hypervisor drivers, the libvirt.so library communicates with separate libvirt daemons to perform work. This communication takes place over a binary RPC protocol defined by libvirt. The protocol uses the XDR format for data encoding, and the message packet format is defined in libvirt source code.
Applications are encouraged to use the primary libvirt.so library which transparently talks to the daemons, so that they are not exposed to the hypervisor driver specific details. None the less, the RPC protocol associated with the libvirtd is considered to be a long term stable ABI. It will only ever have new messages added to it, existing messages will not be removed, nor have their contents changed. Thus if an application does wish to provide its own client side implementation of the RPC protocol this is supported, with the caveat that the application will loose the ability to work with certain hypervisors libvirt supports. The project reserves the right to define new authentication and encryption options for the protocol, and the defaults used in this area may change over time. This is particularly true of the TLS ciphers permitted. Thus applications choosing to implement the RPC protocol must be prepared to track support for new security options. If defaults are changed, however, it will generally be possible to reconfigure the daemon to use the old defaults, albeit with possible implications for system security.
Other daemons besides, libvirtd, also use the same RPC protocol, but with different message types defined. These RPC protocols are all considered to be private implementations that are liable to change at any time. Applications must not attempt to talk to these other daemons directly.
The virsh program provides a simple client to interact with an arbitrary libvirt hypervisor connection. Since it uses the primary public API of libvirt, it should generally inherit the guarantees associated with that API, and with the hypervisor driver. The commands that virsh exposes, and the arguments they accept are all considered to be long term stable. Existing commands and arguments will not be removed or renamed. New commands and arguments may be added in new releases. The text output format produced by virsh commands is not generally guaranteed to be stable if it contains compound data (eg formatted tables or lists). Commands which output single data items (ie an object name, or an XML document), can be treated as having stable format.