conf: snapshot: Introduce 'manual' mode for snapshot of a disk

The idea of the manual mode is to allow a synchronized snapshot in cases
when the storage is outsourced to an unmanaged storage provider which
requires cooperation with snapshotting.

The mode will instruct the hypervisor to pause along when the other
components are snapshotted and the 'manual' disk can be snapshotted
along. This increases latency of the snapshot but allows them in
otherwise impossible situations.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

docs/formatdomain.rst

@@ -2620,13 +2620,14 @@ paravirtualized driver is specified via the ``disk`` element.
       Indicates the default behavior of the disk during disk snapshots:
       "``internal``" requires a file format such as qcow2 that can store both
       the snapshot and the data changes since the snapshot; "``external``" will
-      separate the snapshot from the live data; and "``no``" means the disk will
+      separate the snapshot from the live data; "``no``" means the disk will
-      not participate in snapshots. Read-only disks default to "``no``", while
+      not participate in snapshots; and ``manual`` allows snapshotting done via
-      the default for other disks depends on the hypervisor's capabilities. Some
+      an unmanaged storage provider. Read-only disks default to "``no``", while
-      hypervisors allow a per-snapshot choice as well, during `domain snapshot
+      the default for other disks depends on the hypervisor's capabilities.
-      creation <formatsnapshot.html>`__. Not all snapshot modes are supported;
+      Some hypervisors allow a per-snapshot choice as well, during `domain
-      for example, enabling snapshots with a transient disk generally does not
+      snapshot creation <formatsnapshot.html>`__. Not all snapshot modes are
-      make sense. :since:`Since 0.9.5`
+      supported; for example, enabling snapshots with a transient disk
+      generally does not make sense. :since:`Since 0.9.5`
 
 ``source``
    Representation of the disk ``source`` depends on the disk ``type`` attribute

docs/formatsnapshot.rst

@@ -124,6 +124,15 @@ The top-level ``domainsnapshot`` element may contain the following elements:
       corresponding domain disk, while others like qemu allow this field to
       override the domain default.
 
+      :since:`Since 8.2.0` the ``snapshot`` attribute supports the ``manual``
+      value which instructs the hypervisor to create the snapshot and keep a
+      synchronized state by pausing the VM which allows to snapshot disk
+      storage from outside of the hypervisor if the storage provider supports
+      it.  The caller is responsible for resuming a VM paused by requesting a
+      ``manual`` snapshot. When reverting such snapshot, the expectation is that
+      the storage is configured in a way where the hypervisor will see the
+      correct image state.
+
       :since:`Since 1.2.2` the ``disk`` element supports an optional attribute
       ``type`` if the ``snapshot`` attribute is set to ``external``. This
       attribute specifies the snapshot target storage type and allows to

docs/schemas/domainsnapshot.rng

@@ -200,6 +200,9 @@
             <ref name="diskSourceNetwork"/>
           </choice>
         </group>
+        <attribute name="snapshot">
+          <value>manual</value>
+        </attribute>
       </choice>
     </element>
   </define>

src/conf/domain_conf.c

@@ -1408,6 +1408,7 @@ VIR_ENUM_IMPL(virDomainSnapshotLocation,
               "no",
               "internal",
               "external",
+              "manual",
 );
 
 /* Internal mapping: subset of block job types that can be present in

src/conf/domain_conf.h

@@ -542,6 +542,7 @@ typedef enum {
     VIR_DOMAIN_SNAPSHOT_LOCATION_NO,
     VIR_DOMAIN_SNAPSHOT_LOCATION_INTERNAL,
     VIR_DOMAIN_SNAPSHOT_LOCATION_EXTERNAL,
+    VIR_DOMAIN_SNAPSHOT_LOCATION_MANUAL,
 
     VIR_DOMAIN_SNAPSHOT_LOCATION_LAST
 } virDomainSnapshotLocation;

src/conf/snapshot_conf.c

@@ -312,6 +312,12 @@ virDomainSnapshotDefParse(xmlXPathContextPtr ctxt,
                                   &def->memory,
                                   VIR_DOMAIN_SNAPSHOT_LOCATION_DEFAULT) < 0)
             return NULL;
+
+        if (def->memory == VIR_DOMAIN_SNAPSHOT_LOCATION_MANUAL) {
+            virReportError(VIR_ERR_XML_ERROR, "%s",
+                           _("'manual' memory snapshot mode not supported"));
+            return NULL;
+        }
     }
 
     if (def->memory == VIR_DOMAIN_SNAPSHOT_LOCATION_DEFAULT) {

src/qemu/qemu_snapshot.c

@@ -757,6 +757,11 @@ qemuSnapshotPrepare(virDomainObj *vm,
             external++;
             break;
 
+        case VIR_DOMAIN_SNAPSHOT_LOCATION_MANUAL:
+            virReportError(VIR_ERR_INTERNAL_ERROR, "%s",
+                           _("'manual' disk snapshot mode not yet implemented"));
+            return -1;
+
         case VIR_DOMAIN_SNAPSHOT_LOCATION_NO:
             /* Remember seeing a disk that has snapshot disabled */
             if (!virStorageSourceIsEmpty(dom_disk->src) &&

src/test/test_driver.c

@@ -8710,6 +8710,23 @@ testDomainSnapshotAlignDisks(virDomainObj *vm,
                              unsigned int flags)
 {
     virDomainSnapshotLocation align_location = VIR_DOMAIN_SNAPSHOT_LOCATION_INTERNAL;
+    size_t i;
+
+    for (i = 0; i < def->ndisks; i++) {
+        switch (def->disks[i].snapshot) {
+        case VIR_DOMAIN_SNAPSHOT_LOCATION_DEFAULT:
+        case VIR_DOMAIN_SNAPSHOT_LOCATION_NO:
+        case VIR_DOMAIN_SNAPSHOT_LOCATION_INTERNAL:
+        case VIR_DOMAIN_SNAPSHOT_LOCATION_EXTERNAL:
+        case VIR_DOMAIN_SNAPSHOT_LOCATION_LAST:
+            break;
+
+        case VIR_DOMAIN_SNAPSHOT_LOCATION_MANUAL:
+            virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
+                           _("'manual' snapshot mode is not supported by the test driver"));
+            return -1;
+        }
+    }
 
     if (flags & VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY) {
         align_location = VIR_DOMAIN_SNAPSHOT_LOCATION_EXTERNAL;