save: add --bypass-cache flag to virsh save/restore operations

Wire up the new flag to several virsh commands.  Also, the
'dump' command had undocumented flags.

* tools/virsh.c (cmdSave, cmdManagedSave, cmdDump, cmdStart)
(cmdRestore): Add new flag.
* tools/virsh.pod (save, managedsave, dump, start, restore):
Document flags.

tools/virsh.c

@@ -1541,6 +1541,8 @@ static const vshCmdOptDef opts_start[] = {
 #endif
     {"paused", VSH_OT_BOOL, 0, N_("leave the guest paused after creation")},
     {"autodestroy", VSH_OT_BOOL, 0, N_("automatically destroy the guest when virsh disconnects")},
+    {"bypass-cache", VSH_OT_BOOL, 0,
+     N_("avoid file system cache when loading")},
     {NULL, 0, 0, NULL}
 };
 
@@ -1571,6 +1573,8 @@ cmdStart(vshControl *ctl, const vshCmd *cmd)
         flags |= VIR_DOMAIN_START_PAUSED;
     if (vshCommandOptBool(cmd, "autodestroy"))
         flags |= VIR_DOMAIN_START_AUTODESTROY;
+    if (vshCommandOptBool(cmd, "bypass-cache"))
+        flags |= VIR_DOMAIN_START_BYPASS_CACHE;
 
     /* Prefer older API unless we have to pass a flag.  */
     if ((flags ? virDomainCreateWithFlags(dom, flags)
@@ -1599,6 +1603,7 @@ static const vshCmdInfo info_save[] = {
 };
 
 static const vshCmdOptDef opts_save[] = {
+    {"bypass-cache", VSH_OT_BOOL, 0, N_("avoid file system cache when saving")},
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
     {"file", VSH_OT_DATA, VSH_OFLAG_REQ, N_("where to save the data")},
     {NULL, 0, 0, NULL}
@@ -1610,7 +1615,8 @@ cmdSave(vshControl *ctl, const vshCmd *cmd)
     virDomainPtr dom;
     const char *name = NULL;
     const char *to = NULL;
-    bool ret = true;
+    bool ret = false;
+    int flags = 0;
 
     if (!vshConnectionUsability(ctl, ctl->conn))
         return false;
@@ -1618,16 +1624,22 @@ cmdSave(vshControl *ctl, const vshCmd *cmd)
     if (vshCommandOptString(cmd, "file", &to) <= 0)
         return false;
 
+    if (vshCommandOptBool(cmd, "bypass-cache"))
+        flags |= VIR_DOMAIN_SAVE_BYPASS_CACHE;
+
     if (!(dom = vshCommandOptDomain(ctl, cmd, &name)))
         return false;
 
-    if (virDomainSave(dom, to) == 0) {
+    if ((flags ? virDomainSaveFlags(dom, to, NULL, flags)
-        vshPrint(ctl, _("Domain %s saved to %s\n"), name, to);
+         : virDomainSave(dom, to)) < 0) {
-    } else {
         vshError(ctl, _("Failed to save domain %s to %s"), name, to);
-        ret = false;
+        goto cleanup;
     }
 
+    vshPrint(ctl, _("Domain %s saved to %s\n"), name, to);
+    ret = true;
+
+cleanup:
     virDomainFree(dom);
     return ret;
 }
@@ -1645,6 +1657,7 @@ static const vshCmdInfo info_managedsave[] = {
 };
 
 static const vshCmdOptDef opts_managedsave[] = {
+    {"bypass-cache", VSH_OT_BOOL, 0, N_("avoid file system cache when saving")},
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
     {NULL, 0, 0, NULL}
 };
@@ -1654,21 +1667,27 @@ cmdManagedSave(vshControl *ctl, const vshCmd *cmd)
 {
     virDomainPtr dom;
     const char *name;
-    bool ret = true;
+    bool ret = false;
+    int flags = 0;
 
     if (!vshConnectionUsability(ctl, ctl->conn))
         return false;
 
+    if (vshCommandOptBool(cmd, "bypass-cache"))
+        flags |= VIR_DOMAIN_SAVE_BYPASS_CACHE;
+
     if (!(dom = vshCommandOptDomain(ctl, cmd, &name)))
         return false;
 
-    if (virDomainManagedSave(dom, 0) == 0) {
+    if (virDomainManagedSave(dom, flags) < 0) {
-        vshPrint(ctl, _("Domain %s state saved by libvirt\n"), name);
-    } else {
         vshError(ctl, _("Failed to save domain %s state"), name);
-        ret = false;
+        goto cleanup;
     }
 
+    vshPrint(ctl, _("Domain %s state saved by libvirt\n"), name);
+    ret = true;
+
+cleanup:
     virDomainFree(dom);
     return ret;
 }
@@ -1995,6 +2014,8 @@ static const vshCmdInfo info_restore[] = {
 
 static const vshCmdOptDef opts_restore[] = {
     {"file", VSH_OT_DATA, VSH_OFLAG_REQ, N_("the state to restore")},
+    {"bypass-cache", VSH_OT_BOOL, 0,
+     N_("avoid file system cache when restoring")},
     {NULL, 0, 0, NULL}
 };
 
@@ -2002,7 +2023,8 @@ static bool
 cmdRestore(vshControl *ctl, const vshCmd *cmd)
 {
     const char *from = NULL;
-    bool ret = true;
+    bool ret = false;
+    int flags = 0;
 
     if (!vshConnectionUsability(ctl, ctl->conn))
         return false;
@@ -2010,12 +2032,19 @@ cmdRestore(vshControl *ctl, const vshCmd *cmd)
     if (vshCommandOptString(cmd, "file", &from) <= 0)
         return false;
 
-    if (virDomainRestore(ctl->conn, from) == 0) {
+    if (vshCommandOptBool(cmd, "bypass-cache"))
-        vshPrint(ctl, _("Domain restored from %s\n"), from);
+        flags |= VIR_DOMAIN_SAVE_BYPASS_CACHE;
-    } else {
+
+    if ((flags ? virDomainRestoreFlags(ctl->conn, from, NULL, flags)
+         : virDomainRestore(ctl->conn, from)) < 0) {
         vshError(ctl, _("Failed to restore domain from %s"), from);
-        ret = false;
+        goto cleanup;
     }
+
+    vshPrint(ctl, _("Domain restored from %s\n"), from);
+    ret = true;
+
+cleanup:
     return ret;
 }
 
@@ -2031,6 +2060,8 @@ static const vshCmdInfo info_dump[] = {
 static const vshCmdOptDef opts_dump[] = {
     {"live", VSH_OT_BOOL, 0, N_("perform a live core dump if supported")},
     {"crash", VSH_OT_BOOL, 0, N_("crash the domain after core dump")},
+    {"bypass-cache", VSH_OT_BOOL, 0,
+     N_("avoid file system cache when saving")},
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
     {"file", VSH_OT_DATA, VSH_OFLAG_REQ, N_("where to dump the core")},
     {NULL, 0, 0, NULL}
@@ -2042,7 +2073,7 @@ cmdDump(vshControl *ctl, const vshCmd *cmd)
     virDomainPtr dom;
     const char *name = NULL;
     const char *to = NULL;
-    bool ret = true;
+    bool ret = false;
     int flags = 0;
 
     if (!vshConnectionUsability(ctl, ctl->conn))
@@ -2058,14 +2089,18 @@ cmdDump(vshControl *ctl, const vshCmd *cmd)
         flags |= VIR_DUMP_LIVE;
     if (vshCommandOptBool (cmd, "crash"))
         flags |= VIR_DUMP_CRASH;
+    if (vshCommandOptBool(cmd, "bypass-cache"))
+        flags |= VIR_DUMP_BYPASS_CACHE;
 
-    if (virDomainCoreDump(dom, to, flags) == 0) {
+    if (virDomainCoreDump(dom, to, flags) < 0) {
-        vshPrint(ctl, _("Domain %s dumped to %s\n"), name, to);
-    } else {
         vshError(ctl, _("Failed to core dump domain %s to %s"), name, to);
-        ret = false;
+        goto cleanup;
     }
 
+    vshPrint(ctl, _("Domain %s dumped to %s\n"), name, to);
+    ret = true;
+
+cleanup:
     virDomainFree(dom);
     return ret;
 }

tools/virsh.pod

@@ -475,9 +475,16 @@ named by I<format> to a domain XML format.
 Convert the file I<xml> in domain XML format to the native guest
 configuration format named by I<format>.
 
-=item B<dump> I<domain-id> I<corefilepath>
+=item B<dump> I<domain-id> I<corefilepath> [I<--live>] [I<--crash>]
+[I<--bypass-cache>]
 
 Dumps the core of a domain to a file for analysis.
+If I<--live> is specified, the domain continues to run until the core
+dump is complete, rather than pausing up front.
+If I<--crash> is specified, the domain is halted with a crashed status,
+rather than merely left in a paused state.
+If I<--bypass-cache> is specified, the save will avoid the file system
+cache, although this may slow down the operation.
 
 =item B<dumpxml> I<domain-id> [I<--inactive>] [I<--security-info>]
 [I<--update-cpu>]
@@ -512,11 +519,13 @@ 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>.
 
-=item B<managedsave> I<domain-id>
+=item B<managedsave> I<domain-id> [I<--bypass-cache>]
 
 Save and destroy (stop) a running domain, so it can be restarted from the same
 state at a later time.  When the virsh B<start> command is next run for
 the domain, it will automatically be started from this saved state.
+If I<--bypass-cache> is specified, the save will avoid the file system
+cache, although this may slow down the operation.
 
 The B<dominfo> command can be used to query whether a domain currently
 has any managed save image.
@@ -590,22 +599,27 @@ domain actually reboots.
 The exact behavior of a domain when it reboots is set by the
 I<on_reboot> parameter in the domain's XML definition.
 
-=item B<restore> I<state-file>
+=item B<restore> I<state-file> [I<--bypass-cache>]
 
 Restores a domain from a B<virsh save> state file. See I<save> for more info.
 
+If I<--bypass-cache> is specified, the restore will avoid the file system
+cache, although this may slow down the operation.
+
 B<Note>: To avoid corrupting file system contents within the domain, you
 should not reuse the saved state file for a second B<restore> unless you
 have also reverted all storage volumes back to the same contents as when
 the state file was created.
 
-=item B<save> I<domain-id> I<state-file>
+=item B<save> I<domain-id> I<state-file> [I<--bypass-cache>]
 
 Saves a running domain (RAM, but not disk state) to a state file so that
 it can be restored
 later.  Once saved, the domain will no longer be running on the
 system, thus the memory allocated for the domain will be free for
 other domains to use.  B<virsh restore> restores from this state file.
+If I<--bypass-cache> is specified, the save will avoid the file system
+cache, although this may slow down the operation.
 
 This is roughly equivalent to doing a hibernate on a running computer,
 with all the same limitations.  Open network connections may be
@@ -791,6 +805,7 @@ The exact behavior of a domain when it shuts down is set by the
 I<on_shutdown> parameter in the domain's XML definition.
 
 =item B<start> I<domain-name> [I<--console>] [I<--paused>] [I<--autodestroy>]
+[I<--bypass-cache>]
 
 Start a (previously defined) inactive domain, either from the last
 B<managedsave> state, or via a fresh boot if no managedsave state is
@@ -799,7 +814,9 @@ used and supported by the driver; otherwise it will be running.
 If I<--console> is requested, attach to the console after creation.
 If I<--autodestroy> is requested, then the guest will be automatically
 destroyed when virsh closes its connection to libvirt, or otherwise
-exits.
+exits.  If I<--bypass-cache> is specified, and managedsave state exists,
+the restore will avoid the file system cache, although this may slow
+down the operation.
 
 =item B<suspend> I<domain-id>