From nobody Mon Sep 16 19:33:22 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1540496810113469.23234325647184; Thu, 25 Oct 2018 12:46:50 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 1D4B5308424C; Thu, 25 Oct 2018 19:46:48 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C6B4E6714C; Thu, 25 Oct 2018 19:46:47 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 537EE4BB79; Thu, 25 Oct 2018 19:46:47 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w9PJKYvK027616 for ; Thu, 25 Oct 2018 15:20:34 -0400 Received: by smtp.corp.redhat.com (Postfix) id A7C2A60C60; Thu, 25 Oct 2018 19:20:34 +0000 (UTC) Received: from red.redhat.com (ovpn-122-116.rdu2.redhat.com [10.10.122.116]) by smtp.corp.redhat.com (Postfix) with ESMTP id 235D865F48; Thu, 25 Oct 2018 19:20:32 +0000 (UTC) From: Eric Blake To: libvir-list@redhat.com Date: Thu, 25 Oct 2018 20:20:02 +0100 Message-Id: <20181025192021.350438-2-eblake@redhat.com> In-Reply-To: <20181025192021.350438-1-eblake@redhat.com> References: <20181025192021.350438-1-eblake@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-loop: libvir-list@redhat.com Cc: amureini@redhat.com, derez@redhat.com, vsementsov@virtuozzo.com, ydary@redhat.com, nsoffer@redhat.com, jsnow@redhat.com Subject: [libvirt] [PATCH v3 01/20] snapshots: Avoid term 'checkpoint' for full system snapshot X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.40]); Thu, 25 Oct 2018 19:46:48 +0000 (UTC) Content-Type: text/plain; charset="utf-8" Upcoming patches plan to introduce virDomainCheckpointPtr as a new object for use in incremental backups, along with documentation on how incremental backups differ from snapshots. But first, we need to rename any existing mention of a 'system checkpoint' to instead be a 'full system snapshot', so that we aren't overloading the term checkpoint. Signed-off-by: Eric Blake --- v2: wording improvements based on review --- include/libvirt/libvirt-domain-snapshot.h | 2 +- docs/formatsnapshot.html.in | 31 +++++++++++------------ src/conf/snapshot_conf.c | 4 +-- src/libvirt-domain-snapshot.c | 7 ++--- src/qemu/qemu_driver.c | 12 ++++----- tools/virsh-snapshot.c | 2 +- tools/virsh.pod | 14 +++++----- 7 files changed, 36 insertions(+), 36 deletions(-) diff --git a/include/libvirt/libvirt-domain-snapshot.h b/include/libvirt/li= bvirt-domain-snapshot.h index 20771f9b1e..00954a0d3a 100644 --- a/include/libvirt/libvirt-domain-snapshot.h +++ b/include/libvirt/libvirt-domain-snapshot.h @@ -60,7 +60,7 @@ typedef enum { VIR_DOMAIN_SNAPSHOT_CREATE_HALT =3D (1 << 3), /* Stop running g= uest after snapshot */ VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY =3D (1 << 4), /* disk snapshot,= not - system checkpoin= t */ + full system */ VIR_DOMAIN_SNAPSHOT_CREATE_REUSE_EXT =3D (1 << 5), /* reuse any exis= ting external files */ VIR_DOMAIN_SNAPSHOT_CREATE_QUIESCE =3D (1 << 6), /* use guest agen= t to diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in index fbbecfd242..c60b4fb7c9 100644 --- a/docs/formatsnapshot.html.in +++ b/docs/formatsnapshot.html.in @@ -33,7 +33,7 @@ resume in a consistent state; but if the disks are modified externally in the meantime, this is likely to lead to data corruption. -
system checkpoint
+
full system
A combination of disk snapshots for all disks as well as VM memory state, which can be used to resume the guest from where it left off with symptoms similar to hibernation (that is, TCP @@ -55,11 +55,12 @@ as virDomainSaveImageGetXMLDesc() to work with those files.

-

System checkpoints are created - by virDomainSnapshotCreateXML() with no flags, and +

Full system snapshots are created + by virDomainSnapshotCreateXML() with no flags, while disk snapshots are created by the same function with - the VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY flag; in - both cases, they are restored by + the VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY + flag. Regardless of the flags provided, restoration of the + snapshot is handled by the virDomainRevertToSnapshot() function. For these types of snapshots, libvirt tracks each snapshot as a separate virDomainSnapshotPtr object, and maintains @@ -128,13 +129,10 @@ what file name is created in an external snapshot. On output, this is fully populated to show the state of each disk in the snapshot, including any properties that were generated by the - hypervisor defaults. For system checkpoints, this field is - ignored on input and omitted on output (a system checkpoint - implies that all disks participate in the snapshot process, - and since the current implementation only does internal system - checkpoints, there are no extra details to add); a future - release may allow the use of disks with a system - checkpoint. This element has a list of disk + hypervisor defaults. For full system snapshots, this field is + ignored on input and omitted on output (a full system snapshot + implies that all disks participate in the snapshot process). + This element has a list of disk sub-elements, describing anywhere from zero to all of the disks associated with the domain. Since 0.9.5 @@ -206,11 +204,12 @@

state
The state of the domain at the time this snapshot was taken. - If the snapshot was created as a system checkpoint, then this - is the state of the domain at that time; when the domain is + If a full system snapshot was created, then this + is the state of the domain at that time. When the domain is reverted to this snapshot, the domain's state will default to - whatever is in this field unless additional flags are passed - to virDomainRevertToSnapshot(). Additionally, + this state, unless overridden + by virDomainRevertToSnapshot() flags to revert to + a running or paused state. Additionally, this field can be the value "disk-snapshot" (since 0.9.5) when it represents only a disk snapshot (no VM memory state), and reverting to this diff --git a/src/conf/snapshot_conf.c b/src/conf/snapshot_conf.c index adba149241..f89048e3f1 100644 --- a/src/conf/snapshot_conf.c +++ b/src/conf/snapshot_conf.c @@ -1302,8 +1302,8 @@ virDomainSnapshotRedefinePrep(virDomainPtr domain, if ((other->def->state =3D=3D VIR_DOMAIN_DISK_SNAPSHOT) !=3D (def->state =3D=3D VIR_DOMAIN_DISK_SNAPSHOT)) { virReportError(VIR_ERR_INVALID_ARG, - _("cannot change between disk snapshot and " - "system checkpoint in snapshot %s"), + _("cannot change between disk only and " + "full system in snapshot %s"), def->name); goto cleanup; } diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c index 100326a5e7..1cc0188928 100644 --- a/src/libvirt-domain-snapshot.c +++ b/src/libvirt-domain-snapshot.c @@ -105,8 +105,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapsh= ot) * contained in xmlDesc. * * If @flags is 0, the domain can be active, in which case the - * snapshot will be a system checkpoint (both disk state and runtime - * VM state such as RAM contents), where reverting to the snapshot is + * snapshot will be a full system snapshot (capturing both disk state, + * and runtime VM state such as RAM contents), where reverting to the + * snapshot is * the same as resuming from hibernation (TCP connections may have * timed out, but everything else picks up where it left off); or * the domain can be inactive, in which case the snapshot includes @@ -149,7 +150,7 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapsh= ot) * is not paused while creating the snapshot. This increases the size * of the memory dump file, but reduces downtime of the guest while * taking the snapshot. Some hypervisors only support this flag during - * external checkpoints. + * external snapshots. * * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY, then the * snapshot will be limited to the disks described in @xmlDesc, and no diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index 9f71641dfa..bb5bc4d200 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -2153,7 +2153,7 @@ qemuDomainReset(virDomainPtr dom, unsigned int flags) } -/* Count how many snapshots in a set are external snapshots or checkpoints= . */ +/* Count how many snapshots in a set are external snapshots. */ static int qemuDomainSnapshotCountExternal(void *payload, const void *name ATTRIBUTE_UNUSED, @@ -14713,7 +14713,7 @@ qemuDomainSnapshotPrepare(virDomainObjPtr vm, if ((def->memory =3D=3D VIR_DOMAIN_SNAPSHOT_LOCATION_INTERNAL && !foun= d_internal) || (found_internal && forbid_internal)) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", - _("internal snapshots and checkpoints require all " + _("internal and full system snapshots require all " "disks to be selected for snapshot")); goto cleanup; } @@ -15163,7 +15163,7 @@ qemuDomainSnapshotCreateActiveExternal(virQEMUDrive= rPtr driver, if (virDomainObjGetState(vm, NULL) =3D=3D VIR_DOMAIN_PMSUSPENDED) { pmsuspended =3D true; } else if (virDomainObjGetState(vm, NULL) =3D=3D VIR_DOMAIN_RUNNING) { - /* For external checkpoints (those with memory), the guest + /* For full system external snapshots (those with memory), the gue= st * must pause (either by libvirt up front, or by qemu after * _LIVE converges). */ if (memory) @@ -15391,7 +15391,7 @@ qemuDomainSnapshotCreateXML(virDomainPtr domain, redefine)) { virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s", _("live snapshot creation is supported only " - "with external checkpoints")); + "during full system snapshots")); goto cleanup; } @@ -15511,12 +15511,12 @@ qemuDomainSnapshotCreateXML(virDomainPtr domain, } else if (virDomainObjIsActive(vm)) { if (flags & VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY || snap->def->memory =3D=3D VIR_DOMAIN_SNAPSHOT_LOCATION_EXTERNAL= ) { - /* external checkpoint or disk snapshot */ + /* external full system or disk snapshot */ if (qemuDomainSnapshotCreateActiveExternal(driver, vm, snap, flags) < = 0) goto endjob; } else { - /* internal checkpoint */ + /* internal full system */ if (qemuDomainSnapshotCreateActiveInternal(driver, vm, snap, flags) < = 0) goto endjob; diff --git a/tools/virsh-snapshot.c b/tools/virsh-snapshot.c index 73861957ba..7b340162f3 100644 --- a/tools/virsh-snapshot.c +++ b/tools/virsh-snapshot.c @@ -1427,7 +1427,7 @@ static const vshCmdOptDef opts_snapshot_list[] =3D { }, {.name =3D "active", .type =3D VSH_OT_BOOL, - .help =3D N_("filter by snapshots taken while active (system checkpoi= nts)") + .help =3D N_("filter by snapshots taken while active (full system sna= pshots)") }, {.name =3D "disk-only", .type =3D VSH_OT_BOOL, diff --git a/tools/virsh.pod b/tools/virsh.pod index 86c041d575..58ab9a090b 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4490,8 +4490,8 @@ If I<--halt> is specified, the domain will be left in= an inactive state after the snapshot is created. If I<--disk-only> is specified, the snapshot will only include disk -state rather than the usual system checkpoint with vm state. Disk -snapshots are faster than full system checkpoints, but reverting to a +content rather than the usual full system snapshot with vm state. Disk +snapshots are captured faster than full system snapshots, but reverting to= a disk snapshot may require fsck or journal replays, since it is like the disk state at the point when the power cord is abruptly pulled; and mixing I<--halt> and I<--disk-only> loses any data that was not @@ -4530,10 +4530,10 @@ this. If this flag is not specified, then some hyp= ervisors may fail after partially performing the action, and B must be used to see whether any partial changes occurred. -If I<--live> is specified, libvirt takes the snapshot (checkpoint) while +If I<--live> is specified, libvirt takes the snapshot while the guest is running. Both disk snapshot and domain memory snapshot are taken. This increases the size of the memory image of the external -checkpoint. This is currently supported only for external checkpoints. +snapshot. This is currently supported only for full system external snapsh= ots. Existence of snapshot metadata will prevent attempts to B a persistent domain. However, for transient domains, snapshot @@ -4553,7 +4553,7 @@ Otherwise, if I<--halt> is specified, the domain will= be left in an inactive state after the snapshot is created, and if I<--disk-only> is specified, the snapshot will not include vm state. -The I<--memspec> option can be used to control whether a checkpoint +The I<--memspec> option can be used to control whether a full system snaps= hot is internal or external. The I<--memspec> flag is mandatory, followed by a B of the form B<[file=3D]name[,snapshot=3Dtype]>, where type can be B, B, or B. To include a literal @@ -4561,7 +4561,7 @@ comma in B, escape it with a second comm= a. I<--memspec> cannot be used together with I<--disk-only>. The I<--diskspec> option can be used to control how I<--disk-only> and -external checkpoints create external files. This option can occur +external full system snapshots create external files. This option can occ= ur multiple times, according to the number of elements in the domain xml. Each is in the form B. A I @@ -4601,7 +4601,7 @@ see whether any partial changes occurred. If I<--live> is specified, libvirt takes the snapshot while the guest is running. This increases the size of the memory image of the external -checkpoint. This is currently supported only for external checkpoints. +snapshot. This is currently supported only for external full system snapsh= ots. =3Ditem B I {[I<--name>] | [I<--security-info>] | [I]} --=20 2.17.2 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list