src/libvirt-domain-checkpoint.c

   1 /*
   2  * libvirt-domain-checkpoint.c: entry points for virDomainCheckpointPtr 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-checkpoint");
  27
  28 #define VIR_FROM_THIS VIR_FROM_DOMAIN_CHECKPOINT
  29
  30 /**
  31  * virDomainCheckpointGetName:
  32  * @checkpoint: a checkpoint object
  33  *
  34  * Get the public name for that checkpoint
  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 checkpoint object.
  38  *
  39  * Since: 5.6.0
  40  */
  41 const char *
  42 virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint)
  43 {
  44     VIR_DEBUG("checkpoint=%p", checkpoint);
  45
  46     virResetLastError();
  47
  48     virCheckDomainCheckpointReturn(checkpoint, NULL);
  49
  50     return checkpoint->name;
  51 }
  52
  53
  54 /**
  55  * virDomainCheckpointGetDomain:
  56  * @checkpoint: a checkpoint object
  57  *
  58  * Provides the domain pointer associated with a checkpoint.  The
  59  * reference counter on the domain is not increased by this
  60  * call.
  61  *
  62  * Returns the domain or NULL.
  63  *
  64  * Since: 5.6.0
  65  */
  66 virDomainPtr
  67 virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint)
  68 {
  69     VIR_DEBUG("checkpoint=%p", checkpoint);
  70
  71     virResetLastError();
  72
  73     virCheckDomainCheckpointReturn(checkpoint, NULL);
  74
  75     return checkpoint->domain;
  76 }
  77
  78
  79 /**
  80  * virDomainCheckpointGetConnect:
  81  * @checkpoint: a checkpoint object
  82  *
  83  * Provides the connection pointer associated with a checkpoint.  The
  84  * reference counter on the connection is not increased by this
  85  * call.
  86  *
  87  * Returns the connection or NULL.
  88  *
  89  * Since: 5.6.0
  90  */
  91 virConnectPtr
  92 virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint)
  93 {
  94     VIR_DEBUG("checkpoint=%p", checkpoint);
  95
  96     virResetLastError();
  97
  98     virCheckDomainCheckpointReturn(checkpoint, NULL);
  99
 100     return checkpoint->domain->conn;
 101 }
 102
 103
 104 /**
 105  * virDomainCheckpointCreateXML:
 106  * @domain: a domain object
 107  * @xmlDesc: description of the checkpoint to create
 108  * @flags: bitwise-OR of supported virDomainCheckpointCreateFlags
 109  *
 110  * Create a new checkpoint using @xmlDesc, with a top-level
 111  * <domaincheckpoint> element, on a running @domain.  Note that
 112  * @xmlDesc must validate against the <domaincheckpoint> XML schema.
 113  * Typically, it is more common to create a new checkpoint as part of
 114  * kicking off a backup job with virDomainBackupBegin(); however, it
 115  * is also possible to start a checkpoint without a backup.
 116  *
 117  * See https://libvirt.org/formatcheckpoint.html#checkpoint-xml
 118  * for more details on @xmlDesc. In particular, some hypervisors may require
 119  * particular disk formats, such as qcow2, in order to support this
 120  * command; where @xmlDesc can be used to limit the checkpoint to a working
 121  * subset of the domain's disks.
 122  *
 123  * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE, then this
 124  * is a request to reinstate checkpoint metadata that was previously
 125  * captured from virDomainCheckpointGetXMLDesc() before removing that
 126  * metadata, rather than creating a new checkpoint.  Note that while
 127  * original creation can omit a number of elements from @xmlDesc (and
 128  * libvirt will supply sane defaults based on the domain state at that
 129  * point in time), a redefinition must supply more elements (as the
 130  * domain may have changed in the meantime, so that libvirt no longer
 131  * has a way to resupply correct defaults).  Not all hypervisors support
 132  * this flag.
 133  *
 134  * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE_VALIDATE along with
 135  * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE the state of the metadata related
 136  * to the disk state of the redefined checkpoint is validated. Note that
 137  * hypervisors may require that the @domain is running to perform validation.
 138  *
 139  * If @flags includes VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE, then the
 140  * libvirt will attempt to use guest agent to freeze and thaw all file
 141  * systems in use within domain OS. However, if the guest agent is not
 142  * present, an error is thrown. This flag is incompatible with
 143  * VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE.
 144  *
 145  * Note: A checkpoint represents point in time after which blocks changed by
 146  * the hypervisor are tracked. The tracking of changed blocks notes only whether
 147  * a block was modified, but does not preserve the old contents.
 148  * The main purpose of checkpoints is to enable incremental backups. But for a
 149  * checkpoint to be useful for this purpose, a backup must be performed at the
 150  * same time as the checkpoint is created.
 151  * This is done via the virDomainBackupBegin API, which also allows to create a
 152  * checkpoint at the same time. Creating checkpoints with
 153  * virDomainCheckpointCreateXML is generally only useful for re-creating the
 154  * libvirt metadata.
 155  *
 156  * Returns an (opaque) new virDomainCheckpointPtr on success or NULL
 157  * on failure.
 158  *
 159  * Since: 5.6.0
 160  */
 161 virDomainCheckpointPtr
 162 virDomainCheckpointCreateXML(virDomainPtr domain,
 163                              const char *xmlDesc,
 164                              unsigned int flags)
 165 {
 166     virConnectPtr conn;
 167
 168     VIR_DOMAIN_DEBUG(domain, "xmlDesc=%s, flags=0x%x", xmlDesc, flags);
 169
 170     virResetLastError();
 171
 172     virCheckDomainReturn(domain, NULL);
 173     conn = domain->conn;
 174
 175     virCheckNonNullArgGoto(xmlDesc, error);
 176     virCheckReadOnlyGoto(conn->flags, error);
 177
 178     VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE,
 179                              VIR_DOMAIN_CHECKPOINT_CREATE_QUIESCE,
 180                              error);
 181
 182     VIR_REQUIRE_FLAG_GOTO(VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE_VALIDATE,
 183                           VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE,
 184                           error);
 185
 186     if (conn->driver->domainCheckpointCreateXML) {
 187         virDomainCheckpointPtr ret;
 188         ret = conn->driver->domainCheckpointCreateXML(domain, xmlDesc, flags);
 189         if (!ret)
 190             goto error;
 191         return ret;
 192     }
 193
 194     virReportUnsupportedError();
 195  error:
 196     virDispatchError(conn);
 197     return NULL;
 198 }
 199
 200
 201 /**
 202  * virDomainCheckpointGetXMLDesc:
 203  * @checkpoint: a domain checkpoint object
 204  * @flags: bitwise-OR of supported virDomainCheckpointXMLFlags
 205  *
 206  * Provide an XML description of the domain checkpoint.
 207  *
 208  * No security-sensitive data will be included unless @flags contains
 209  * VIR_DOMAIN_CHECKPOINT_XML_SECURE; this flag is rejected on read-only
 210  * connections.
 211  *
 212  * Normally, the XML description includes an element giving a full
 213  * description of the domain at the time the checkpoint was created; to
 214  * reduce parsing time, it will be suppressed when @flags contains
 215  * VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN.
 216  *
 217  * By default, the XML description contains only static information that
 218  * does not change over time. However, when @flags contains
 219  * VIR_DOMAIN_CHECKPOINT_XML_SIZE, each <disk> listing adds an additional
 220  * attribute that shows an estimate of the current size in bytes that
 221  * have been dirtied between the time the checkpoint was created and the
 222  * current point in time. Note that updating the size may be expensive and
 223  * data will be inaccurate once guest OS writes to the disk. Also note that
 224  * hypervisors may require that the domain associated with @checkpoint is
 225  * running when VIR_DOMAIN_CHECKPOINT_XML_SIZE is used.
 226  *
 227  * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case
 228  * of error. The caller must free() the returned value.
 229  *
 230  * Since: 5.6.0
 231  */
 232 char *
 233 virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint,
 234                               unsigned int flags)
 235 {
 236     virConnectPtr conn;
 237     VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags);
 238
 239     virResetLastError();
 240
 241     virCheckDomainCheckpointReturn(checkpoint, NULL);
 242     conn = checkpoint->domain->conn;
 243
 244     if ((conn->flags & VIR_CONNECT_RO) &&
 245         (flags & VIR_DOMAIN_CHECKPOINT_XML_SECURE)) {
 246         virReportError(VIR_ERR_OPERATION_DENIED, "%s",
 247                        _("virDomainCheckpointGetXMLDesc with secure flag"));
 248         goto error;
 249     }
 250
 251     if (conn->driver->domainCheckpointGetXMLDesc) {
 252         char *ret;
 253         ret = conn->driver->domainCheckpointGetXMLDesc(checkpoint, flags);
 254         if (!ret)
 255             goto error;
 256         return ret;
 257     }
 258
 259     virReportUnsupportedError();
 260  error:
 261     virDispatchError(conn);
 262     return NULL;
 263 }
 264
 265
 266 /**
 267  * virDomainListAllCheckpoints:
 268  * @domain: a domain object
 269  * @checkpoints: pointer to variable to store the array containing checkpoint
 270  *               object, or NULL if the list is not required (just returns
 271  *               number of checkpoints)
 272  * @flags: bitwise-OR of supported virDomainCheckpointListFlags
 273  *
 274  * Collect the list of domain checkpoints for the given domain and allocate
 275  * an array to store those objects.
 276  *
 277  * If @flags contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL,
 278  * @checkpoints is non-NULL, and no other connection is modifying
 279  * checkpoints, then it is guaranteed that for any checkpoint in the
 280  * resulting list, no checkpoints later in the list can be reached by
 281  * a sequence of virDomainCheckpointGetParent() starting from that
 282  * earlier checkpoint; otherwise, the order of checkpoints in the
 283  * resulting list is unspecified.
 284  *
 285  * By default, this command covers all checkpoints. It is also
 286  * possible to limit things to just checkpoints with no parents, when
 287  * @flags includes VIR_DOMAIN_CHECKPOINT_LIST_ROOTS.  Additional
 288  * filters are provided in groups listed below. Within a group, bits
 289  * are mutually exclusive, where all possible checkpoints are
 290  * described by exactly one bit from the group. Some hypervisors might
 291  * reject particular flags where it cannot make a distinction for
 292  * filtering. If the set of filter flags selected forms an impossible
 293  * combination, the hypervisor may return either 0 or an error.
 294  *
 295  * The first group of @flags is VIR_DOMAIN_CHECKPOINT_LIST_LEAVES and
 296  * VIR_DOMAIN_CHECKPOINT_LIST_NO_LEAVES, to filter based on checkpoints that
 297  * have no further children (a leaf checkpoint).
 298  *
 299  * Returns the number of domain checkpoints found or -1 and sets @checkpoints
 300  * to NULL in case of error.  On success, the array stored into @checkpoints
 301  * is guaranteed to have an extra allocated element set to NULL but not
 302  * included in the return count, to make iteration easier.  The caller is
 303  * responsible for calling virDomainCheckpointFree() on each array element,
 304  * then calling free() on @checkpoints.
 305  *
 306  * Since: 5.6.0
 307  */
 308 int
 309 virDomainListAllCheckpoints(virDomainPtr domain,
 310                             virDomainCheckpointPtr **checkpoints,
 311                             unsigned int flags)
 312 {
 313     virConnectPtr conn;
 314
 315     VIR_DOMAIN_DEBUG(domain, "checkpoints=%p, flags=0x%x", checkpoints, flags);
 316
 317     virResetLastError();
 318
 319     if (checkpoints)
 320         *checkpoints = NULL;
 321
 322     virCheckDomainReturn(domain, -1);
 323     conn = domain->conn;
 324
 325     if (conn->driver->domainListAllCheckpoints) {
 326         int ret = conn->driver->domainListAllCheckpoints(domain, checkpoints,
 327                                                          flags);
 328         if (ret < 0)
 329             goto error;
 330         return ret;
 331     }
 332
 333     virReportUnsupportedError();
 334  error:
 335     virDispatchError(conn);
 336     return -1;
 337 }
 338
 339
 340 /**
 341  * virDomainCheckpointListAllChildren:
 342  * @checkpoint: a domain checkpoint object
 343  * @children: pointer to variable to store the array containing checkpoint
 344  *            objects or NULL if the list is not required (just returns
 345  *            number of checkpoints)
 346  * @flags: bitwise-OR of supported virDomainCheckpointListFlags
 347  *
 348  * Collect the list of domain checkpoints that are children of the given
 349  * checkpoint, and allocate an array to store those objects.
 350  *
 351  * If @flags contains VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL,
 352  * @checkpoints is non-NULL, and no other connection is modifying
 353  * checkpoints, then it is guaranteed that for any checkpoint in the
 354  * resulting list, no checkpoints later in the list can be reached by
 355  * a sequence of virDomainCheckpointGetParent() starting from that
 356  * earlier checkpoint; otherwise, the order of checkpoints in the
 357  * resulting list is unspecified.
 358  *
 359  * By default, this command covers only direct children. It is also
 360  * possible to expand things to cover all descendants, when @flags
 361  * includes VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS.  Additional
 362  * are provided via the remaining @flags values as documented in
 363  * virDomainListAllCheckpoints(), with the exception that
 364  * VIR_DOMAIN_CHECKPOINT_LIST_ROOTS is not supported (in fact,
 365  * VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS has the same bit value but
 366  * opposite semantics of widening rather than narrowing the listing).
 367  *
 368  * Returns the number of domain checkpoints found or -1 and sets @children to
 369  * NULL in case of error.  On success, the array stored into @children is
 370  * guaranteed to have an extra allocated element set to NULL but not included
 371  * in the return count, to make iteration easier.  The caller is responsible
 372  * for calling virDomainCheckpointFree() on each array element, then calling
 373  * free() on @children.
 374  *
 375  * Since: 5.6.0
 376  */
 377 int
 378 virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint,
 379                                    virDomainCheckpointPtr **children,
 380                                    unsigned int flags)
 381 {
 382     virConnectPtr conn;
 383
 384     VIR_DEBUG("checkpoint=%p, children=%p, flags=0x%x",
 385               checkpoint, children, flags);
 386
 387     virResetLastError();
 388
 389     if (children)
 390         *children = NULL;
 391
 392     virCheckDomainCheckpointReturn(checkpoint, -1);
 393     conn = checkpoint->domain->conn;
 394
 395     if (conn->driver->domainCheckpointListAllChildren) {
 396         int ret = conn->driver->domainCheckpointListAllChildren(checkpoint,
 397                                                                 children,
 398                                                                 flags);
 399         if (ret < 0)
 400             goto error;
 401         return ret;
 402     }
 403
 404     virReportUnsupportedError();
 405  error:
 406     virDispatchError(conn);
 407     return -1;
 408 }
 409
 410
 411 /**
 412  * virDomainCheckpointLookupByName:
 413  * @domain: a domain object
 414  * @name: name for the domain checkpoint
 415  * @flags: extra flags; not used yet, so callers should always pass 0
 416  *
 417  * Try to lookup a domain checkpoint based on its name.
 418  *
 419  * Returns a domain checkpoint object or NULL in case of failure.  If the
 420  * domain checkpoint cannot be found, then the VIR_ERR_NO_DOMAIN_CHECKPOINT
 421  * error is raised.
 422  *
 423  * Since: 5.6.0
 424  */
 425 virDomainCheckpointPtr
 426 virDomainCheckpointLookupByName(virDomainPtr domain,
 427                                 const char *name,
 428                                 unsigned int flags)
 429 {
 430     virConnectPtr conn;
 431
 432     VIR_DOMAIN_DEBUG(domain, "name=%s, flags=0x%x", name, flags);
 433
 434     virResetLastError();
 435
 436     virCheckDomainReturn(domain, NULL);
 437     conn = domain->conn;
 438
 439     virCheckNonNullArgGoto(name, error);
 440
 441     if (conn->driver->domainCheckpointLookupByName) {
 442         virDomainCheckpointPtr checkpoint;
 443         checkpoint = conn->driver->domainCheckpointLookupByName(domain, name,
 444                                                                 flags);
 445         if (!checkpoint)
 446             goto error;
 447         return checkpoint;
 448     }
 449
 450     virReportUnsupportedError();
 451  error:
 452     virDispatchError(conn);
 453     return NULL;
 454 }
 455
 456
 457 /**
 458  * virDomainCheckpointGetParent:
 459  * @checkpoint: a checkpoint object
 460  * @flags: extra flags; not used yet, so callers should always pass 0
 461  *
 462  * Get the parent checkpoint for @checkpoint, if any.
 463  *
 464  * virDomainCheckpointFree should be used to free the resources after the
 465  * checkpoint object is no longer needed.
 466  *
 467  * Returns a domain checkpoint object or NULL in case of failure.  If the
 468  * given checkpoint is a root (no parent), then the VIR_ERR_NO_DOMAIN_CHECKPOINT
 469  * error is raised.
 470  *
 471  * Since: 5.6.0
 472  */
 473 virDomainCheckpointPtr
 474 virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint,
 475                              unsigned int flags)
 476 {
 477     virConnectPtr conn;
 478
 479     VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags);
 480
 481     virResetLastError();
 482
 483     virCheckDomainCheckpointReturn(checkpoint, NULL);
 484     conn = checkpoint->domain->conn;
 485
 486     if (conn->driver->domainCheckpointGetParent) {
 487         virDomainCheckpointPtr parent;
 488         parent = conn->driver->domainCheckpointGetParent(checkpoint, flags);
 489         if (!parent)
 490             goto error;
 491         return parent;
 492     }
 493
 494     virReportUnsupportedError();
 495  error:
 496     virDispatchError(conn);
 497     return NULL;
 498 }
 499
 500
 501 /**
 502  * virDomainCheckpointDelete:
 503  * @checkpoint: the checkpoint to remove
 504  * @flags: bitwise-OR of supported virDomainCheckpointDeleteFlags
 505  *
 506  * Removes a checkpoint from the domain.
 507  *
 508  * When removing a checkpoint, the record of which portions of the
 509  * disk were dirtied after the checkpoint will be merged into the
 510  * record tracked by the parent checkpoint, if any.
 511  *
 512  * If @flags includes VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN, then any
 513  * descendant checkpoints are also deleted. If @flags includes
 514  * VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY, then any descendant
 515  * checkepoints are deleted, but this checkpoint remains. These two
 516  * flags are mutually exclusive.
 517  *
 518  * If @flags includes VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY, then
 519  * any checkpoint metadata tracked by libvirt is removed while keeping
 520  * the checkpoint contents intact; if a hypervisor does not require
 521  * any libvirt metadata to track checkpoints, then this flag is
 522  * silently ignored.
 523  *
 524  * Returns 0 on success, -1 on error.
 525  *
 526  * Since: 5.6.0
 527  */
 528 int
 529 virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint,
 530                           unsigned int flags)
 531 {
 532     virConnectPtr conn;
 533
 534     VIR_DEBUG("checkpoint=%p, flags=0x%x", checkpoint, flags);
 535
 536     virResetLastError();
 537
 538     virCheckDomainCheckpointReturn(checkpoint, -1);
 539     conn = checkpoint->domain->conn;
 540
 541     virCheckReadOnlyGoto(conn->flags, error);
 542
 543     VIR_EXCLUSIVE_FLAGS_GOTO(VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN,
 544                              VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN_ONLY,
 545                              error);
 546
 547     if (conn->driver->domainCheckpointDelete) {
 548         int ret = conn->driver->domainCheckpointDelete(checkpoint, flags);
 549         if (ret < 0)
 550             goto error;
 551         return ret;
 552     }
 553
 554     virReportUnsupportedError();
 555  error:
 556     virDispatchError(conn);
 557     return -1;
 558 }
 559
 560
 561 /**
 562  * virDomainCheckpointRef:
 563  * @checkpoint: the checkpoint to hold a reference on
 564  *
 565  * Increment the reference count on the checkpoint. For each
 566  * additional call to this method, there shall be a corresponding
 567  * call to virDomainCheckpointFree to release the reference count, once
 568  * the caller no longer needs the reference to this object.
 569  *
 570  * This method is typically useful for applications where multiple
 571  * threads are using a connection, and it is required that the
 572  * connection and domain remain open until all threads have finished
 573  * using the checkpoint. ie, each new thread using a checkpoint would
 574  * increment the reference count.
 575  *
 576  * Returns 0 in case of success and -1 in case of failure.
 577  *
 578  * Since: 5.6.0
 579  */
 580 int
 581 virDomainCheckpointRef(virDomainCheckpointPtr checkpoint)
 582 {
 583     VIR_DEBUG("checkpoint=%p", checkpoint);
 584
 585     virResetLastError();
 586
 587     virCheckDomainCheckpointReturn(checkpoint, -1);
 588
 589     virObjectRef(checkpoint);
 590     return 0;
 591 }
 592
 593
 594 /**
 595  * virDomainCheckpointFree:
 596  * @checkpoint: a domain checkpoint object
 597  *
 598  * Free the domain checkpoint object.  The checkpoint itself is not modified.
 599  * The data structure is freed and should not be used thereafter.
 600  *
 601  * Returns 0 in case of success and -1 in case of failure.
 602  *
 603  * Since: 5.6.0
 604  */
 605 int
 606 virDomainCheckpointFree(virDomainCheckpointPtr checkpoint)
 607 {
 608     VIR_DEBUG("checkpoint=%p", checkpoint);
 609
 610     virResetLastError();
 611
 612     virCheckDomainCheckpointReturn(checkpoint, -1);
 613
 614     virObjectUnref(checkpoint);
 615     return 0;
 616 }