File: formatsnapshot.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 (462 lines) | stat: -rw-r--r-- 20,782 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
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <!--
        This file is autogenerated from formatsnapshot.html.in
        Do not edit this file. Changes will be lost.
      -->
  <!--
        This page was generated at Tue Jul 30 02:04:27 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: Snapshot XML format</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>Snapshot XML format</h1>
        <ul>
          <li>
            <a href="#SnapshotAttributes">Snapshot XML</a>
          </li>
          <li>
            <a href="#example">Examples</a>
          </li>
        </ul>
        <h2>
          <a id="SnapshotAttributes">Snapshot XML</a>
          <a class="headerlink" href="#SnapshotAttributes" title="Permalink to this headline">¶</a>
        </h2>
        <p>
      Snapshots are one form
      of <a href="kbase/domainstatecapture.html">domain state
      capture</a>.  There are several types of snapshots:
    </p>
        <dl>
          <dt>disk snapshot</dt>
          <dd>Contents of disks (whether a subset or all disks associated
        with the domain) are saved at a given point of time, and can
        be restored back to that state.  On a running guest, a disk
        snapshot is likely to be only crash-consistent rather than
        clean (that is, it represents the state of the disk on a
        sudden power outage, and may need fsck or journal replays to
        be made consistent); on an inactive guest, a disk snapshot is
        clean if the disks were clean when the guest was last shut
        down.  Disk snapshots exist in two forms: internal (file
        formats such as qcow2 track both the snapshot and changes
        since the snapshot in a single file) and external (the
        snapshot is one file, and the changes since the snapshot are
        in another file).</dd>
          <dt>memory state (or VM state)</dt>
          <dd>Tracks only the state of RAM and all other resources in use
        by the VM.  If the disks are unmodified between the time a VM
        state snapshot is taken and restored, then the guest will
        resume in a consistent state; but if the disks are modified
        externally in the meantime, this is likely to lead to data
        corruption.</dd>
          <dt>full system</dt>
          <dd>A combination of disk snapshots for all disks as well as VM
        memory state, which can be used to resume the guest from where it
        left off with symptoms similar to hibernation (that is, TCP
        connections in the guest may have timed out, but no files or
        processes are lost).</dd>
        </dl>
        <p>
      Libvirt can manage all three types of snapshots.  For now, VM
      state (memory) snapshots are created only by
      the <code>virDomainSave()</code>, <code>virDomainSaveFlags</code>,
      and <code>virDomainManagedSave()</code> functions, and restored
      via the <code>virDomainRestore()</code>,
      <code>virDomainRestoreFlags()</code>, <code>virDomainCreate()</code>,
      and <code>virDomainCreateWithFlags()</code> functions (as well
      as via domain autostart).  With managed snapshots, libvirt
      tracks all information internally; with save images, the user
      tracks the snapshot file, but libvirt provides functions such
      as <code>virDomainSaveImageGetXMLDesc()</code> to work with
      those files.
    </p>
        <p>Full system snapshots are created
      by <code>virDomainSnapshotCreateXML()</code> with no flags, while
      disk snapshots are created by the same function with
      the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code>
      flag. Regardless of the flags provided, restoration of the
      snapshot is handled by
      the <code>virDomainRevertToSnapshot()</code> function.  For
      these types of snapshots, libvirt tracks each snapshot as a
      separate <code>virDomainSnapshotPtr</code> object, and maintains
      a tree relationship of which snapshots descended from an earlier
      point in time.
    </p>
        <p>
      Attributes of libvirt snapshots are stored as child elements of
      the <code>domainsnapshot</code> element.  At snapshot creation
      time, normally only the <code>name</code>, <code>description</code>,
      and <code>disks</code> elements are settable; the rest of the
      fields are ignored on creation, and will be filled in by
      libvirt in for informational purposes
      by <code>virDomainSnapshotGetXMLDesc()</code>.  However, when
      redefining a snapshot (<span class="since">since 0.9.5</span>),
      with the <code>VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE</code> flag
      of <code>virDomainSnapshotCreateXML()</code>, all of the XML
      described here is relevant on input, even the fields that are
      normally described as readonly for output.
    </p>
        <p>
      Snapshots are maintained in a hierarchy.  A domain can have a
      current snapshot, which is the most recent snapshot compared to
      the current state of the domain (although a domain might have
      snapshots without a current snapshot, if snapshots have been
      deleted in the meantime).  Creating or reverting to a snapshot
      sets that snapshot as current, and the prior current snapshot is
      the parent of the new snapshot.  Branches in the hierarchy can
      be formed by reverting to a snapshot with a child, then creating
      another snapshot.  For now, the creation of external snapshots
      when checkpoints exist is forbidden, although future work will
      make it possible to integrate these two concepts.
    </p>
        <p>
      The top-level <code>domainsnapshot</code> element may contain
      the following elements:
    </p>
        <dl>
          <dt>
            <code>name</code>
          </dt>
          <dd>The optional name for this snapshot.  If the name is
        omitted, libvirt will create a name based on the time of the
        creation.
      </dd>
          <dt>
            <code>description</code>
          </dt>
          <dd>An optional human-readable description of the snapshot.  If
        the description is omitted when initially creating the
        snapshot, then this field will be empty.
      </dd>
          <dt>
            <code>memory</code>
          </dt>
          <dd>On input, this is an optional request for how to handle VM
        memory state.  For an offline domain or a disk-only snapshot,
        attribute <code>snapshot</code> must be <code>no</code>, since
        there is no VM state saved; otherwise, the attribute can
        be <code>internal</code> if the memory state is piggy-backed with
        other internal disk state, or <code>external</code> along with
        a second attribute <code>file</code> giving the absolute path
        of the file holding the VM memory state.  <span class="since">Since
        1.0.1</span>
      </dd>
          <dt>
            <code>disks</code>
          </dt>
          <dd>On input, this is an optional listing of specific
        instructions for disk snapshots; it is needed when making a
        snapshot of only a subset of the disks associated with a
        domain, or when overriding the domain defaults for how to
        snapshot each disk, or for providing specific control over
        what file name is created in an external snapshot.  On output,
        this is fully populated to show the state of each disk in the
        snapshot, including any properties that were generated by the
        hypervisor defaults.  For full system snapshots, this field is
        ignored on input and omitted on output (a full system snapshot
        implies that all disks participate in the snapshot process).
        This element has a list of <code>disk</code>
        sub-elements, describing anywhere from zero to all of the
        disks associated with the domain.  <span class="since">Since
        0.9.5</span>
        <dl><dt><code>disk</code></dt><dd>This sub-element describes the snapshot properties of a
            specific disk.  The attribute <code>name</code> is
            mandatory, and must match either the <code>&lt;target
            dev='name'/&gt;</code> (recommended) or an unambiguous
            <code>&lt;source file='name'/&gt;</code> of one of
            the <a href="formatdomain.html#elementsDisks">disk
            devices</a> specified for the domain at the time of the
            snapshot.  The attribute <code>snapshot</code> is
            optional, and the possible values are the same as the
            <code>snapshot</code> attribute for
             <a href="formatdomain.html#elementsDisks">disk devices</a>
            (<code>no</code>, <code>internal</code>,
            or <code>external</code>).  Some hypervisors like ESX
            require that if specified, the snapshot mode must not
            override any snapshot mode attached to the corresponding
            domain disk, while others like qemu allow this field to
            override the domain default.

            <dl><dt><code>source</code></dt><dd>If the snapshot mode is external (whether specified
              or inherited), then there is an optional sub-element
              <code>source</code>, with an attribute <code>file</code>
              giving the name of the new file.
              If <code>source</code> is not
              given and the disk is backed by a local image file (not
              a block device or remote storage), a file name is
              generated that consists of the existing file name
              with anything after the trailing dot replaced by the
              snapshot name.  Remember that with external
              snapshots, the original file name becomes the read-only
              snapshot, and the new file name contains the read-write
              delta of all disk changes since the snapshot.
              <p/>
              The <code>source</code> element also may contain the
              <code>seclabel</code> element (described in the
              <a href="formatdomain.html#seclabel">domain XML documentation</a>)
              which can be used to override the domain security labeling policy
              for <code>source</code>.
              </dd><dt><code>driver</code></dt><dd>An optional sub-element <code>driver</code>,
              with an attribute <code>type</code> giving the driver type (such
              as qcow2), of the new file created by the external
              snapshot of the new file.
              </dd><dt><code>seclabel</code></dt></dl>

            <span class="since">Since 1.2.2</span> the <code>disk</code> element
            supports an optional attribute <code>type</code> if the
            <code>snapshot</code> attribute is set to <code>external</code>.
            This attribute specifies the snapshot target storage type and allows
            to overwrite the default <code>file</code> type. The <code>type</code>
            attribute along with the format of the <code>source</code>
            sub-element is identical to the <code>source</code> element used in
            domain disk definitions. See the
            <a href="formatdomain.html#elementsDisks">disk devices</a> section
            documentation for further information.

            Libvirt currently supports the <code>type</code> element in the qemu
            driver and supported values are <code>file</code>, <code>block</code>
            and <code>network</code> with a protocol of <code>gluster</code>
            <span class="since">(since 1.2.2)</span>.
          </dd></dl>
      </dd>
          <dt>
            <code>creationTime</code>
          </dt>
          <dd>A readonly representation of the time this snapshot was
        created.  The time is specified in seconds since the Epoch,
        UTC (i.e. Unix time).
      </dd>
          <dt>
            <code>state</code>
          </dt>
          <dd>A readonly representation of the state of the domain at the
        time this snapshot was taken.  If a full system snapshot was
        created, then this is the state of the domain at that
        time. When the domain is reverted to this snapshot, the
        domain's state will default to this state, unless overridden
        by <code>virDomainRevertToSnapshot()</code> flags to revert to
        a running or paused state. Additionally, this field can be the
        value "disk-snapshot" (<span class="since">since 0.9.5</span>)
        when it represents only a disk snapshot (no VM memory state),
        and reverting to this snapshot will default to an inactive
        guest.
      </dd>
          <dt>
            <code>parent</code>
          </dt>
          <dd>Readonly, present only if this snapshot has a parent. The
        parent name is given by the sub-element <code>name</code>. The
        parent relationship allows tracking a tree of related snapshots.
      </dd>
          <dt>
            <code>domain</code>
          </dt>
          <dd>A readonly representation of the domain that this snapshot
        was taken against.  Older versions of libvirt stored only a
        single child element, uuid; reverting to a snapshot like this
        is risky if the current state of the domain differs from the
        state that the domain was created in, and requires the use of
        the <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag
        in <code>virDomainRevertToSnapshot()</code>.  Newer versions
        of libvirt (<span class="since">since 0.9.5</span>) store the
        entire inactive <a href="formatdomain.html">domain
        configuration</a> at the time of the snapshot
        (<span class="since">since 0.9.5</span>). The domain will have
        security-sensitive information omitted
        unless the flag <code>VIR_DOMAIN_SNAPSHOT_XML_SECURE</code> is
        provided on a read-write connection.
      </dd>
          <dt>
            <code>cookie</code>
          </dt>
          <dd>An optional readonly representation of a save image cookie
        containing additional data libvirt may need to properly
        restore a domain from an active snapshot when such data cannot
        be stored directly in the <code>domain</code> to maintain
        compatibility with older libvirt or hypervisor.
      </dd>
        </dl>
        <h2>
          <a id="example">Examples</a>
          <a class="headerlink" href="#example" title="Permalink to this headline">¶</a>
        </h2>
        <p>Using this XML to create a disk snapshot of just vda on a qemu
      domain with two disks:</p>
        <pre>
&lt;domainsnapshot&gt;
  &lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
  &lt;disks&gt;
    &lt;disk name='vda'&gt;
      &lt;source file='/path/to/new'/&gt;
    &lt;/disk&gt;
    &lt;disk name='vdb' snapshot='no'/&gt;
    &lt;disk name='vdc'&gt;
      &lt;source file='/path/to/newc'&gt;
        &lt;seclabel model='dac' relabel='no'/&gt;
      &lt;/source&gt;
    &lt;/disk&gt;
  &lt;/disks&gt;
&lt;/domainsnapshot&gt;</pre>
        <p>will result in XML similar to this from
      <code>virDomainSnapshotGetXMLDesc()</code>:</p>
        <pre>
&lt;domainsnapshot&gt;
  &lt;name&gt;1270477159&lt;/name&gt;
  &lt;description&gt;Snapshot of OS install and updates&lt;/description&gt;
  &lt;state&gt;running&lt;/state&gt;
  &lt;creationTime&gt;1270477159&lt;/creationTime&gt;
  &lt;parent&gt;
    &lt;name&gt;bare-os-install&lt;/name&gt;
  &lt;/parent&gt;
  &lt;memory snapshot='no'/&gt;
  &lt;disks&gt;
    &lt;disk name='vda' snapshot='external'&gt;
      &lt;driver type='qcow2'/&gt;
      <b>&lt;source file='/path/to/new'/&gt;</b>
    &lt;/disk&gt;
    &lt;disk name='vdb' snapshot='no'/&gt;
  &lt;/disks&gt;
  &lt;domain&gt;
    &lt;name&gt;fedora&lt;/name&gt;
    &lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
    &lt;memory&gt;1048576&lt;/memory&gt;
    ...
    &lt;devices&gt;
      &lt;disk type='file' device='disk'&gt;
        &lt;driver name='qemu' type='raw'/&gt;
        <b>&lt;source file='/path/to/old'/&gt;</b>
        &lt;target dev='vda' bus='virtio'/&gt;
      &lt;/disk&gt;
      &lt;disk type='file' device='disk' snapshot='external'&gt;
        &lt;driver name='qemu' type='raw'/&gt;
        &lt;source file='/path/to/old2'/&gt;
        &lt;target dev='vdb' bus='virtio'/&gt;
      &lt;/disk&gt;
      ...
    &lt;/devices&gt;
  &lt;/domain&gt;
&lt;/domainsnapshot&gt;</pre>
        <p>With that snapshot created, <code>/path/to/old</code> is the
      read-only backing file to the new active
      file <code>/path/to/new</code>.  The <code>&lt;domain&gt;</code>
      element within the snapshot xml records the state of the domain
      just before the snapshot; a call
      to <code>virDomainGetXMLDesc()</code> will show that the domain
      has been changed to reflect the snapshot:
    </p>
        <pre>
&lt;domain&gt;
  &lt;name&gt;fedora&lt;/name&gt;
  &lt;uuid&gt;93a5c045-6457-2c09-e56c-927cdf34e178&lt;/uuid&gt;
  &lt;memory&gt;1048576&lt;/memory&gt;
  ...
  &lt;devices&gt;
    &lt;disk type='file' device='disk'&gt;
      &lt;driver name='qemu' type='qcow2'/&gt;
      <b>&lt;source file='/path/to/new'/&gt;</b>
      &lt;target dev='vda' bus='virtio'/&gt;
    &lt;/disk&gt;
    &lt;disk type='file' device='disk' snapshot='external'&gt;
      &lt;driver name='qemu' type='raw'/&gt;
      &lt;source file='/path/to/old2'/&gt;
      &lt;target dev='vdb' bus='virtio'/&gt;
    &lt;/disk&gt;
    ...
  &lt;/devices&gt;
&lt;/domain&gt;</pre>
      </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>