From nobody Mon May  6 02:13:19 2024
Delivered-To: importer@patchew.org
Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28
 as permitted sender) client-ip=209.132.183.28;
 envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com;
Authentication-Results: mx.zohomail.com;
	spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
 permitted sender)  smtp.mailfrom=libvir-list-bounces@redhat.com
Return-Path: <libvir-list-bounces@redhat.com>
Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by
 mx.zohomail.com
	with SMTPS id 1510852762309985.4295259216394;
 Thu, 16 Nov 2017 09:19:22 -0800 (PST)
Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com
 [10.5.11.14])
	(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mx1.redhat.com (Postfix) with ESMTPS id 1249868695;
	Thu, 16 Nov 2017 17:19:21 +0000 (UTC)
Received: from colo-mx.corp.redhat.com
 (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21])
	by smtp.corp.redhat.com (Postfix) with ESMTPS id E08B68CF8D;
	Thu, 16 Nov 2017 17:19:20 +0000 (UTC)
Received: from lists01.pubmisc.prod.ext.phx2.redhat.com
 (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33])
	by colo-mx.corp.redhat.com (Postfix) with ESMTP id 9E50C4A467;
	Thu, 16 Nov 2017 17:19:20 +0000 (UTC)
Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com
	[10.5.11.16])
	by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP
	id vAGHJJZQ016471 for <libvir-list@listman.util.phx.redhat.com>;
	Thu, 16 Nov 2017 12:19:19 -0500
Received: by smtp.corp.redhat.com (Postfix)
	id 642285C3FF; Thu, 16 Nov 2017 17:19:19 +0000 (UTC)
Received: from localhost.localdomain.com (unknown [10.42.22.189])
	by smtp.corp.redhat.com (Postfix) with ESMTP id 68244922F3;
	Thu, 16 Nov 2017 17:19:16 +0000 (UTC)
From: "Daniel P. Berrange" <berrange@redhat.com>
To: libvir-list@redhat.com
Date: Thu, 16 Nov 2017 17:19:14 +0000
Message-Id: <20171116171914.3856-1-berrange@redhat.com>
X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16
X-loop: libvir-list@redhat.com
Subject: [libvirt] [PATCH] docs: add a page describing support guarantees
	for libvirt features
X-BeenThere: libvir-list@redhat.com
X-Mailman-Version: 2.1.12
Precedence: junk
List-Id: Development discussions about the libvirt library & tools
	<libvir-list.redhat.com>
List-Unsubscribe: <https://www.redhat.com/mailman/options/libvir-list>,
	<mailto:libvir-list-request@redhat.com?subject=unsubscribe>
List-Archive: <https://www.redhat.com/archives/libvir-list>
List-Post: <mailto:libvir-list@redhat.com>
List-Help: <mailto:libvir-list-request@redhat.com?subject=help>
List-Subscribe: <https://www.redhat.com/mailman/listinfo/libvir-list>,
	<mailto:libvir-list-request@redhat.com?subject=subscribe>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Sender: libvir-list-bounces@redhat.com
Errors-To: libvir-list-bounces@redhat.com
X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14
X-Greylist: Sender IP whitelisted,
 not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]);
 Thu, 16 Nov 2017 17:19:21 +0000 (UTC)
X-ZohoMail: RSF_0  Z_629925259 SPT_0
Content-Type: text/plain; charset="utf-8"

While we have collective knowledge about the support status of various
parts of libvirt, this has never been formally documented, leaving our
users to guess.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Reviewed-by: Jim Fehlig <jfehlig@suse.com>
---
 docs/docs.html.in    |   3 +
 docs/support.html.in | 257 +++++++++++++++++++++++++++++++++++++++++++++++=
++++
 2 files changed, 260 insertions(+)
 create mode 100644 docs/support.html.in

diff --git a/docs/docs.html.in b/docs/docs.html.in
index 931da85424..a8d544f83f 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -110,6 +110,9 @@
         <dt><a href=3D"drivers.html">Drivers</a></dt>
         <dd>Hypervisor specific driver information</dd>
=20
+        <dt><a href=3D"support.html">Support guarantees</a></dt>
+        <dd>Details of support status for various interfaces</dd>
+
         <dt><a href=3D"hvsupport.html">Driver support</a></dt>
         <dd>matrix of API support per hypervisor per release</dd>
=20
diff --git a/docs/support.html.in b/docs/support.html.in
new file mode 100644
index 0000000000..6f34a35eb7
--- /dev/null
+++ b/docs/support.html.in
@@ -0,0 +1,257 @@
+<?xml version=3D"1.0" encoding=3D"UTF-8"?>
+<!DOCTYPE html>
+<html xmlns=3D"http://www.w3.org/1999/xhtml">
+  <body>
+    <h1>Support guarantees</h1>
+
+    <ul id=3D"toc"></ul>
+
+    <p>
+      This document will outline the support status / guarantees around the
+      very interfaces that libvirt exposes to applications and/or system
+      adminstrators. 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=3D"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 typed=
efs
+        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 indica=
tes
+        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 remo=
ved
+        or have their value changed. Most constants are grouped into relat=
ed
+        sets, and within each set, new constants may be introduced. APIs w=
hich
+        use the constants may thus accept or return new constant values ov=
er
+        time.
+      </dd>
+      <dt>Symbol versions</dt>
+      <dd>Where the platform library format permits, APIs defined in libvi=
rt.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=3D"hvAPI">Hypervisor specific APIs</a></h2>
+
+    <p>
+      A number of hypervisor drivers provide additional libraries with hyp=
ervisor
+      specific APIs, extending the core libvirt API. These add-on librarie=
s follow
+      the same general principles described above, however, they are <stro=
ng>not</strong>
+      not guranteed to be preserved forever. The project reserves the righ=
t to remove
+      hypervisor specific APIs in any new release, or to change their sema=
ntics.
+      That said the project will endeavour to maintain API compatibility f=
or 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 inter=
actions
+      with normal libvirt operations. An application which chooses to make=
 use of
+      hypervisor specific APIs should validate their operation with each n=
ew release
+      of libvirt and each new release of the underlying hypervisor. The se=
mantics
+      may change in unexpected ways, or have unforseen interactions with l=
ibvirt's
+      operation.
+    </p>
+
+    <h2><a id=3D"apierrors">Error reporting</a></h2>
+
+    <p>
+      Almost API calls are subject to failure and so will report error cod=
es and
+      messages. Libvirt defines error codes for a wide variety of scenario=
s, some
+      are very targetted to specific problems, while others are general pu=
rpose
+      for broad classes of problem. Over time the error codes reported are=
 liable
+      to, usually changing from a generic error to a more specific error. =
Thus
+      applications should be careful about checking for &amp; taking actio=
n upon
+      specific error codes, as the behaviour is liable to change across re=
leases.
+    </p>
+       =20
+    <h2><a id=3D"xmlschema">XML schemas</a></h2>
+
+    <p>
+      The main objects exposed via the primary libvirt public API are usua=
lly
+      configured via XML documents following specific schemas. The XML sch=
emas
+      are considered to be stable formats, whose compatibility will be mai=
ntained
+      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 specif=
ic
+      extensions to the XML documents. These extensions will always be
+      contained within a hypervisor specific XML namespace. There is gener=
ally
+      no guarantee of long term support for the hypervisor specific extens=
ions
+      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=3D"configfiles">Configuration files</a></h2>
+
+    <p>
+      A number of programs / daemons provided libvirt rely on host filesys=
tem
+      configuration files. These configuration files are accompanied by au=
geas
+      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 pres=
erve
+      them as long as is possible. If a configuration option is dropped fr=
om
+      the file, the augeas lens will retain the ability to read that confi=
guration
+      parameter, so that it is able to read &amp; update historically modi=
fied
+      files.
+
+      The default configuration files ship with all parameters commented o=
ut
+      such that a deployment relies on the built-in defaults of the applic=
ation
+      in question. There is no guarantee that the defaults will remain the=
 same
+      across releases. An deployments that expects a particular value for a
+      configuration parameter should consider defining it explicitly, inst=
ead
+      of relying on the defaults.
+    </p>
+
+    <h2><a id=3D"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 no supported. Likewise libvirt will
+      make reasonable efforts to keep API calls working across hypervisor
+      releases even if the underlying implementation changes. In cases whe=
re
+      this is impossible, an suitable error will be reported. The list of
+      APIs which have implementations <a href=3D"hvsupport.html">is detail=
ed separately</a>.
+    </p>
+
+    <h2><a id=3D"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 us=
es
+      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 wh=
ich
+      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 w=
ill
+      not be removed, nor have their contents changed. Thus if an applicat=
ion
+      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 encr=
yption
+      options for the protocol, and the defaults used in this area may cha=
nge
+      over time. This is particularly true of the TLS ciphers permitted. T=
hus
+      applications choosing to implement the RPC protocol must be prepared=
 to
+      track support for new security options. If defaults are changed, how=
ever,
+      it will generally be possible to reconfigure the daemon to use the o=
ld
+      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 implementation that are liable to change
+      at any time. Applications must not attempt to talk to these other
+      daemons directly.
+    </p>
+
+    <h2><a id=3D"virsh">virsh client</a></h2>
+
+    <p>
+      The virsh program provides a simple client to interact with an arbit=
rary libvirt
+      hypevisor connection. Since it uses the primary public API of libvir=
t, it should
+      generally inherit the guarantees associated with that API, and with =
the hypervisor
+      driver. The commands that virsh exposes, and the arguments they acce=
pt are all
+      considered to be long term stable. Existing commands and arguments w=
ill not be
+      removed or renamed. New commands and arguments may be added in new r=
eleases.
+      The text output format produced by virsh commands is not generally g=
uaranteed 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 documen=
t), can be
+      treated as having stable format.
+    </p>
+   =20
+  </body>
+</html>
--=20
2.14.3

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list