File: support.html

package info (click to toggle)
libvirt 5.6.0-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 240,844 kB
  • sloc: ansic: 584,521; xml: 176,725; sh: 9,912; python: 4,731; perl: 4,343; makefile: 3,321; ml: 465
file content (384 lines) | stat: -rw-r--r-- 18,583 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <!--
        This file is autogenerated from support.html.in
        Do not edit this file. Changes will be lost.
      -->
  <!--
        This page was generated at Tue Jul 30 02:04:26 UTC 2019.
      -->
  <head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <link rel="stylesheet" type="text/css" href="main.css"/>
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"/>
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/>
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/>
    <link rel="manifest" href="/manifest.json"/>
    <meta name="theme-color" content="#ffffff"/>
    <title>libvirt: Support guarantees</title>
    <meta name="description" content="libvirt, virtualization, virtualization API"/>
    <script type="text/javascript" src="js/main.js">
      <!--// forces non-empty element-->
    </script>
  </head>
  <body onload="pageload()">
    <div id="body">
      <div id="content">
        <h1>Support guarantees</h1>
        <ul>
          <li>
            <a href="#publicAPI">Primary public API</a>
          </li>
          <li>
            <a href="#hvAPI">Hypervisor specific APIs</a>
          </li>
          <li>
            <a href="#apierrors">Error reporting</a>
          </li>
          <li>
            <a href="#xmlschema">XML schemas</a>
          </li>
          <li>
            <a href="#configfiles">Configuration files</a>
          </li>
          <li>
            <a href="#hvdrivers">Hypervisor drivers</a>
          </li>
          <li>
            <a href="#rpcproto">RPC protocol</a>
          </li>
          <li>
            <a href="#virsh">virsh client</a>
          </li>
        </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>
          <a class="headerlink" href="#publicAPI" title="Permalink to this headline">¶</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>
          <a class="headerlink" href="#hvAPI" title="Permalink to this headline">¶</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>
          <a class="headerlink" href="#apierrors" title="Permalink to this headline">¶</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 &amp; taking action
      upon specific error codes, as their behaviour may change across releases.
    </p>
        <h2>
          <a id="xmlschema">XML schemas</a>
          <a class="headerlink" href="#xmlschema" title="Permalink to this headline">¶</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>
          <a class="headerlink" href="#configfiles" title="Permalink to this headline">¶</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 &amp; 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>
          <a class="headerlink" href="#hvdrivers" title="Permalink to this headline">¶</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>
          <a class="headerlink" href="#rpcproto" title="Permalink to this headline">¶</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>
          <a class="headerlink" href="#virsh" title="Permalink to this headline">¶</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>
      </div>
    </div>
    <div id="nav">
      <div id="home">
        <a href="index.html">Home</a>
      </div>
      <div id="jumplinks">
        <ul>
          <li>
            <a href="downloads.html">Download</a>
          </li>
          <li>
            <a href="contribute.html">Contribute</a>
          </li>
          <li>
            <a href="docs.html">Docs</a>
          </li>
        </ul>
      </div>
      <div id="search">
        <form id="simplesearch" action="https://www.google.com/search" enctype="application/x-www-form-urlencoded" method="get">
          <div>
            <input id="searchsite" name="sitesearch" type="hidden" value="libvirt.org"/>
            <input id="searchq" name="q" type="text" size="12" value=""/>
            <input name="submit" type="submit" value="Go"/>
          </div>
        </form>
        <div id="advancedsearch">
          <span>
            <input type="radio" name="what" id="whatwebsite" checked="checked" value="website"/>
            <label for="whatwebsite">Website</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatwiki" value="wiki"/>
            <label for="whatwiki">Wiki</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatdevs" value="devs"/>
            <label for="whatdevs">Developers list</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatusers" value="users"/>
            <label for="whatusers">Users list</label>
          </span>
        </div>
      </div>
    </div>
    <div id="footer">
      <div id="contact">
        <h3>Contact</h3>
        <ul>
          <li>
            <a href="contact.html#email">email</a>
          </li>
          <li>
            <a href="contact.html#irc">irc</a>
          </li>
        </ul>
      </div>
      <div id="community">
        <h3>Community</h3>
        <ul>
          <li>
            <a href="https://twitter.com/hashtag/libvirt">twitter</a>
          </li>
          <li>
            <a href="http://stackoverflow.com/questions/tagged/libvirt">stackoverflow</a>
          </li>
          <li>
            <a href="http://serverfault.com/questions/tagged/libvirt">serverfault</a>
          </li>
        </ul>
      </div>
      <div id="conduct">
            Participants in the libvirt project agree to abide by <a href="governance.html#codeofconduct">the project code of conduct</a></div>
      <br class="clear"/>
    </div>
  </body>
</html>