Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/meson.build | 2 +- docs/support.html.in | 258 ------------------------------------------- docs/support.rst | 207 ++++++++++++++++++++++++++++++++++ 3 files changed, 208 insertions(+), 259 deletions(-) delete mode 100644 docs/support.html.in create mode 100644 docs/support.rst diff --git a/docs/meson.build b/docs/meson.build index d0c1217351..b3432cc6f6 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -63,7 +63,6 @@ docs_html_in_files = [ 'remote', 'securityprocess', 'storage', - 'support', 'testapi', 'testsuites', 'testtck', @@ -112,6 +111,7 @@ docs_rst_files = [ 'strategy', 'styleguide', 'submitting-patches', + 'support', ] # list of web targets to build for docs/web rule diff --git a/docs/support.html.in b/docs/support.html.in deleted file mode 100644 index 38f2f906e0..0000000000 --- a/docs/support.html.in +++ /dev/null @@ -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> diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 0000000000..f285f63c55 --- /dev/null +++ b/docs/support.rst @@ -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. -- 2.35.1
