Re: [PATCH v8 12/21] backup: Implement virsh support for checkpoints

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Wed, Apr 17, 2019 at 09:09:12 -0500, Eric Blake wrote:
> Introduce a bunch of new virsh commands for managing checkpoints
> in isolation. More commands are needed for performing incremental
> backups, but these commands were easy to implement by modeling
> heavily after virsh-snapshot.c (no need for checkpoint-revert,
> and checkpoint-list was a lot easier since we don't have to cater
> to older libvirt API).
> 
> Signed-off-by: Eric Blake <eblake@xxxxxxxxxx>
> ---
>  tools/virsh-checkpoint.h     |   29 +
>  tools/virsh-completer.h      |    4 +
>  tools/virsh-util.h           |    3 +
>  tools/virsh.h                |    1 +
>  po/POTFILES                  |    1 +
>  tools/Makefile.am            |    1 +
>  tools/virsh-checkpoint.c     | 1370 ++++++++++++++++++++++++++++++++++
>  tools/virsh-completer.c      |   51 ++
>  tools/virsh-domain-monitor.c |   23 +
>  tools/virsh-domain.c         |   15 +
>  tools/virsh-util.c           |   11 +
>  tools/virsh.c                |    2 +
>  tools/virsh.pod              |  238 +++++-
>  13 files changed, 1742 insertions(+), 7 deletions(-)
>  create mode 100644 tools/virsh-checkpoint.h
>  create mode 100644 tools/virsh-checkpoint.c

[...]

> diff --git a/tools/virsh-checkpoint.c b/tools/virsh-checkpoint.c
> new file mode 100644
> index 0000000000..3089383dc5
> --- /dev/null
> +++ b/tools/virsh-checkpoint.c
> @@ -0,0 +1,1370 @@
> +/*
> + * virsh-checkpoint.c: Commands to manage domain checkpoints
> + *
> + * Copyright (C) 2005-2019 Red Hat, Inc.
> + *
> + * This library is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU Lesser General Public
> + * License as published by the Free Software Foundation; either
> + * version 2.1 of the License, or (at your option) any later version.
> + *
> + * This library is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> + * Lesser General Public License for more details.
> + *
> + * You should have received a copy of the GNU Lesser General Public
> + * License along with this library.  If not, see
> + * <http://www.gnu.org/licenses/>.
> + *
> + *  Daniel Veillard <veillard@xxxxxxxxxx>
> + *  Karel Zak <kzak@xxxxxxxxxx>
> + *  Daniel P. Berrange <berrange@xxxxxxxxxx>
> + *
> + */
> +
> +#include <config.h>
> +#include "virsh-checkpoint.h"
> +
> +#include <assert.h>
> +
> +#include <libxml/parser.h>
> +#include <libxml/tree.h>
> +#include <libxml/xpath.h>
> +#include <libxml/xmlsave.h>
> +
> +#include "internal.h"
> +#include "virbuffer.h"
> +#include "viralloc.h"
> +#include "virfile.h"
> +#include "virsh-util.h"
> +#include "virstring.h"
> +#include "virxml.h"
> +#include "conf/checkpoint_conf.h"
> +
> +/* Helper for checkpoint-create and checkpoint-create-as */
> +static bool
> +virshCheckpointCreate(vshControl *ctl,
> +                      virDomainPtr dom,
> +                      const char *buffer,
> +                      unsigned int flags,
> +                      const char *from)
> +{
> +    bool ret = false;
> +    virDomainCheckpointPtr checkpoint;
> +    const char *name = NULL;
> +
> +    checkpoint = virDomainCheckpointCreateXML(dom, buffer, flags);
> +
> +    if (checkpoint == NULL)
> +        goto cleanup;
> +
> +    name = virDomainCheckpointGetName(checkpoint);
> +    if (!name) {
> +        vshError(ctl, "%s", _("Could not get snapshot name"));

Some copypaste leftovers.

> +        goto cleanup;
> +    }
> +
> +    if (from)
> +        vshPrintExtra(ctl, _("Domain checkpoint %s created from '%s'"),
> +                      name, from);
> +    else
> +        vshPrintExtra(ctl, _("Domain checkpoint %s created"), name);
> +
> +    ret = true;
> +
> + cleanup:
> +    virshDomainCheckpointFree(checkpoint);
> +    return ret;
> +}
> +
> +
> +/*

[...]

> +
> +static bool
> +cmdCheckpointCreate(vshControl *ctl,
> +                    const vshCmd *cmd)
> +{
> +    virDomainPtr dom = NULL;
> +    bool ret = false;
> +    const char *from = NULL;
> +    char *buffer = NULL;
> +    unsigned int flags = 0;
> +
> +    if (vshCommandOptBool(cmd, "redefine"))
> +        flags |= VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE;
> +    if (vshCommandOptBool(cmd, "current"))
> +        flags |= VIR_DOMAIN_CHECKPOINT_CREATE_CURRENT;
> +    if (vshCommandOptBool(cmd, "no-metadata"))
> +        flags |= VIR_DOMAIN_CHECKPOINT_CREATE_NO_METADATA;
> +    if (vshCommandOptBool(cmd, "quiesce"))
> +        flags |= VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE;

leftovers

> +
> +    if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
> +        goto cleanup;
> +
> +    if (vshCommandOptStringReq(ctl, cmd, "xmlfile", &from) < 0)
> +        goto cleanup;
> +    if (!from) {
> +        buffer = vshStrdup(ctl, "<domaincheckpoint/>");
> +    } else {
> +        if (virFileReadAll(from, VSH_MAX_XML_FILE, &buffer) < 0) {
> +            vshSaveLibvirtError();
> +            goto cleanup;
> +        }
> +    }
> +
> +    ret = virshCheckpointCreate(ctl, dom, buffer, flags, from);
> +
> + cleanup:
> +    VIR_FREE(buffer);
> +    virshDomainFree(dom);
> +
> +    return ret;
> +}
> +
> +

[...]

> +/* Helper for resolving {--current | --ARG name} into a checkpoint
> + * belonging to DOM.  If EXCLUSIVE, fail if both --current and arg are
> + * present.  On success, populate *CHK and *NAME, before returning 0.
> + * On failure, return -1 after issuing an error message.  */
> +static int
> +virshLookupCheckpoint(vshControl *ctl,
> +                      const vshCmd *cmd,
> +                      const char *arg,
> +                      bool exclusive,
> +                      virDomainPtr dom,
> +                      virDomainCheckpointPtr *chk,
> +                      const char **name)
> +{
> +    bool current = vshCommandOptBool(cmd, "current");
> +    const char *chkname = NULL;
> +
> +    if (vshCommandOptStringReq(ctl, cmd, arg, &chkname) < 0)
> +        return -1;
> +
> +    if (exclusive && current && chkname) {
> +        vshError(ctl, _("--%s and --current are mutually exclusive"), arg);
> +        return -1;
> +    }
> +
> +    if (chkname) {
> +        *chk = virDomainCheckpointLookupByName(dom, chkname, 0);
> +    } else if (current) {
> +        *chk = virDomainCheckpointCurrent(dom, 0);
> +    } else {
> +        vshError(ctl, _("--%s or --current is required"), arg);
> +        return -1;
> +    }
> +    if (!*chk) {
> +        vshReportError(ctl);
> +        return -1;
> +    }
> +
> +    *name = virDomainCheckpointGetName(*chk);
> +    return 0;
> +}
> +
> +
> +/*
> + * "checkpoint-edit" command
> + */
> +static const vshCmdInfo info_checkpoint_edit[] = {
> +    {.name = "help",
> +     .data = N_("edit XML for a checkpoint")
> +    },
> +    {.name = "desc",
> +     .data = N_("Edit the domain checkpoint XML for a named checkpoint")
> +    },
> +    {.name = NULL}
> +};
> +
> +static const vshCmdOptDef opts_checkpoint_edit[] = {
> +    VIRSH_COMMON_OPT_DOMAIN_FULL(0),
> +    {.name = "checkpointname",
> +     .type = VSH_OT_STRING,
> +     .help = N_("checkpoint name"),
> +     .completer = virshCheckpointNameCompleter,
> +    },
> +    VIRSH_COMMON_OPT_CURRENT(N_("also set edited checkpoint as current")),
> +    {.name = "rename",
> +     .type = VSH_OT_BOOL,
> +     .help = N_("allow renaming an existing checkpoint")
> +    },
> +    {.name = "clone",
> +     .type = VSH_OT_BOOL,
> +     .help = N_("allow cloning to new name")
> +    },
> +    {.name = NULL}
> +};

[...]

> +
> +
> +/*
> + * "checkpoint-current" command
> + */
> +static const vshCmdInfo info_checkpoint_current[] = {
> +    {.name = "help",
> +     .data = N_("Get or set the current checkpoint")

Set?!? I see we do that with snapshots, but that's pure insanity.

It uses redefine to set the snapshot as current? But that defeats the
purpose of the 'current' snapshot/checkpoint since it does not change
the underlying state.

I don't think we should copy this.


> +    },
> +    {.name = "desc",
> +     .data = N_("Get or set the current checkpoint")
> +    },
> +    {.name = NULL}
> +};

[...]

> +/* Helper function to get the name of a checkpoint's parent.  Caller
> + * must free the result.  Returns 0 on success (including when it was
> + * proven no parent exists), and -1 on failure with error reported
> + * (such as no checkpoint support or domain deleted in meantime).  */
> +static int
> +virshGetCheckpointParent(vshControl *ctl,
> +                         virDomainCheckpointPtr checkpoint,
> +                         char **parent_name)
> +{
> +    virDomainCheckpointPtr parent = NULL;
> +    int ret = -1;
> +
> +    *parent_name = NULL;
> +
> +    parent = virDomainCheckpointGetParent(checkpoint, 0);
> +    if (parent) {
> +        /* API works, and virDomainCheckpointGetName will succeed */

There's no option when the API would not work. Only when it isn't
supported, but then you have other problems.

> +        *parent_name = vshStrdup(ctl, virDomainCheckpointGetName(parent));
> +        ret = 0;
> +    } else if (last_error->code == VIR_ERR_NO_DOMAIN_CHECKPOINT) {
> +        /* API works, and we found a root with no parent */
> +        ret = 0;
> +    }
> +
> +    if (ret < 0) {
> +        vshReportError(ctl);
> +        vshError(ctl, "%s", _("unable to determine if checkpoint has parent"));
> +    } else {
> +        vshResetLibvirtError();
> +    }
> +    virshDomainCheckpointFree(parent);
> +    return ret;
> +}
> +
> +
> +/*
> + * "checkpoint-info" command
> + */
> +static const vshCmdInfo info_checkpoint_info[] = {
> +    {.name = "help",
> +     .data = N_("checkpoint information")
> +    },
> +    {.name = "desc",
> +     .data = N_("Returns basic information about a checkpoint.")
> +    },
> +    {.name = NULL}
> +};
> +
> +static const vshCmdOptDef opts_checkpoint_info[] = {
> +    VIRSH_COMMON_OPT_DOMAIN_FULL(0),
> +    {.name = "checkpointname",
> +     .type = VSH_OT_STRING,
> +     .help = N_("checkpoint name"),
> +     .completer = virshCheckpointNameCompleter,
> +    },
> +    VIRSH_COMMON_OPT_CURRENT(N_("info on current checkpoint")),
> +    {.name = NULL}
> +};
> +
> +
> +static bool
> +cmdCheckpointInfo(vshControl *ctl,
> +                  const vshCmd *cmd)
> +{
> +    virDomainPtr dom;
> +    virDomainCheckpointPtr checkpoint = NULL;
> +    const char *name;
> +    char *parent = NULL;
> +    bool ret = false;
> +    int count;
> +    unsigned int flags;
> +    int current;
> +    int metadata;
> +
> +    dom = virshCommandOptDomain(ctl, cmd, NULL);
> +    if (dom == NULL)
> +        return false;
> +
> +    if (virshLookupCheckpoint(ctl, cmd, "checkpointname", true, dom,
> +                              &checkpoint, &name) < 0)
> +        goto cleanup;
> +
> +    vshPrint(ctl, "%-15s %s\n", _("Name:"), name);
> +    vshPrint(ctl, "%-15s %s\n", _("Domain:"), virDomainGetName(dom));
> +
> +    /* Determine if checkpoint is current.  */
> +    current = virDomainCheckpointIsCurrent(checkpoint, 0);
> +    if (current < 0) {
> +        vshError(ctl, "%s",
> +                 _("unexpected problem querying checkpoint state"));
> +        goto cleanup;
> +    }
> +    vshPrint(ctl, "%-15s %s\n", _("Current:"),
> +             current > 0 ? _("yes") : _("no"));
> +
> +    if (virshGetCheckpointParent(ctl, checkpoint, &parent) < 0) {
> +        vshError(ctl, "%s",
> +                 _("unexpected problem querying checkpoint state"));

virshGetCheckpointParent already reports errors

> +        goto cleanup;
> +    }
> +    vshPrint(ctl, "%-15s %s\n", _("Parent:"), parent ? parent : "-");
> +
> +    /* Children, Descendants.  */
> +    flags = 0;
> +    count = virDomainCheckpointListAllChildren(checkpoint, NULL, flags);
> +    if (count < 0) {
> +        if (last_error->code == VIR_ERR_NO_SUPPORT) {
> +            vshResetLibvirtError();

Other calls are fatal.

> +            ret = true;
> +        }
> +        goto cleanup;
> +    }
> +    vshPrint(ctl, "%-15s %d\n", _("Children:"), count);
> +    flags = VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS;
> +    count = virDomainCheckpointListAllChildren(checkpoint, NULL, flags);
> +    if (count < 0)
> +        goto cleanup;
> +    vshPrint(ctl, "%-15s %d\n", _("Descendants:"), count);
> +
> +    /* Metadata.  */
> +    metadata = virDomainCheckpointHasMetadata(checkpoint, 0);
> +    if (metadata >= 0)
> +        vshPrint(ctl, "%-15s %s\n", _("Metadata:"),
> +                 metadata ? _("yes") : _("no"));

This should be probably dropped altogether. I don't see a reason to have
metadata-less checkpoints.

> +
> +    ret = true;
> +
> + cleanup:
> +    VIR_FREE(parent);
> +    virshDomainCheckpointFree(checkpoint);
> +    virshDomainFree(dom);
> +    return ret;
> +}


[...]


> +    if (vshCommandOptBool(cmd, "topological"))
> +        flags |= VIR_DOMAIN_CHECKPOINT_LIST_TOPOLOGICAL;
> +
> +    if (roots)
> +        flags |= VIR_DOMAIN_CHECKPOINT_LIST_ROOTS;
> +
> +    if (vshCommandOptBool(cmd, "metadata"))
> +        flags |= VIR_DOMAIN_CHECKPOINT_LIST_METADATA;
> +
> +    if (vshCommandOptBool(cmd, "no-metadata"))
> +        flags |= VIR_DOMAIN_CHECKPOINT_LIST_NO_METADATA;
> +
> +    if (vshCommandOptBool(cmd, "descendants")) {
> +        if (!from && !current) {
> +            vshError(ctl, "%s",
> +                     _("--descendants requires either --from or --current"));
> +            return false;
> +        }
> +        flags |= VIR_DOMAIN_CHECKPOINT_LIST_DESCENDANTS;
> +    }
> +
> +    if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
> +        return false;
> +
> +    if ((from || current) &&
> +        virshLookupCheckpoint(ctl, cmd, "from", true, dom, &start, &from_chk) < 0)
> +        goto cleanup;
> +
> +    if (!(chklist = virshCheckpointListCollect(ctl, dom, start, flags, tree)))
> +        goto cleanup;
> +
> +    if (!tree && !name) {
> +        if (parent)
> +            vshPrintExtra(ctl, " %-20s %-25s %s",
> +                          _("Name"), _("Creation Time"), _("Parent"));
> +        else
> +            vshPrintExtra(ctl, " %-20s %-25s",
> +                          _("Name"), _("Creation Time"));
> +        vshPrintExtra(ctl, "\n"
> +                           "------------------------------"
> +                           "--------------\n");

We don't do manual tables for some time now.

> +    }
> +
> +    if (tree) {
> +        for (i = 0; i < chklist->nchks; i++) {
> +            if (!chklist->chks[i].parent &&
> +                vshTreePrint(ctl, virshCheckpointListLookup, chklist,
> +                             chklist->nchks, i) < 0)
> +                goto cleanup;
> +        }
> +        ret = true;
> +        goto cleanup;
> +    }
> +
> +    for (i = 0; i < chklist->nchks; i++) {
> +        const char *chk_name;
> +
> +        /* free up memory from previous iterations of the loop */
> +        VIR_FREE(parent_chk);
> +        xmlXPathFreeContext(ctxt);
> +        xmlFreeDoc(xml);
> +        VIR_FREE(doc);
> +
> +        checkpoint = chklist->chks[i].chk;
> +        chk_name = virDomainCheckpointGetName(checkpoint);
> +        assert(chk_name);
> +
> +        if (name) {
> +            /* just print the checkpoint name */
> +            vshPrint(ctl, "%s\n", chk_name);
> +            continue;
> +        }
> +
> +        if (!(doc = virDomainCheckpointGetXMLDesc(checkpoint, 0)))
> +            continue;
> +
> +        if (!(xml = virXMLParseStringCtxt(doc, _("(domain_checkpoint)"), &ctxt)))
> +            continue;
> +
> +        if (parent)
> +            parent_chk = virXPathString("string(/domaincheckpoint/parent/name)",
> +                                        ctxt);
> +
> +        if (virXPathLongLong("string(/domaincheckpoint/creationTime)", ctxt,
> +                             &creation_longlong) < 0)
> +            continue;
> +        creation_time_t = creation_longlong;
> +        if (creation_time_t != creation_longlong) {
> +            vshError(ctl, "%s", _("time_t overflow"));
> +            continue;
> +        }
> +        localtime_r(&creation_time_t, &time_info);
> +        strftime(timestr, sizeof(timestr), "%Y-%m-%d %H:%M:%S %z",
> +                 &time_info);
> +
> +        if (parent)
> +            vshPrint(ctl, " %-20s %-25s %s\n",
> +                     chk_name, timestr, parent_chk ?: "-");
> +        else
> +            vshPrint(ctl, " %-20s %-25s\n", chk_name, timestr);
> +    }
> +
> +    ret = true;
> +
> + cleanup:
> +    /* this frees up memory from the last iteration of the loop */
> +    virshCheckpointListFree(chklist);
> +    VIR_FREE(parent_chk);
> +    virshDomainCheckpointFree(start);
> +    xmlXPathFreeContext(ctxt);
> +    xmlFreeDoc(xml);
> +    VIR_FREE(doc);
> +    virshDomainFree(dom);
> +
> +    return ret;
> +}
> +
[...]

> diff --git a/tools/virsh-domain-monitor.c b/tools/virsh-domain-monitor.c
> index d87475f6f6..59f3d7e6d9 100644
> --- a/tools/virsh-domain-monitor.c
> +++ b/tools/virsh-domain-monitor.c

[...]

> @@ -1782,6 +1783,17 @@ virshDomainListCollect(vshControl *ctl, unsigned int flags)
>                  goto remove_entry;
>          }

We could make the checkpoint flags mandatory if the driver supports
checkpoints.

> +        /* checkpoint filter */
> +        if (VSH_MATCH(VIR_CONNECT_LIST_DOMAINS_FILTERS_CHECKPOINT)) {
> +            if ((nchk = virDomainListAllCheckpoints(dom, NULL, 0)) < 0) {
> +                vshError(ctl, "%s", _("Failed to get checkpoint count"));
> +                goto cleanup;
> +            }
> +            if (!((VSH_MATCH(VIR_CONNECT_LIST_DOMAINS_HAS_CHECKPOINT) && nchk > 0) ||
> +                  (VSH_MATCH(VIR_CONNECT_LIST_DOMAINS_NO_CHECKPOINT) && nchk == 0)))
> +                goto remove_entry;
> +        }
> +
>          /* the domain matched all filters, it may stay */
>          continue;
> 

[...]


> diff --git a/tools/virsh.pod b/tools/virsh.pod
> index afc1684db0..064a0a2fa3 100644
> --- a/tools/virsh.pod
> +++ b/tools/virsh.pod
> @@ -409,6 +409,7 @@ Inject NMI to the guest.
>                [I<--with-managed-save>] [I<--without-managed-save>]
>                [I<--autostart>] [I<--no-autostart>]
>                [I<--with-snapshot>] [I<--without-snapshot>]
> +              [I<--with-checkpoint>] [I<--without-checkpoint>]
>                [I<--state-running>] [I<--state-paused>]
>                [I<--state-shutoff>] [I<--state-other>]
> 
> @@ -514,6 +515,11 @@ this feature disabled use I<--no-autostart>.
>  Domains that have snapshot images can be listed using flag I<--with-snapshot>,
>  domains without a snapshot I<--without-snapshot>.
> 
> +=item B<Checkpoint existence>
> +
> +Domains that have checkpoints can be listed using flag I<--with-checkpoint>,
> +domains without a checkpoint I<--without-checkpoint>.
> +
>  =back
> 
>  When talking to older servers, this command is forced to use a series of API
> @@ -809,7 +815,8 @@ can be restarted later.
>  If I<domain> is transient, then the metadata of any snapshots will
>  be lost once the guest stops running, but the snapshot contents still
>  exist, and a new domain with the same name and UUID can restore the
> -snapshot metadata with B<snapshot-create>.
> +snapshot metadata with B<snapshot-create>.  Similarly, the metadata of
> +any checkpoints will be lost, but can be restored with B<checkpoint-create>.
> 
>  If I<--graceful> is specified, don't resort to extreme measures
>  (e.g. SIGKILL) when the guest doesn't stop after a reasonable timeout;
> @@ -1570,7 +1577,7 @@ Convert a domain Id (or UUID) to domain name
>  Rename a domain. This command changes current domain name to the new name
>  specified in the second argument.
> 
> -B<Note>: Domain must be inactive and without snapshots.
> +B<Note>: Domain must be inactive and without snapshots or checkpoints.
> 
>  =item B<domstate> I<domain> [I<--reason>]
> 
> @@ -2811,10 +2818,11 @@ services must be shutdown in the domain.
>  The exact behavior of a domain when it shuts down is set by the
>  I<on_poweroff> parameter in the domain's XML definition.
> 
> -If I<domain> is transient, then the metadata of any snapshots will
> -be lost once the guest stops running, but the snapshot contents still
> -exist, and a new domain with the same name and UUID can restore the
> -snapshot metadata with B<snapshot-create>.
> +If I<domain> is transient, then the metadata of any snapshots and
> +checkpoints will be lost once the guest stops running, but the underlying
> +contents still exist, and a new domain with the same name and UUID can
> +restore the snapshot metadata with B<snapshot-create>, and the checkpoint
> +metadata with B<checkpoint-create>.
> 
>  By default the hypervisor will try to pick a suitable shutdown
>  method. To specify an alternative method, the I<--mode> parameter
> @@ -2891,7 +2899,7 @@ Output the device used for the TTY console of the domain. If the information
>  is not available the processes will provide an exit code of 1.
> 
>  =item B<undefine> I<domain> [I<--managed-save>] [I<--snapshots-metadata>]
> -[I<--nvram>] [I<--keep-nvram>]
> +[I<--checkpoints-metadata>] [I<--nvram>] [I<--keep-nvram>]
>  [ {I<--storage> B<volumes> | I<--remove-all-storage> [I<--delete-snapshots>]}
>  I<--wipe-storage>]
> 
> @@ -2909,6 +2917,12 @@ domain.  Without the flag, attempts to undefine an inactive domain with
>  snapshot metadata will fail.  If the domain is active, this flag is
>  ignored.
> 
> +The I<--checkpoints-metadata> flag guarantees that any checkpoints (see the
> +B<checkpoint-list> command) are also cleaned up when undefining an inactive
> +domain.  Without the flag, attempts to undefine an inactive domain with
> +checkpoint metadata will fail.  If the domain is active, this flag is
> +ignored.
> +
>  I<--nvram> and I<--keep-nvram> specify accordingly to delete or keep nvram
>  (/domain/os/nvram/) file. If the domain has an nvram file and the flags are
>  omitted, the undefine will fail.
> @@ -4876,6 +4890,216 @@ the data contents from that point in time.
> 
>  =back
> 
> +=head1 CHECKPOINT COMMANDS
> +
> +The following commands manipulate domain checkpoints.  Checkpoints serve as
> +a point in time to identify which portions of a guest's disks have changed
> +after that time, making it possible to perform incremental and differential
> +backups.  Checkpoints are identified with a unique name.  See
> +L<https://libvirt.org/formatcheckpoint.html> for documentation of the XML
> +format used to represent properties of checkpoints.
> +
> +=over 4
> +
> +=item B<checkpoint-create> I<domain> [I<xmlfile>] {[I<--redefine>
> +{[I<--current>] | [I<--redefine-list>]}] | [I<--no-metadata>] [I<--quiesce>]}
> +
> +Create a checkpoint for domain I<domain> with the properties specified
> +in I<xmlfile> describing a <domaincheckpoint> top-level element. If
> +I<xmlfile> is completely omitted, then libvirt will create a
> +checkpoint with a name based on the current time. The new checkpoint
> +will become current, as listed by B<checkpoint-current>.
> +
> +If I<--redefine> is specified, then all XML elements produced by
> +B<checkpoint-dumpxml> are valid; this can be used to migrate
> +checkpoint hierarchy from one machine to another, to recreate
> +hierarchy for the case of a transient domain that goes away and is
> +later recreated with the same name and UUID, or to make slight
> +alterations in the checkpoint metadata (such as host-specific aspects
> +of the domain XML embedded in the checkpoint).  When this flag is
> +supplied, the I<xmlfile> argument is mandatory, and the domain's
> +current snapshot will not be altered unless the I<--current> flag is
> +also given.  If I<--redefine-list> is specified, I<--redefine> is
> +implied, I<--current> is rejected, and the XML changes from being a
> +single <domaincheckpoint> to instead being a <checkpoints> element
> +describing a list of checkpoints. List form only works if the domain
> +has no currently-defined checkpoint metadata, and can be obtained as a
> +subset of I<dumpxml --checkpoints> output.
> +
> +If I<--no-metadata> is specified, then the checkpoint data is created,
> +but any metadata is immediately discarded (that is, libvirt does not
> +treat the checkpoint as current, and cannot use the checkpoint for an
> +incremental backup unless I<--redefine> is later used to teach libvirt
> +about the metadata again).
> +
> +If I<--quiesce> is specified, libvirt will try to use guest agent
> +to freeze and unfreeze domain's mounted file systems. However,
> +if domain has no guest agent, checkpoint creation will fail.
> +
> +Existence of checkpoint metadata will prevent attempts to B<undefine>
> +a persistent domain.  However, for transient domains, checkpoint
> +metadata is silently lost when the domain quits running (whether
> +by command such as B<destroy> or by internal guest action).
> +
> +=item B<checkpoint-create-as> I<domain> {[I<--print-xml>]
> +| [I<--no-metadata>]} [I<name>] [I<description>] [I<--quiesce>]
> +[I<--diskspec>] B<diskspec>]...
> +
> +Create a checkpoint for domain I<domain> with the given <name> and
> +<description>; if either value is omitted, libvirt will choose a
> +value.  If I<--print-xml> is specified, then XML appropriate for
> +I<checkpoint-create> is output, rather than actually creating a
> +checkpoint.
> +
> +The I<--diskspec> option can be used to control which guest disks participate in the checkpoint. This option can occur
> +multiple times, according to the number of <disk> elements in the domain
> +xml.  Each <diskspec> is in the
> +form B<disk[,checkpoint=type][,bitmap=name]>. A literal I<--diskspec> must precede each B<diskspec> unless
> +all three of I<domain>, I<name>, and I<description> are also present.
> +For example, a diskspec of "vda,checkpoint=bitmap,bitmap=map1"
> +results in the following XML:
> +  <disk name='vda' checkpoint='bitmap' bitmap='map1'/>
> +
> +If I<--quiesce> is specified, libvirt will try to use guest agent
> +to freeze and unfreeze domain's mounted file systems. However,
> +if domain has no guest agent, checkpoint creation will fail.
> +
> +If I<--no-metadata> is specified, then the checkpoint data is created,
> +but any metadata is immediately discarded (that is, libvirt does not
> +treat the checkpoint as current, and cannot use the checkpoint for an
> +incremental backup unless I<--redefine> is later used to teach libvirt
> +about the metadata again).
> +
> +=item B<checkpoint-current> I<domain> {[I<--name>] | [I<--security-info>]
> +[I<--no-domain>] [I<--size>] | [I<checkpointname>]}
> +
> +Without I<checkpointname>, this will output the checkpoint XML for the
> +domain's current checkpoint (if any).  If I<--name> is specified,
> +output just the current checkpoint name instead of the full xml.
> +Otherwise, using I<--security-info> will also include security
> +sensitive information in the XML, using I<--size> will add XML
> +indicating roughly how much guest data has changed since the
> +checkpoint was created, and using I<--no-domain> will omit the
> +<domain> element from the output for a more compact view.
> +
> +With I<checkpointname>, this is a request to make the existing named
> +checkpoint become the current checkpoint.
> +
> +=item B<checkpoint-edit> I<domain> [I<checkpointname>] [I<--current>]
> +{[I<--rename>] | [I<--clone>]}
> +
> +Edit the XML configuration file for I<checkpointname> of a domain.  If
> +both I<checkpointname> and I<--current> are specified, also force the
> +edited checkpoint to become the current snapshot.  If
> +I<checkpointname> is omitted, then I<--current> must be supplied, to
> +edit the current checkpoint.
> +
> +This is equivalent to:
> +
> + virsh checkpoint-dumpxml dom name > checkpoint.xml
> + vi checkpoint.xml (or make changes with your other text editor)
> + virsh checkpoint-create dom checkpoint.xml --redefine [--current]
> +
> +except that it does some error checking.
> +
> +The editor used can be supplied by the C<$VISUAL> or C<$EDITOR> environment
> +variables, and defaults to C<vi>.
> +
> +If I<--rename> is specified, then the edits can change the checkpoint
> +name.  If I<--clone> is specified, then changing the snapshot name
> +will create a clone of the checkpoint metadata.  If neither is
> +specified, then the edits must not change the checkpoint name.  Note
> +that changing a checkpoint name must be done with care, since some
> +drivers may require the original checkpoint name for actually
> +accessing changes since a point in time.
> +
> +=item B<checkpoint-info> I<domain> {I<checkpoint> | I<--current>}
> +
> +Output basic information about a named <checkpoint>, or the current
> +checkpoint with I<--current>.
> +
> +=item B<checkpoint-list> I<domain> [I<--metadata>] [I<--no-metadata>]
> +[{I<--parent> | I<--roots> | [{I<--tree> | I<--name>}]}] [I<--topological>]
> +[{[I<--from>] B<checkpoint> | I<--current>} [I<--descendants>]]
> +[I<--leaves>] [I<--no-leaves>]
> +
> +List all of the available checkpoints for the given domain, defaulting
> +to show columns for the checkpoint name and creation time.
> +
> +Normally, table form output is sorted by checkpoint name; using
> +I<--topological> instead sorts so that no child is listed before its
> +ancestors (although there may be more than one possible ordering with
> +this property).
> +
> +If I<--parent> is specified, add a column to the output table giving
> +the name of the parent of each checkpoint.  If I<--roots> is
> +specified, the list will be filtered to just checkpoints that have no
> +parents.  If I<--tree> is specified, the output will be in a tree
> +format, listing just checkpoint names.  These three options are
> +mutually exclusive. If I<--name> is specified only the checkpoint name
> +is printed. This option is mutually exclusive with I<--tree>.
> +
> +If I<--from> is provided, filter the list to checkpoints which are
> +children of the given B<checkpoint>; or if I<--current> is provided,
> +start at the current checkpoint.  When used in isolation or with
> +I<--parent>, the list is limited to direct children unless
> +I<--descendants> is also present.  When used with I<--tree>, the use
> +of I<--descendants> is implied.  This option is not compatible with
> +I<--roots>.  Note that the starting point of I<--from> or I<--current>
> +is not included in the list unless the I<--tree> option is also
> +present.
> +
> +If I<--leaves> is specified, the list will be filtered to just
> +checkpoints that have no children.  Likewise, if I<--no-leaves> is
> +specified, the list will be filtered to just checkpoints with
> +children.  (Note that omitting both options does no filtering, while
> +providing both options will either produce the same list or error out
> +depending on whether the server recognizes the flags).  Filtering
> +options are not compatible with I<--tree>.
> +
> +If I<--metadata> is specified, the list will be filtered to just
> +checkpoints that involve libvirt metadata, and thus would prevent
> +B<undefine> of a persistent domain, or be lost on B<destroy> of a
> +transient domain.  Likewise, if I<--no-metadata> is specified, the
> +list will be filtered to just checkpoints that exist without the need
> +for libvirt metadata.

Hmmm. This actually reminds me that we should forbid checkpoints without
metadata. It's a dead-end also with snapshots.

> +
> +=item B<checkpoint-dumpxml> I<domain> I<snapshot> [I<--security-info>]
> +[I<--no-domain>] [I<--size>]
> +
> +Output the snapshot XML for the domain's checkpoint named
> +I<checkpoint>.  Using I<--security-info> will also include security
> +sensitive information, using I<--size> will add XML indicating roughly
> +how much guest data has changed since the checkpoint was created, and
> +using I<--no-domain> will omit the <domain> element from the output
> +for a more compact view.  Use B<checkpoint-current> to easily access
> +the XML of the current snapshot.  To grab the XML for all checkpoints
> +at once, use B<dumpxml --checkpoints>.
> +
> +=item B<checkpoint-parent> I<domain> {I<checkpoint> | I<--current>}
> +
> +Output the name of the parent checkpoint, if any, for the given
> +I<checkpoint>, or for the current checkpoint with I<--current>.
> +
> +=item B<checkpoint-delete> I<domain> {I<checkpoint> | I<--current>}
> +[I<--metadata>] [{I<--children> | I<--children-only>}]
> +
> +Delete the checkpoint for the domain named I<checkpoint>, or the
> +current checkpoint with I<--current>.  The record of which portions of
> +the disk changed since the checkpoint are merged into the parent
> +checkpoint (if any). If I<--children> is passed, then delete this
> +checkpoint and any children of this checkpoint.  If I<--children-only>
> +is passed, then delete any children of this checkpoint, but leave this
> +checkpoint intact. These two flags are mutually exclusive.
> +
> +If I<--metadata> is specified, then only delete the checkpoint
> +metadata maintained by libvirt, while leaving the checkpoint contents
> +intact for access by external tools; otherwise deleting a checkpoint
> +also removes the ability to perform an incremental backup from that
> +point in time.
> +
> +=back
> +
>  =head1 NWFILTER COMMANDS
> 
>  The following commands manipulate network filters. Network filters allow
> -- 
> 2.20.1
> 
> --
> libvir-list mailing list
> libvir-list@xxxxxxxxxx
> https://www.redhat.com/mailman/listinfo/libvir-list

Attachment: signature.asc
Description: PGP signature

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

[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux