1 /*
2 * libvirt-domain-snapshot.c: entry points for virDomainSnapshotPtr APIs
3 *
4 * Copyright (C) 2006-2019 Red Hat, Inc.
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library. If not, see
18 * <http://www.gnu.org/licenses/>.
19 */
20
21 #include <config.h>
22
23 #include "datatypes.h"
24 #include "virlog.h"
25
26 VIR_LOG_INIT("libvirt.domain-snapshot");
27
28 #define VIR_FROM_THIS VIR_FROM_DOMAIN_SNAPSHOT
29
30 /**
31 * virDomainSnapshotGetName:
32 * @snapshot: a snapshot object
33 *
34 * Get the public name for that snapshot
35 *
36 * Returns a pointer to the name or NULL, the string need not be deallocated
37 * as its lifetime will be the same as the snapshot object.
38 */
39 const char *
virDomainSnapshotGetName(virDomainSnapshotPtr snapshot)40 virDomainSnapshotGetName(virDomainSnapshotPtr snapshot)
41 {
42 VIR_DEBUG("snapshot=%p", snapshot);
43
44 virResetLastError();
45
46 virCheckDomainSnapshotReturn(snapshot, NULL);
47
48 return snapshot->name;
49 }
50
51
52 /**
53 * virDomainSnapshotGetDomain:
54 * @snapshot: a snapshot object
55 *
56 * Provides the domain pointer associated with a snapshot. The
57 * reference counter on the domain is not increased by this
58 * call.
59 *
60 * Returns the domain or NULL.
61 */
62 virDomainPtr
virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)63 virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot)
64 {
65 VIR_DEBUG("snapshot=%p", snapshot);
66
67 virResetLastError();
68
69 virCheckDomainSnapshotReturn(snapshot, NULL);
70
71 return snapshot->domain;
72 }
73
74
75 /**
76 * virDomainSnapshotGetConnect:
77 * @snapshot: a snapshot object
78 *
79 * Provides the connection pointer associated with a snapshot. The
80 * reference counter on the connection is not increased by this
81 * call.
82 *
83 * Returns the connection or NULL.
84 */
85 virConnectPtr
virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)86 virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
87 {
88 VIR_DEBUG("snapshot=%p", snapshot);
89
90 virResetLastError();
91
92 virCheckDomainSnapshotReturn(snapshot, NULL);
93
94 return snapshot->domain->conn;
95 }
96
97
98 /**
99 * virDomainSnapshotCreateXML:
100 * @domain: a domain object
101 * @xmlDesc: string containing an XML description of the domain snapshot
102 * @flags: bitwise-OR of virDomainSnapshotCreateFlags
103 *
104 * Creates a new snapshot of a domain based on the snapshot xml
105 * contained in xmlDesc, with a top-level element <domainsnapshot>.
106 *
107 * If @flags is 0, the domain can be active, in which case the
108 * snapshot will be a full system snapshot (capturing both disk state,
109 * and runtime VM state such as RAM contents), where reverting to the
110 * snapshot is
111 * the same as resuming from hibernation (TCP connections may have
112 * timed out, but everything else picks up where it left off); or
113 * the domain can be inactive, in which case the snapshot includes
114 * just the disk state prior to booting. The newly created snapshot
115 * becomes current (see virDomainSnapshotCurrent()), and is a child
116 * of any previous current snapshot.
117 *
118 * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_VALIDATE, then @xmlDesc
119 * is validated against the <domainsnapshot> XML schema.
120 *
121 * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE, then this
122 * is a request to reinstate snapshot metadata that was previously
123 * captured from virDomainSnapshotGetXMLDesc() before removing that
124 * metadata, rather than creating a new snapshot. This can be used to
125 * recreate a snapshot hierarchy on a destination, then remove it on
126 * the source, in order to allow migration (since migration normally
127 * fails if snapshot metadata still remains on the source machine).
128 * Note that while original creation can omit a number of elements
129 * from @xmlDesc (and libvirt will supply sane defaults based on the
130 * domain state at that point in time), a redefinition must supply
131 * more elements (as the domain may have changed in the meantime, so
132 * that libvirt no longer has a way to resupply correct
133 * defaults). When redefining snapshot metadata, the domain's current
134 * snapshot will not be altered unless the
135 * VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag is also present. It is an
136 * error to request the VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT flag
137 * without VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE. On some hypervisors,
138 * redefining an existing snapshot can be used to alter host-specific
139 * portions of the domain XML to be used during revert (such as
140 * backing filenames associated with disk devices), but must not alter
141 * guest-visible layout. When redefining a snapshot name that does
142 * not exist, the hypervisor may validate that reverting to the
143 * snapshot appears to be possible (for example, disk images have
144 * snapshot contents by the requested name). Not all hypervisors
145 * support these flags.
146 *
147 * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA, then the
148 * domain's disk images are modified according to @xmlDesc, but
149 * libvirt does not track any metadata (similar to immediately calling
150 * virDomainSnapshotDelete() with
151 * VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY). This flag is
152 * incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE.
153 *
154 * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_HALT, then the domain
155 * will be inactive after the snapshot completes, regardless of whether
156 * it was active before; otherwise, a running domain will still be
157 * running after the snapshot. This flag is invalid on transient domains,
158 * and is incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE.
159 *
160 * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_LIVE, then the domain
161 * is not paused while creating the snapshot. This increases the size
162 * of the memory dump file, but reduces downtime of the guest while
163 * taking the snapshot. Some hypervisors only support this flag during
164 * external snapshots.
165 *
166 * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY, then the
167 * snapshot will be limited to the disks described in @xmlDesc, and no
168 * VM state will be saved. For an active guest, the disk image may be
169 * inconsistent (as if power had been pulled), and specifying this
170 * with the VIR_DOMAIN_SNAPSHOT_CREATE_HALT flag risks data loss.
171 *
172 * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE, then the
173 * libvirt will attempt to use guest agent to freeze and thaw all
174 * file systems in use within domain OS. However, if the guest agent
175 * is not present, an error is thrown. Moreover, this flag requires
176 * VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY to be passed as well.
177 * For better control and error recovery users should invoke virDomainFSFreeze
178 * manually before taking the snapshot and then virDomainFSThaw to restore the
179 * VM rather than using VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE.
180 *
181 * By default, if the snapshot involves external files, and any of the
182 * destination files already exist as a non-empty regular file, the
183 * snapshot is rejected to avoid losing contents of those files.
184 * However, if @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT,
185 * then the destination files must be pre-created manually with
186 * the correct image format and metadata including backing store path
187 * (this allows a management app to pre-create files with relative backing
188 * file names, rather than the default of creating with absolute backing
189 * file names). Note that only the file specified in the snapshot XML is
190 * inserted as a snapshot thus setting incorrect metadata in the pre-created
191 * image may lead to the VM being unable to start or other block jobs may fail.
192 *
193 * Be aware that although libvirt prefers to report errors up front with
194 * no other effect, some hypervisors have certain types of failures where
195 * the overall command can easily fail even though the guest configuration
196 * was partially altered (for example, if a disk snapshot request for two
197 * disks fails on the second disk, but the first disk alteration cannot be
198 * rolled back). If this API call fails, it is therefore normally
199 * necessary to follow up with virDomainGetXMLDesc() and check each disk
200 * to determine if any partial changes occurred. However, if @flags
201 * contains VIR_DOMAIN_SNAPSHOT_CREATE_ATOMIC, then libvirt guarantees
202 * that this command will not alter any disks unless the entire set of
203 * changes can be done atomically, making failure recovery simpler (note
204 * that it is still possible to fail after disks have changed, but only
205 * in the much rarer cases of running out of memory or disk space).
206 *
207 * Some hypervisors may prevent this operation if there is a current
208 * block copy operation; in that case, use virDomainBlockJobAbort()
209 * to stop the block copy first.
210 *
211 * virDomainSnapshotFree should be used to free the resources after the
212 * snapshot object is no longer needed.
213 *
214 * Returns an (opaque) new virDomainSnapshotPtr on success or NULL on
215 * failure.
216 */
217 virDomainSnapshotPtr
virDomainSnapshotCreateXML(virDomainPtr domain,const char * xmlDesc,unsigned int flags)218 virDomainSnapshotCreateXML(virDomainPtr domain,
219 const char *xmlDesc,
220 unsigned int flags)
221 {
222 virConnectPtr conn;
223
224 VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=0x%x", xmlDesc, flags);
225
226 virResetLastError();
227
228 virCheckDomainReturn(domain, NULL);
229 conn = domain->conn;
230
231 virCheckNonNullArgGoto(xmlDesc, error);
232 virCheckReadOnlyGoto(conn->flags, error);
233
234 VIR_REQUIRE_FLAG_GOTO(VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT,
235 VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE,
236 error);
237
238 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE,
239 VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA,
240 error);
241 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE,
242 VIR_DOMAIN_SNAPSHOT_CREATE_HALT,
243 error);
244
245 if (conn->driver->domainSnapshotCreateXML) {
246 virDomainSnapshotPtr ret;
247 ret = conn->driver->domainSnapshotCreateXML(domain, xmlDesc, flags);
248 if (!ret)
249 goto error;
250 return ret;
251 }
252
253 virReportUnsupportedError();
254 error:
255 virDispatchError(conn);
256 return NULL;
257 }
258
259
260 /**
261 * virDomainSnapshotGetXMLDesc:
262 * @snapshot: a domain snapshot object
263 * @flags: bitwise-OR of supported virDomainSnapshotXMLFlags
264 *
265 * Provide an XML description of the domain snapshot, with a top-level
266 * element of <domainsnapshot>.
267 *
268 * No security-sensitive data will be included unless @flags contains
269 * VIR_DOMAIN_SNAPSHOT_XML_SECURE; this flag is rejected on read-only
270 * connections.
271 *
272 * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
273 * of error. The caller must free() the returned value.
274 */
275 char *
virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,unsigned int flags)276 virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
277 unsigned int flags)
278 {
279 virConnectPtr conn;
280 VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
281
282 virResetLastError();
283
284 virCheckDomainSnapshotReturn(snapshot, NULL);
285 conn = snapshot->domain->conn;
286
287 if ((conn->flags & VIR_CONNECT_RO) &&
288 (flags & VIR_DOMAIN_SNAPSHOT_XML_SECURE)) {
289 virReportError(VIR_ERR_OPERATION_DENIED, "%s",
290 _("virDomainSnapshotGetXMLDesc with secure flag"));
291 goto error;
292 }
293
294 if (conn->driver->domainSnapshotGetXMLDesc) {
295 char *ret;
296 ret = conn->driver->domainSnapshotGetXMLDesc(snapshot, flags);
297 if (!ret)
298 goto error;
299 return ret;
300 }
301
302 virReportUnsupportedError();
303 error:
304 virDispatchError(conn);
305 return NULL;
306 }
307
308
309 /**
310 * virDomainSnapshotNum:
311 * @domain: a domain object
312 * @flags: bitwise-OR of supported virDomainSnapshotListFlags
313 *
314 * Provides the number of domain snapshots for this domain.
315 *
316 * This function will accept VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL in
317 * @flags only if virDomainSnapshotListNames() can honor it, although
318 * the flag has no other effect here.
319 *
320 * By default, this command covers all snapshots. It is also possible
321 * to limit things to just snapshots with no parents, when @flags
322 * includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are
323 * provided via the same @flags values as documented in
324 * virDomainListAllSnapshots().
325 *
326 * Returns the number of domain snapshots found or -1 in case of error.
327 */
328 int
virDomainSnapshotNum(virDomainPtr domain,unsigned int flags)329 virDomainSnapshotNum(virDomainPtr domain, unsigned int flags)
330 {
331 virConnectPtr conn;
332
333 VIR_DOMAIN_DEBUG(domain, "flags=0x%x", flags);
334
335 virResetLastError();
336
337 virCheckDomainReturn(domain, -1);
338
339 conn = domain->conn;
340 if (conn->driver->domainSnapshotNum) {
341 int ret = conn->driver->domainSnapshotNum(domain, flags);
342 if (ret < 0)
343 goto error;
344 return ret;
345 }
346
347 virReportUnsupportedError();
348 error:
349 virDispatchError(conn);
350 return -1;
351 }
352
353
354 /**
355 * virDomainSnapshotListNames:
356 * @domain: a domain object
357 * @names: array to collect the list of names of snapshots
358 * @nameslen: size of @names
359 * @flags: bitwise-OR of supported virDomainSnapshotListFlags
360 *
361 * Collect the list of domain snapshots for the given domain, and store
362 * their names in @names. The value to use for @nameslen can be determined
363 * by virDomainSnapshotNum() with the same @flags.
364 *
365 * If @flags contains VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL, and no
366 * other connection is modifying snapshots, then it is guaranteed that
367 * for any snapshot in the resulting list, no snapshots later in the
368 * list can be reached by a sequence of virDomainSnapshotGetParent()
369 * starting from that earlier snapshot; otherwise, the order of
370 * snapshots in the resulting list is unspecified.
371 *
372 * By default, this command covers all snapshots. It is also possible
373 * to limit things to just snapshots with no parents, when @flags
374 * includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are
375 * provided via the same @flags values as documented in
376 * virDomainListAllSnapshots().
377 *
378 * Note that this command is inherently racy: another connection can
379 * define a new snapshot between a call to virDomainSnapshotNum() and
380 * this call. You are only guaranteed that all currently defined
381 * snapshots were listed if the return is less than @nameslen. Likewise,
382 * you should be prepared for virDomainSnapshotLookupByName() to fail when
383 * converting a name from this call into a snapshot object, if another
384 * connection deletes the snapshot in the meantime.
385 *
386 * The use of this function is discouraged. Instead, use
387 * virDomainListAllSnapshots().
388 *
389 * Returns the number of domain snapshots found or -1 in case of error.
390 * The caller is responsible to call free() for each member of the array.
391 */
392 int
virDomainSnapshotListNames(virDomainPtr domain,char ** names,int nameslen,unsigned int flags)393 virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen,
394 unsigned int flags)
395 {
396 virConnectPtr conn;
397
398 VIR_DOMAIN_DEBUG(domain, "names=%p, nameslen=%d, flags=0x%x",
399 names, nameslen, flags);
400
401 virResetLastError();
402
403 virCheckDomainReturn(domain, -1);
404 conn = domain->conn;
405
406 virCheckNonNullArrayArgGoto(names, nameslen, error);
407 virCheckNonNegativeArgGoto(nameslen, error);
408
409 if (conn->driver->domainSnapshotListNames) {
410 int ret = conn->driver->domainSnapshotListNames(domain, names,
411 nameslen, flags);
412 if (ret < 0)
413 goto error;
414 return ret;
415 }
416
417 virReportUnsupportedError();
418 error:
419 virDispatchError(conn);
420 return -1;
421 }
422
423
424 /**
425 * virDomainListAllSnapshots:
426 * @domain: a domain object
427 * @snaps: pointer to variable to store the array containing snapshot objects
428 * or NULL if the list is not required (just returns number of
429 * snapshots)
430 * @flags: bitwise-OR of supported virDomainSnapshotListFlags
431 *
432 * Collect the list of domain snapshots for the given domain and allocate
433 * an array to store those objects. This API solves the race inherent in
434 * virDomainSnapshotListNames().
435 *
436 * If @flags contains VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL and @snaps
437 * is non-NULL, and no other connection is modifying snapshots, then
438 * it is guaranteed that for any snapshot in the resulting list, no
439 * snapshots later in the list can be reached by a sequence of
440 * virDomainSnapshotGetParent() starting from that earlier snapshot;
441 * otherwise, the order of snapshots in the resulting list is
442 * unspecified.
443 *
444 * By default, this command covers all snapshots. It is also possible
445 * to limit things to just snapshots with no parents, when @flags
446 * includes VIR_DOMAIN_SNAPSHOT_LIST_ROOTS. Additional filters are
447 * provided in groups listed below. Within a group, bits are mutually
448 * exclusive, where all possible snapshots are described by exactly
449 * one bit from the group. Some hypervisors might reject particular
450 * flags where it cannot make a distinction for filtering. If the set
451 * of filter flags selected forms an impossible combination, the
452 * hypervisor may return either 0 or an error.
453 *
454 * The first group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_LEAVES and
455 * VIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES, to filter based on snapshots that
456 * have no further children (a leaf snapshot).
457 *
458 * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_METADATA and
459 * VIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA, for filtering snapshots based on
460 * whether they have metadata that would prevent the removal of the last
461 * reference to a domain.
462 *
463 * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INACTIVE,
464 * VIR_DOMAIN_SNAPSHOT_LIST_ACTIVE, and VIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY,
465 * for filtering snapshots based on what domain state is tracked by the
466 * snapshot.
467 *
468 * The next group of @flags is VIR_DOMAIN_SNAPSHOT_LIST_INTERNAL and
469 * VIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL, for filtering snapshots based on
470 * whether the snapshot is stored inside the disk images or as
471 * additional files.
472 *
473 * Returns the number of domain snapshots found or -1 and sets @snaps to
474 * NULL in case of error. On success, the array stored into @snaps is
475 * guaranteed to have an extra allocated element set to NULL but not included
476 * in the return count, to make iteration easier. The caller is responsible
477 * for calling virDomainSnapshotFree() on each array element, then calling
478 * free() on @snaps.
479 */
480 int
virDomainListAllSnapshots(virDomainPtr domain,virDomainSnapshotPtr ** snaps,unsigned int flags)481 virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps,
482 unsigned int flags)
483 {
484 virConnectPtr conn;
485
486 VIR_DOMAIN_DEBUG(domain, "snaps=%p, flags=0x%x", snaps, flags);
487
488 virResetLastError();
489
490 if (snaps)
491 *snaps = NULL;
492
493 virCheckDomainReturn(domain, -1);
494 conn = domain->conn;
495
496 if (conn->driver->domainListAllSnapshots) {
497 int ret = conn->driver->domainListAllSnapshots(domain, snaps, flags);
498 if (ret < 0)
499 goto error;
500 return ret;
501 }
502
503 virReportUnsupportedError();
504 error:
505 virDispatchError(conn);
506 return -1;
507 }
508
509
510 /**
511 * virDomainSnapshotNumChildren:
512 * @snapshot: a domain snapshot object
513 * @flags: bitwise-OR of supported virDomainSnapshotListFlags
514 *
515 * Provides the number of child snapshots for this domain snapshot.
516 *
517 * This function will accept VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL in
518 * @flags only if virDomainSnapshotListChildrenNames() can honor it,
519 * although the flag has no other effect here.
520 *
521 * By default, this command covers only direct children. It is also
522 * possible to expand things to cover all descendants, when @flags
523 * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
524 * are provided via the same @flags values as documented in
525 * virDomainSnapshotListAllChildren().
526 *
527 * Returns the number of domain snapshots found or -1 in case of error.
528 */
529 int
virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot,unsigned int flags)530 virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags)
531 {
532 virConnectPtr conn;
533
534 VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
535
536 virResetLastError();
537
538 virCheckDomainSnapshotReturn(snapshot, -1);
539 conn = snapshot->domain->conn;
540
541 if (conn->driver->domainSnapshotNumChildren) {
542 int ret = conn->driver->domainSnapshotNumChildren(snapshot, flags);
543 if (ret < 0)
544 goto error;
545 return ret;
546 }
547
548 virReportUnsupportedError();
549 error:
550 virDispatchError(conn);
551 return -1;
552 }
553
554
555 /**
556 * virDomainSnapshotListChildrenNames:
557 * @snapshot: a domain snapshot object
558 * @names: array to collect the list of names of snapshots
559 * @nameslen: size of @names
560 * @flags: bitwise-OR of supported virDomainSnapshotListFlags
561 *
562 * Collect the list of domain snapshots that are children of the given
563 * snapshot, and store their names in @names. The value to use for
564 * @nameslen can be determined by virDomainSnapshotNumChildren() with
565 * the same @flags.
566 *
567 * If @flags lacks VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS or contains
568 * VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL, and no other connection is
569 * modifying snapshots, then it is guaranteed that for any snapshot in
570 * the resulting list, no snapshots later in the list can be reached
571 * by a sequence of virDomainSnapshotGetParent() starting from that
572 * earlier snapshot; otherwise, the order of snapshots in the
573 * resulting list is unspecified.
574 *
575 * By default, this command covers only direct children. It is also
576 * possible to expand things to cover all descendants, when @flags
577 * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
578 * are provided via the same @flags values as documented in
579 * virDomainSnapshotListAllChildren().
580 *
581 * Note that this command is inherently racy: another connection can
582 * define a new snapshot between a call to virDomainSnapshotNumChildren()
583 * and this call. You are only guaranteed that all currently defined
584 * snapshots were listed if the return is less than @nameslen. Likewise,
585 * you should be prepared for virDomainSnapshotLookupByName() to fail when
586 * converting a name from this call into a snapshot object, if another
587 * connection deletes the snapshot in the meantime.
588 *
589 * The use of this function is discouraged. Instead, use
590 * virDomainSnapshotListAllChildren().
591 *
592 * Returns the number of domain snapshots found or -1 in case of error.
593 * The caller is responsible to call free() for each member of the array.
594 */
595 int
virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,char ** names,int nameslen,unsigned int flags)596 virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot,
597 char **names, int nameslen,
598 unsigned int flags)
599 {
600 virConnectPtr conn;
601
602 VIR_DEBUG("snapshot=%p, names=%p, nameslen=%d, flags=0x%x",
603 snapshot, names, nameslen, flags);
604
605 virResetLastError();
606
607 virCheckDomainSnapshotReturn(snapshot, -1);
608 conn = snapshot->domain->conn;
609
610 virCheckNonNullArrayArgGoto(names, nameslen, error);
611 virCheckNonNegativeArgGoto(nameslen, error);
612
613 if (conn->driver->domainSnapshotListChildrenNames) {
614 int ret = conn->driver->domainSnapshotListChildrenNames(snapshot,
615 names,
616 nameslen,
617 flags);
618 if (ret < 0)
619 goto error;
620 return ret;
621 }
622
623 virReportUnsupportedError();
624 error:
625 virDispatchError(conn);
626 return -1;
627 }
628
629
630 /**
631 * virDomainSnapshotListAllChildren:
632 * @snapshot: a domain snapshot object
633 * @snaps: pointer to variable to store the array containing snapshot objects
634 * or NULL if the list is not required (just returns number of
635 * snapshots)
636 * @flags: bitwise-OR of supported virDomainSnapshotListFlags
637 *
638 * Collect the list of domain snapshots that are children of the given
639 * snapshot, and allocate an array to store those objects. This API solves
640 * the race inherent in virDomainSnapshotListChildrenNames().
641 *
642 * If @flags lacks VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS or contains
643 * VIR_DOMAIN_SNAPSHOT_LIST_TOPOLOGICAL, @snaps is non-NULL, and no
644 * other connection is modifying snapshots, then it is guaranteed that
645 * for any snapshot in the resulting list, no snapshots later in the
646 * list can be reached by a sequence of virDomainSnapshotGetParent()
647 * starting from that earlier snapshot; otherwise, the order of
648 * snapshots in the resulting list is unspecified.
649 *
650 * By default, this command covers only direct children. It is also
651 * possible to expand things to cover all descendants, when @flags
652 * includes VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS. Additional filters
653 * are provided via the remaining @flags values as documented in
654 * virDomainListAllSnapshots(), with the exception that
655 * VIR_DOMAIN_SNAPSHOT_LIST_ROOTS is not supported (in fact,
656 * VIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS has the same bit value but
657 * opposite semantics of widening rather than narrowing the listing).
658 *
659 * Returns the number of domain snapshots found or -1 and sets @snaps to
660 * NULL in case of error. On success, the array stored into @snaps is
661 * guaranteed to have an extra allocated element set to NULL but not included
662 * in the return count, to make iteration easier. The caller is responsible
663 * for calling virDomainSnapshotFree() on each array element, then calling
664 * free() on @snaps.
665 */
666 int
virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot,virDomainSnapshotPtr ** snaps,unsigned int flags)667 virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot,
668 virDomainSnapshotPtr **snaps,
669 unsigned int flags)
670 {
671 virConnectPtr conn;
672
673 VIR_DEBUG("snapshot=%p, snaps=%p, flags=0x%x", snapshot, snaps, flags);
674
675 virResetLastError();
676
677 if (snaps)
678 *snaps = NULL;
679
680 virCheckDomainSnapshotReturn(snapshot, -1);
681 conn = snapshot->domain->conn;
682
683 if (conn->driver->domainSnapshotListAllChildren) {
684 int ret = conn->driver->domainSnapshotListAllChildren(snapshot, snaps,
685 flags);
686 if (ret < 0)
687 goto error;
688 return ret;
689 }
690
691 virReportUnsupportedError();
692 error:
693 virDispatchError(conn);
694 return -1;
695 }
696
697
698 /**
699 * virDomainSnapshotLookupByName:
700 * @domain: a domain object
701 * @name: name for the domain snapshot
702 * @flags: extra flags; not used yet, so callers should always pass 0
703 *
704 * Try to lookup a domain snapshot based on its name.
705 *
706 * Returns a domain snapshot object or NULL in case of failure. If the
707 * domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
708 * error is raised.
709 */
710 virDomainSnapshotPtr
virDomainSnapshotLookupByName(virDomainPtr domain,const char * name,unsigned int flags)711 virDomainSnapshotLookupByName(virDomainPtr domain,
712 const char *name,
713 unsigned int flags)
714 {
715 virConnectPtr conn;
716
717 VIR_DOMAIN_DEBUG(domain, "name=%s, flags=0x%x", name, flags);
718
719 virResetLastError();
720
721 virCheckDomainReturn(domain, NULL);
722 conn = domain->conn;
723
724 virCheckNonNullArgGoto(name, error);
725
726 if (conn->driver->domainSnapshotLookupByName) {
727 virDomainSnapshotPtr dom;
728 dom = conn->driver->domainSnapshotLookupByName(domain, name, flags);
729 if (!dom)
730 goto error;
731 return dom;
732 }
733
734 virReportUnsupportedError();
735 error:
736 virDispatchError(conn);
737 return NULL;
738 }
739
740
741 /**
742 * virDomainHasCurrentSnapshot:
743 * @domain: pointer to the domain object
744 * @flags: extra flags; not used yet, so callers should always pass 0
745 *
746 * Determine if the domain has a current snapshot.
747 *
748 * Returns 1 if such snapshot exists, 0 if it doesn't, -1 on error.
749 */
750 int
virDomainHasCurrentSnapshot(virDomainPtr domain,unsigned int flags)751 virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags)
752 {
753 virConnectPtr conn;
754
755 VIR_DOMAIN_DEBUG(domain, "flags=0x%x", flags);
756
757 virResetLastError();
758
759 virCheckDomainReturn(domain, -1);
760 conn = domain->conn;
761
762 if (conn->driver->domainHasCurrentSnapshot) {
763 int ret = conn->driver->domainHasCurrentSnapshot(domain, flags);
764 if (ret < 0)
765 goto error;
766 return ret;
767 }
768
769 virReportUnsupportedError();
770 error:
771 virDispatchError(conn);
772 return -1;
773 }
774
775
776 /**
777 * virDomainSnapshotCurrent:
778 * @domain: a domain object
779 * @flags: extra flags; not used yet, so callers should always pass 0
780 *
781 * Get the current snapshot for a domain, if any.
782 *
783 * virDomainSnapshotFree should be used to free the resources after the
784 * snapshot object is no longer needed.
785 *
786 * Returns a domain snapshot object or NULL in case of failure. If the
787 * current domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT
788 * error is raised.
789 */
790 virDomainSnapshotPtr
virDomainSnapshotCurrent(virDomainPtr domain,unsigned int flags)791 virDomainSnapshotCurrent(virDomainPtr domain,
792 unsigned int flags)
793 {
794 virConnectPtr conn;
795
796 VIR_DOMAIN_DEBUG(domain, "flags=0x%x", flags);
797
798 virResetLastError();
799
800 virCheckDomainReturn(domain, NULL);
801 conn = domain->conn;
802
803 if (conn->driver->domainSnapshotCurrent) {
804 virDomainSnapshotPtr snap;
805 snap = conn->driver->domainSnapshotCurrent(domain, flags);
806 if (!snap)
807 goto error;
808 return snap;
809 }
810
811 virReportUnsupportedError();
812 error:
813 virDispatchError(conn);
814 return NULL;
815 }
816
817
818 /**
819 * virDomainSnapshotGetParent:
820 * @snapshot: a snapshot object
821 * @flags: extra flags; not used yet, so callers should always pass 0
822 *
823 * Get the parent snapshot for @snapshot, if any.
824 *
825 * virDomainSnapshotFree should be used to free the resources after the
826 * snapshot object is no longer needed.
827 *
828 * Returns a domain snapshot object or NULL in case of failure. If the
829 * given snapshot is a root (no parent), then the VIR_ERR_NO_DOMAIN_SNAPSHOT
830 * error is raised.
831 */
832 virDomainSnapshotPtr
virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot,unsigned int flags)833 virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot,
834 unsigned int flags)
835 {
836 virConnectPtr conn;
837
838 VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
839
840 virResetLastError();
841
842 virCheckDomainSnapshotReturn(snapshot, NULL);
843 conn = snapshot->domain->conn;
844
845 if (conn->driver->domainSnapshotGetParent) {
846 virDomainSnapshotPtr snap;
847 snap = conn->driver->domainSnapshotGetParent(snapshot, flags);
848 if (!snap)
849 goto error;
850 return snap;
851 }
852
853 virReportUnsupportedError();
854 error:
855 virDispatchError(conn);
856 return NULL;
857 }
858
859
860 /**
861 * virDomainSnapshotIsCurrent:
862 * @snapshot: a snapshot object
863 * @flags: extra flags; not used yet, so callers should always pass 0
864 *
865 * Determine if the given snapshot is the domain's current snapshot. See
866 * also virDomainHasCurrentSnapshot().
867 *
868 * Returns 1 if current, 0 if not current, or -1 on error.
869 */
870 int
virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot,unsigned int flags)871 virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot,
872 unsigned int flags)
873 {
874 virConnectPtr conn;
875
876 VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
877
878 virResetLastError();
879
880 virCheckDomainSnapshotReturn(snapshot, -1);
881 conn = snapshot->domain->conn;
882
883 if (conn->driver->domainSnapshotIsCurrent) {
884 int ret;
885 ret = conn->driver->domainSnapshotIsCurrent(snapshot, flags);
886 if (ret < 0)
887 goto error;
888 return ret;
889 }
890
891 virReportUnsupportedError();
892 error:
893 virDispatchError(conn);
894 return -1;
895 }
896
897
898 /**
899 * virDomainSnapshotHasMetadata:
900 * @snapshot: a snapshot object
901 * @flags: extra flags; not used yet, so callers should always pass 0
902 *
903 * Determine if the given snapshot is associated with libvirt metadata
904 * that would prevent the deletion of the domain.
905 *
906 * Returns 1 if the snapshot has metadata, 0 if the snapshot exists without
907 * help from libvirt, or -1 on error.
908 */
909 int
virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot,unsigned int flags)910 virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot,
911 unsigned int flags)
912 {
913 virConnectPtr conn;
914
915 VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
916
917 virResetLastError();
918
919 virCheckDomainSnapshotReturn(snapshot, -1);
920 conn = snapshot->domain->conn;
921
922 if (conn->driver->domainSnapshotHasMetadata) {
923 int ret;
924 ret = conn->driver->domainSnapshotHasMetadata(snapshot, flags);
925 if (ret < 0)
926 goto error;
927 return ret;
928 }
929
930 virReportUnsupportedError();
931 error:
932 virDispatchError(conn);
933 return -1;
934 }
935
936
937 /**
938 * virDomainRevertToSnapshot:
939 * @snapshot: a domain snapshot object
940 * @flags: bitwise-OR of virDomainSnapshotRevertFlags
941 *
942 * Revert the domain to a given snapshot.
943 *
944 * Normally, the domain will revert to the same state the domain was
945 * in while the snapshot was taken (whether inactive, running, or
946 * paused), except that disk snapshots default to reverting to
947 * inactive state. Including VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING in
948 * @flags overrides the snapshot state to guarantee a running domain
949 * after the revert; or including VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED in
950 * @flags guarantees a paused domain after the revert. These two
951 * flags are mutually exclusive. While a persistent domain does not
952 * need either flag, it is not possible to revert a transient domain
953 * into an inactive state, so transient domains require the use of one
954 * of these two flags.
955 *
956 * Reverting to any snapshot discards all configuration changes made since
957 * the last snapshot. Additionally, reverting to a snapshot from a running
958 * domain is a form of data loss, since it discards whatever is in the
959 * guest's RAM at the time. Since the very nature of keeping snapshots
960 * implies the intent to roll back state, no additional confirmation is
961 * normally required for these lossy effects.
962 *
963 * Since libvirt 7.10.0 the VM process is always restarted so the following
964 * paragraph is no longer valid. If the snapshot metadata lacks the full
965 * VM XML it's no longer possible to revert to such snapshot.
966 *
967 * However, there are two particular situations where reverting will
968 * be refused by default, and where @flags must include
969 * VIR_DOMAIN_SNAPSHOT_REVERT_FORCE to acknowledge the risks. 1) Any
970 * attempt to revert to a snapshot that lacks the metadata to perform
971 * ABI compatibility checks (generally the case for snapshots that
972 * lack a full <domain> when listed by virDomainSnapshotGetXMLDesc(),
973 * such as those created prior to libvirt 0.9.5). 2) Any attempt to
974 * revert a running domain to an active state that requires starting a
975 * new hypervisor instance rather than reusing the existing hypervisor
976 * (since this would terminate all connections to the domain, such as
977 * such as VNC or Spice graphics) - this condition arises from active
978 * snapshots that are provably ABI incompatible, as well as from
979 * inactive snapshots with a @flags request to start the domain after
980 * the revert.
981 *
982 * Returns 0 if the creation is successful, -1 on error.
983 */
984 int
virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,unsigned int flags)985 virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot,
986 unsigned int flags)
987 {
988 virConnectPtr conn;
989
990 VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
991
992 virResetLastError();
993
994 virCheckDomainSnapshotReturn(snapshot, -1);
995 conn = snapshot->domain->conn;
996
997 virCheckReadOnlyGoto(conn->flags, error);
998
999 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING,
1000 VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED,
1001 error);
1002
1003 if (conn->driver->domainRevertToSnapshot) {
1004 int ret = conn->driver->domainRevertToSnapshot(snapshot, flags);
1005 if (ret < 0)
1006 goto error;
1007 return ret;
1008 }
1009
1010 virReportUnsupportedError();
1011 error:
1012 virDispatchError(conn);
1013 return -1;
1014 }
1015
1016
1017 /**
1018 * virDomainSnapshotDelete:
1019 * @snapshot: a domain snapshot object
1020 * @flags: bitwise-OR of supported virDomainSnapshotDeleteFlags
1021 *
1022 * Delete the snapshot.
1023 *
1024 * If @flags is 0, then just this snapshot is deleted, and changes
1025 * from this snapshot are automatically merged into children
1026 * snapshots. If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN,
1027 * then this snapshot and any descendant snapshots are deleted. If
1028 * @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY, then any
1029 * descendant snapshots are deleted, but this snapshot remains. These
1030 * two flags are mutually exclusive.
1031 *
1032 * If @flags includes VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY, then
1033 * any snapshot metadata tracked by libvirt is removed while keeping
1034 * the snapshot contents intact; if a hypervisor does not require any
1035 * libvirt metadata to track snapshots, then this flag is silently
1036 * ignored.
1037 *
1038 * Returns 0 if the selected snapshot(s) were successfully deleted,
1039 * -1 on error.
1040 */
1041 int
virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,unsigned int flags)1042 virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
1043 unsigned int flags)
1044 {
1045 virConnectPtr conn;
1046
1047 VIR_DEBUG("snapshot=%p, flags=0x%x", snapshot, flags);
1048
1049 virResetLastError();
1050
1051 virCheckDomainSnapshotReturn(snapshot, -1);
1052 conn = snapshot->domain->conn;
1053
1054 virCheckReadOnlyGoto(conn->flags, error);
1055
1056 VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN,
1057 VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY,
1058 error);
1059
1060 if (conn->driver->domainSnapshotDelete) {
1061 int ret = conn->driver->domainSnapshotDelete(snapshot, flags);
1062 if (ret < 0)
1063 goto error;
1064 return ret;
1065 }
1066
1067 virReportUnsupportedError();
1068 error:
1069 virDispatchError(conn);
1070 return -1;
1071 }
1072
1073
1074 /**
1075 * virDomainSnapshotRef:
1076 * @snapshot: the snapshot to hold a reference on
1077 *
1078 * Increment the reference count on the snapshot. For each
1079 * additional call to this method, there shall be a corresponding
1080 * call to virDomainSnapshotFree to release the reference count, once
1081 * the caller no longer needs the reference to this object.
1082 *
1083 * This method is typically useful for applications where multiple
1084 * threads are using a connection, and it is required that the
1085 * connection and domain remain open until all threads have finished
1086 * using the snapshot. ie, each new thread using a snapshot would
1087 * increment the reference count.
1088 *
1089 * Returns 0 in case of success and -1 in case of failure.
1090 */
1091 int
virDomainSnapshotRef(virDomainSnapshotPtr snapshot)1092 virDomainSnapshotRef(virDomainSnapshotPtr snapshot)
1093 {
1094 VIR_DEBUG("snapshot=%p", snapshot);
1095
1096 virResetLastError();
1097
1098 virCheckDomainSnapshotReturn(snapshot, -1);
1099
1100 virObjectRef(snapshot);
1101 return 0;
1102 }
1103
1104
1105 /**
1106 * virDomainSnapshotFree:
1107 * @snapshot: a domain snapshot object
1108 *
1109 * Free the domain snapshot object. The snapshot itself is not modified.
1110 * The data structure is freed and should not be used thereafter.
1111 *
1112 * Returns 0 in case of success and -1 in case of failure.
1113 */
1114 int
virDomainSnapshotFree(virDomainSnapshotPtr snapshot)1115 virDomainSnapshotFree(virDomainSnapshotPtr snapshot)
1116 {
1117 VIR_DEBUG("snapshot=%p", snapshot);
1118
1119 virResetLastError();
1120
1121 virCheckDomainSnapshotReturn(snapshot, -1);
1122
1123 virObjectUnref(snapshot);
1124 return 0;
1125 }
1126