mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 05:35:25 +00:00
docs: Convert 'support' page to rST
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Peter Krempa
parent
3c489dbbe3
commit
7f3d5914a1
@ -63,7 +63,6 @@ docs_html_in_files = [
|
|||||||
'remote',
|
'remote',
|
||||||
'securityprocess',
|
'securityprocess',
|
||||||
'storage',
|
'storage',
|
||||||
'support',
|
|
||||||
'testapi',
|
'testapi',
|
||||||
'testsuites',
|
'testsuites',
|
||||||
'testtck',
|
'testtck',
|
||||||
@ -112,6 +111,7 @@ docs_rst_files = [
|
|||||||
'strategy',
|
'strategy',
|
||||||
'styleguide',
|
'styleguide',
|
||||||
'submitting-patches',
|
'submitting-patches',
|
||||||
|
'support',
|
||||||
]
|
]
|
||||||
|
|
||||||
# list of web targets to build for docs/web rule
|
# list of web targets to build for docs/web rule
|
||||||
|
|||||||
@ -1,258 +0,0 @@
|
|||||||
<?xml version="1.0" encoding="UTF-8"?>
|
|
||||||
<!DOCTYPE html>
|
|
||||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
||||||
<body>
|
|
||||||
<h1>Support guarantees</h1>
|
|
||||||
|
|
||||||
<ul id="toc"></ul>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2><a id="publicAPI">Primary public API</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
The main public API provided by <code>libvirt.so</code> and described
|
|
||||||
in <code>libvirt/libvirt.h</code> 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:
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt>Functions</dt>
|
|
||||||
<dd>Functions will never be removed from the public API, and will
|
|
||||||
never have parameters added, removed or changed in their signature.
|
|
||||||
IOW they will be ABI compatible forever. The semantics implied by
|
|
||||||
a specific set of parameters passed to the function will remain
|
|
||||||
unchanged. Where a parameter accepts a bitset of feature flags, or
|
|
||||||
an enumerated value, further flags / enum values may be supported
|
|
||||||
in the future. Where a parameter accepts one of a set of related
|
|
||||||
constants, further constants may be supported in the future.
|
|
||||||
</dd>
|
|
||||||
<dt>Struct types</dt>
|
|
||||||
<dd>Once defined in a release, struct definitions will never have any
|
|
||||||
fields add, removed or changed in any way. Their size and layout is
|
|
||||||
fixed forever. If a struct name starts with an underscore, it is
|
|
||||||
considered acceptable to rename it. Applications should thus always
|
|
||||||
use the corresponding typedef in preference to the struct name.
|
|
||||||
</dd>
|
|
||||||
<dt>Union types</dt>
|
|
||||||
<dd>Once defined in a release, union definitions will never have any
|
|
||||||
existing fields removed or changed. New union choices may be added,
|
|
||||||
provided that they don't change the size of the existing union
|
|
||||||
definition. If a struct name starts with an underscore, it is
|
|
||||||
considered acceptable to rename it. Applications should thus always
|
|
||||||
use the corresponding typedef in preference to the struct name.
|
|
||||||
</dd>
|
|
||||||
<dt>Type definitions</dt>
|
|
||||||
<dd>Most custom data types used in the APIs have corresponding typedefs
|
|
||||||
provided for their stable names. The typedefs should always be used
|
|
||||||
in preference to the underlying data type name, as the latter are not
|
|
||||||
guaranteed to be stable.
|
|
||||||
</dd>
|
|
||||||
<dt>Enumerations</dt>
|
|
||||||
<dd>Once defined in a release, existing enumeration values will never
|
|
||||||
be removed or renamed. New enumeration values may be introduced at
|
|
||||||
any time. Every enumeration will have a '_LAST' value which indicates
|
|
||||||
the current highest enumeration value, which may increase with new
|
|
||||||
releases. If an enumeration name starts with an underscore, it is
|
|
||||||
considered acceptable to rename it. Applications should thus always
|
|
||||||
use the corresponding typedef in preference to the enum name.
|
|
||||||
</dd>
|
|
||||||
<dt>Constants</dt>
|
|
||||||
<dd>Once defined in a release, existing constants will never be removed
|
|
||||||
or have their value changed. Most constants are grouped into related
|
|
||||||
sets, and within each set, new constants may be introduced. APIs which
|
|
||||||
use the constants may thus accept or return new constant values over
|
|
||||||
time.
|
|
||||||
</dd>
|
|
||||||
<dt>Symbol versions</dt>
|
|
||||||
<dd>Where the platform library format permits, APIs defined in libvirt.so
|
|
||||||
library will have version information associated. Each API will be
|
|
||||||
tagged with the version in which it was introduced, and this won't
|
|
||||||
be changed thereafter.
|
|
||||||
</dd>
|
|
||||||
</dl>
|
|
||||||
|
|
||||||
<h2><a id="hvAPI">Hypervisor specific APIs</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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 <strong>not</strong>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2><a id="apierrors">Error reporting</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2><a id="xmlschema">XML schemas</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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:
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt>Attributes</dt>
|
|
||||||
<dd>Attributes defined on an XML element will never be removed or
|
|
||||||
renamed. New attributes may be defined. If the set of valid values
|
|
||||||
for an attribute are determined by an enumeration, the permitted
|
|
||||||
values will never be removed or renamed, only new values defined.
|
|
||||||
None the less, specific hypervisors may reject usage of certain
|
|
||||||
values according to their feature set.
|
|
||||||
</dd>
|
|
||||||
<dt>Elements</dt>
|
|
||||||
<dd>Elements defined will never be removed or renamed. New child
|
|
||||||
elements may be defined at any time. In places where only a
|
|
||||||
single instance of a named XML element is used, future versions
|
|
||||||
may be extended to permit multiple instances of the named XML
|
|
||||||
element to be used. An element which currently has no content
|
|
||||||
may later gain child elements.
|
|
||||||
</dd>
|
|
||||||
</dl>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2><a id="configfiles">Configuration files</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2><a id="hvdrivers">Hypervisor drivers</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
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 <a href="hvsupport.html">is detailed separately</a>.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2><a id="rpcproto">RPC protocol</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<h2><a id="virsh">virsh client</a></h2>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
207
docs/support.rst
Normal file
207
docs/support.rst
Normal file
@ -0,0 +1,207 @@
|
|||||||
|
==================
|
||||||
|
Support guarantees
|
||||||
|
==================
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Primary public API
|
||||||
|
------------------
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
Functions
|
||||||
|
Functions will never be removed from the public API, and will never have
|
||||||
|
parameters added, removed or changed in their signature. IOW they will be ABI
|
||||||
|
compatible forever. The semantics implied by a specific set of parameters
|
||||||
|
passed to the function will remain unchanged. Where a parameter accepts a
|
||||||
|
bitset of feature flags, or an enumerated value, further flags / enum values
|
||||||
|
may be supported in the future. Where a parameter accepts one of a set of
|
||||||
|
related constants, further constants may be supported in the future.
|
||||||
|
Struct types
|
||||||
|
Once defined in a release, struct definitions will never have any fields add,
|
||||||
|
removed or changed in any way. Their size and layout is fixed forever. If a
|
||||||
|
struct name starts with an underscore, it is considered acceptable to rename
|
||||||
|
it. Applications should thus always use the corresponding typedef in
|
||||||
|
preference to the struct name.
|
||||||
|
Union types
|
||||||
|
Once defined in a release, union definitions will never have any existing
|
||||||
|
fields removed or changed. New union choices may be added, provided that they
|
||||||
|
don't change the size of the existing union definition. If a struct name
|
||||||
|
starts with an underscore, it is considered acceptable to rename it.
|
||||||
|
Applications should thus always use the corresponding typedef in preference
|
||||||
|
to the struct name.
|
||||||
|
Type definitions
|
||||||
|
Most custom data types used in the APIs have corresponding typedefs provided
|
||||||
|
for their stable names. The typedefs should always be used in preference to
|
||||||
|
the underlying data type name, as the latter are not guaranteed to be stable.
|
||||||
|
Enumerations
|
||||||
|
Once defined in a release, existing enumeration values will never be removed
|
||||||
|
or renamed. New enumeration values may be introduced at any time. Every
|
||||||
|
enumeration will have a '_LAST' value which indicates the current highest
|
||||||
|
enumeration value, which may increase with new releases. If an enumeration
|
||||||
|
name starts with an underscore, it is considered acceptable to rename it.
|
||||||
|
Applications should thus always use the corresponding typedef in preference
|
||||||
|
to the enum name.
|
||||||
|
Constants
|
||||||
|
Once defined in a release, existing constants will never be removed or have
|
||||||
|
their value changed. Most constants are grouped into related sets, and within
|
||||||
|
each set, new constants may be introduced. APIs which use the constants may
|
||||||
|
thus accept or return new constant values over time.
|
||||||
|
Symbol versions
|
||||||
|
Where the platform library format permits, APIs defined in libvirt.so library
|
||||||
|
will have version information associated. Each API will be tagged with the
|
||||||
|
version in which it was introduced, and this won't be changed thereafter.
|
||||||
|
|
||||||
|
Hypervisor specific APIs
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Error reporting
|
||||||
|
---------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
XML schemas
|
||||||
|
-----------
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
Attributes
|
||||||
|
Attributes defined on an XML element will never be removed or renamed. New
|
||||||
|
attributes may be defined. If the set of valid values for an attribute are
|
||||||
|
determined by an enumeration, the permitted values will never be removed or
|
||||||
|
renamed, only new values defined. None the less, specific hypervisors may
|
||||||
|
reject usage of certain values according to their feature set.
|
||||||
|
Elements
|
||||||
|
Elements defined will never be removed or renamed. New child elements may be
|
||||||
|
defined at any time. In places where only a single instance of a named XML
|
||||||
|
element is used, future versions may be extended to permit multiple instances
|
||||||
|
of the named XML element to be used. An element which currently has no
|
||||||
|
content may later gain child elements.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Configuration files
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Hypervisor drivers
|
||||||
|
------------------
|
||||||
|
|
||||||
|
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 <hvsupport.html>`__.
|
||||||
|
|
||||||
|
RPC protocol
|
||||||
|
------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
virsh client
|
||||||
|
------------
|
||||||
|
|
||||||
|
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.
|
||||||
Loading…
Reference in New Issue
Block a user