snapshot: reflect new dumpxml and list options in virsh

New flag bits are worth exposing via virsh.  In the case of
snapshot-list --roots, it's possible to emulate this even when
talking to an older server that lacks the bit; whereas
--metadata requires a newer server.

Although we don't use --security-info yet, the flag is already
documented for other dumpxml operations, and turning it on now
will make it useful when a future patch actually has to honor it.

* tools/virsh.c (cmdSnapshotDumpXML, cmdSnapshotCurrent): Add
--security-info.
(cmdSnapshotList): Add --roots, --metadata.
* tools/virsh.pod (snapshot-dumpxml, snapshot-current)
(snapshot-list): Document these.

tools/virsh.c

@@ -12120,6 +12120,8 @@ static const vshCmdInfo info_snapshot_current[] = {
 static const vshCmdOptDef opts_snapshot_current[] = {
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
     {"name", VSH_OT_BOOL, 0, N_("list the name, rather than the full xml")},
+    {"security-info", VSH_OT_BOOL, 0,
+     N_("include security sensitive information in XML dump")},
     {NULL, 0, 0, NULL}
 };
 
@@ -12131,6 +12133,10 @@ cmdSnapshotCurrent(vshControl *ctl, const vshCmd *cmd)
     int current;
     virDomainSnapshotPtr snapshot = NULL;
     char *xml = NULL;
+    unsigned int flags = 0;
+
+    if (vshCommandOptBool(cmd, "security-info"))
+        flags |= VIR_DOMAIN_XML_SECURE;
 
     if (!vshConnectionUsability(ctl, ctl->conn))
         goto cleanup;
@@ -12148,7 +12154,7 @@ cmdSnapshotCurrent(vshControl *ctl, const vshCmd *cmd)
         if (!(snapshot = virDomainSnapshotCurrent(dom, 0)))
             goto cleanup;
 
-        xml = virDomainSnapshotGetXMLDesc(snapshot, 0);
+        xml = virDomainSnapshotGetXMLDesc(snapshot, flags);
         if (!xml)
             goto cleanup;
 
@@ -12195,6 +12201,9 @@ static const vshCmdInfo info_snapshot_list[] = {
 static const vshCmdOptDef opts_snapshot_list[] = {
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
     {"parent", VSH_OT_BOOL, 0, N_("add a column showing parent snapshot")},
+    {"roots", VSH_OT_BOOL, 0, N_("list only snapshots without parents")},
+    {"metadata", VSH_OT_BOOL, 0,
+     N_("list only snapshots that have metadata that would prevent undefine")},
     {NULL, 0, 0, NULL}
 };
 
@@ -12204,8 +12213,8 @@ cmdSnapshotList(vshControl *ctl, const vshCmd *cmd)
     virDomainPtr dom = NULL;
     bool ret = false;
     unsigned int flags = 0;
-    int parent_filter = 0; /* 0 for no parent information needed,
-                              1 for parent column */
+    int parent_filter = 0; /* -1 for roots filtering, 0 for no parent
+                              information needed, 1 for parent column */
     int numsnaps;
     char **names = NULL;
     int actual = 0;
@@ -12222,7 +12231,18 @@ cmdSnapshotList(vshControl *ctl, const vshCmd *cmd)
     struct tm time_info;
 
     if (vshCommandOptBool(cmd, "parent")) {
+        if (vshCommandOptBool(cmd, "roots")) {
+            vshError(ctl, "%s",
+                     _("--parent and --roots are mutually exlusive"));
+            return false;
+        }
         parent_filter = 1;
+    } else if (vshCommandOptBool(cmd, "roots")) {
+        flags |= VIR_DOMAIN_SNAPSHOT_LIST_ROOTS;
+    }
+
+    if (vshCommandOptBool(cmd, "metadata")) {
+        flags |= VIR_DOMAIN_SNAPSHOT_LIST_METADATA;
     }
 
     if (!vshConnectionUsability(ctl, ctl->conn))
@@ -12234,6 +12254,16 @@ cmdSnapshotList(vshControl *ctl, const vshCmd *cmd)
 
     numsnaps = virDomainSnapshotNum(dom, flags);
 
+    /* Fall back to simulation if --roots was unsupported.  */
+    if (numsnaps < 0 && last_error->code == VIR_ERR_INVALID_ARG &&
+        (flags & VIR_DOMAIN_SNAPSHOT_LIST_ROOTS)) {
+        virFreeError(last_error);
+        last_error = NULL;
+        parent_filter = -1;
+        flags &= ~VIR_DOMAIN_SNAPSHOT_LIST_ROOTS;
+        numsnaps = virDomainSnapshotNum(dom, flags);
+    }
+
     if (numsnaps < 0)
         goto cleanup;
 
@@ -12281,6 +12311,8 @@ cmdSnapshotList(vshControl *ctl, const vshCmd *cmd)
             if (parent_filter) {
                 parent = virXPathString("string(/domainsnapshot/parent/name)",
                                         ctxt);
+                if (!parent && parent_filter < 0)
+                    continue;
             }
 
             state = virXPathString("string(/domainsnapshot/state)", ctxt);
@@ -12338,6 +12370,8 @@ static const vshCmdInfo info_snapshot_dumpxml[] = {
 static const vshCmdOptDef opts_snapshot_dumpxml[] = {
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
     {"snapshotname", VSH_OT_DATA, VSH_OFLAG_REQ, N_("snapshot name")},
+    {"security-info", VSH_OT_BOOL, 0,
+     N_("include security sensitive information in XML dump")},
     {NULL, 0, 0, NULL}
 };
 
@@ -12349,6 +12383,10 @@ cmdSnapshotDumpXML(vshControl *ctl, const vshCmd *cmd)
     const char *name = NULL;
     virDomainSnapshotPtr snapshot = NULL;
     char *xml = NULL;
+    unsigned int flags = 0;
+
+    if (vshCommandOptBool(cmd, "security-info"))
+        flags |= VIR_DOMAIN_XML_SECURE;
 
     if (!vshConnectionUsability(ctl, ctl->conn))
         goto cleanup;
@@ -12364,7 +12402,7 @@ cmdSnapshotDumpXML(vshControl *ctl, const vshCmd *cmd)
     if (snapshot == NULL)
         goto cleanup;
 
-    xml = virDomainSnapshotGetXMLDesc(snapshot, 0);
+    xml = virDomainSnapshotGetXMLDesc(snapshot, flags);
     if (!xml)
         goto cleanup;
 

tools/virsh.pod

@@ -596,7 +596,7 @@ Output the domain information as an XML dump to stdout, this format can be used
 by the B<create> command. Additional options affecting the XML dump may be
 used. I<--inactive> tells virsh to dump domain configuration that will be used
 on next start of the domain as opposed to the current domain configuration.
-Using I<--security-info> security sensitive information will also be included
+Using I<--security-info> will also include security sensitive information
 in the XML dump. I<--update-cpu> updates domain CPU requirements according to
 host CPU.
 
@@ -1702,21 +1702,32 @@ value.  If I<--print-xml> is specified, then XML appropriate for
 I<snapshot-create> is output, rather than actually creating a snapshot.
 
 =item B<snapshot-current> I<domain> [I<--name>]
+=item B<snapshot-current> I<domain> {[I<--name>] | [I<--security-info]}
 
 Output the snapshot XML for the domain's current snapshot (if any).
-If I<--name> is specified, just list the snapshot name instead of the
-full xml.
+If I<--name> is specified, just print the current snapshot name instead
+of the full xml.  Otherwise, using I<--security-info> will also include
+security sensitive information in the XML.
 
-=item B<snapshot-list> I<domain> [I<--parent>]
+=item B<snapshot-list> I<domain> [{I<--parent> | I<--roots>}] [I<--metadata>]
 
 List all of the available snapshots for the given domain.
 
 If I<--parent> is specified, add a column to the output table giving
 the name of the parent of each snapshot.
 
-=item B<snapshot-dumpxml> I<domain> I<snapshot>
+If I<--roots> is specified, the list will be filtered to just snapshots
+that have no parents; this option is not compatible with I<--parent>.
+
+If I<--metadata> is specified, the list will be filtered to just
+snapshots that involve libvirt metadata, and thus would prevent
+B<undefine> of a persistent domain, or be lost on B<destroy> of
+a transient domain.
+
+=item B<snapshot-dumpxml> I<domain> I<snapshot> [I<--security-info>]
 
 Output the snapshot XML for the domain's snapshot named I<snapshot>.
+Using I<--security-info> will also include security sensitive information.
 
 =item B<snapshot-parent> I<domain> I<snapshot>