lib: Introduce VIR_DOMAIN_BACKUP_BEGIN_PRESERVE_SHUTDOWN_DOMAIN flag

This flag will instruct the hypervisor driver to keep the VM around
while the backup is running if the guest OS decides to shut down, so
that the backup can be finished.

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

docs/manpages/virsh.rst

@@ -2186,6 +2186,7 @@ backup-begin
 ::
 
    backup-begin domain [backupxml] [checkpointxml] [--reuse-external]
+       [--preserve-domain-on-shutdown]
 
 Begin a new backup job. If *backupxml* is omitted, this defaults to a full
 backup using a push model to filenames generated by libvirt; supplying XML
@@ -2199,6 +2200,11 @@ libvirt. For more information on backup XML, see:
 If *--reuse-external* is used it instructs libvirt to reuse temporary
 and output files provided by the user in *backupxml*.
 
+When the *--preserve-domain-on-shutdown* flag is used libvirt will not
+terminate the VM if the guest OS shuts down while the backup is running. The VM
+will be instead kept in VIR_DOMAIN_PAUSED state until the backup job finishes.
+The vm can be also resumed in order to boot again.
+
 If *checkpointxml* is specified, a second file with a top-level
 element of *domaincheckpoint* is used to create a simultaneous
 checkpoint, for doing a later incremental backup relative to the time

include/libvirt/libvirt-domain.h

@@ -8518,8 +8518,10 @@ int virDomainAgentSetResponseTimeout(virDomainPtr domain,
  * Since: 6.0.0
  */
 typedef enum {
-    VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL = (1 << 0), /* reuse separately
-                                                          provided images (Since: 6.0.0) */
+    /* reuse separately provided images (Since: 6.0.0) */
+    VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL = (1 << 0),
+    /* preserve the domain if the guest OS shuts down while the backup is running (Since: 11.10.0) */
+    VIR_DOMAIN_BACKUP_BEGIN_PRESERVE_SHUTDOWN_DOMAIN = (1 << 1),
 } virDomainBackupBeginFlags;
 
 int virDomainBackupBegin(virDomainPtr domain,

src/libvirt-domain.c

@@ -13682,6 +13682,11 @@ virDomainAgentSetResponseTimeout(virDomainPtr domain,
  * temporary files described by the @backupXML document were created by the
  * caller with correct format and size to hold the backup or temporary data.
  *
+ * When the VIR_DOMAIN_BACKUP_BEGIN_PRESERVE_SHUTDOWN_DOMAIN flag is used
+ * libvirt will not terminate the VM if the guest OS shuts down while the
+ * backup is running. The VM will be kept in the VIR_DOMAIN_PAUSED state
+ * until the backup job finishes or until it's resumed via virDomainResume.
+ *
  * The creation of a new checkpoint allows for future incremental backups.
  * Note that some hypervisors may require a particular disk format, such as
  * qcow2, in order to take advantage of checkpoints, while allowing arbitrary

tools/virsh-backup.c

@@ -48,6 +48,10 @@ static const vshCmdOptDef opts_backup_begin[] = {
      .type = VSH_OT_BOOL,
      .help = N_("reuse files provided by caller"),
     },
+    {.name = "preserve-domain-on-shutdown",
+     .type = VSH_OT_BOOL,
+     .help = N_("avoid shutdown of the domain while the backup is running"),
+    },
     {.name = NULL}
 };
 
@@ -65,6 +69,9 @@ cmdBackupBegin(vshControl *ctl,
     if (vshCommandOptBool(cmd, "reuse-external"))
         flags |= VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL;
 
+    if (vshCommandOptBool(cmd, "preserve-domain-on-shutdown"))
+        flags |= VIR_DOMAIN_BACKUP_BEGIN_PRESERVE_SHUTDOWN_DOMAIN;
+
     if (!(dom = virshCommandOptDomain(ctl, cmd, NULL)))
         return false;