Improve the documentation of query output fields

The gnt-node and gnt-instance list commands have a customizable list of
output fields, but the list is not up to date (in the man page) and not
easily understandable from the ‘--help’ output.

This patch updates the man pages and adds the available fields and
default fields in the ‘--help’ output, as part of the description.

Example:
Usage
=====
  gnt-node list

Lists the nodes in the cluster. The available fields are (see the man page for
details): name, pinst_cnt, pinst_list, sinst_cnt, sinst_list, pip, sip,
dtotal, dfree, mtotal, mnode, mfree, bootid. The default field list is (in
order): name, dtotal, dfree, mtotal, mnode, mfree, pinst_cnt, sinst_cnt.

Reviewed-by: imsnah,ultrotter

diff --git a/lib/cli.py b/lib/cli.py
index d2bcf6f..a58f550 100644 (file)
--- a/lib/cli.py
+++ b/lib/cli.py
@@ -167,7 +167,8 @@ USEUNITS_OPT = make_option("--human-readable", default=False,
                            help="Print sizes in human readable format")
 
 FIELDS_OPT = make_option("-o", "--output", dest="output", action="store",
-                         type="string", help="Select output fields",
+                         type="string", help="Comma separated list of"
+                         " output fields",
                          metavar="FIELDS")
 
 FORCE_OPT = make_option("-f", "--force", dest="force", action="store_true",

diff --git a/man/gnt-instance.sgml b/man/gnt-instance.sgml
index 36a6c14..100d856 100644 (file)
--- a/man/gnt-instance.sgml
+++ b/man/gnt-instance.sgml
@@ -436,6 +436,25 @@
                 </simpara>
               </listitem>
             </varlistentry>
+            <varlistentry>
+              <term>sda_size</term>
+              <listitem>
+                <simpara>the size of the instance's first disk</simpara>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>sdb_size</term>
+              <listitem>
+                <simpara>the size of the instance's second disk</simpara>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>vcpus</term>
+              <listitem>
+                <simpara>the number of VCPUs allocated to the
+                instance</simpara>
+              </listitem>
+            </varlistentry>
           </variablelist>
         </para>
 

diff --git a/man/gnt-node.sgml b/man/gnt-node.sgml
index d44847b..f6d4c3e 100644 (file)
--- a/man/gnt-node.sgml
+++ b/man/gnt-node.sgml
@@ -232,20 +232,34 @@
             </listitem>
           </varlistentry>
           <varlistentry>
-            <term>pinst</term>
+            <term>pinst_cnt</term>
             <listitem>
               <simpara>the number of instances having this node as
               primary</simpara>
             </listitem>
           </varlistentry>
           <varlistentry>
-            <term>sinst</term>
+            <term>pinst_list</term>
+            <listitem>
+              <simpara>the list of instances having this node as
+              primary, comma separated</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>sinst_cnt</term>
             <listitem>
               <simpara>the number of instances having this node as a
               secondary node</simpara>
             </listitem>
           </varlistentry>
           <varlistentry>
+            <term>sinst_list</term>
+            <listitem>
+              <simpara>the list of instances having this node as a
+              secondary node, comma separated</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
             <term>pip</term>
             <listitem>
               <simpara>the primary ip of this node (used for cluster
@@ -296,6 +310,15 @@
               allocations</simpara>
             </listitem>
           </varlistentry>
+          <varlistentry>
+            <term>bootid</term>
+            <listitem>
+              <simpara>the node bootid value; this is a linux specific
+              feature that assigns a new UUID to the node at each boot
+              and can be use to detect node reboots (by tracking
+              changes in this value)</simpara>
+            </listitem>
+          </varlistentry>
         </variablelist>
       </para>
 

diff --git a/scripts/gnt-instance b/scripts/gnt-instance
index fd54f7c..5842b39 100755 (executable)
--- a/scripts/gnt-instance
+++ b/scripts/gnt-instance
@@ -811,7 +811,12 @@ commands = {
            "Show information on the specified instance"),
   'list': (ListInstances, ARGS_NONE,
            [DEBUG_OPT, NOHDR_OPT, SEP_OPT, USEUNITS_OPT, FIELDS_OPT],
-           "", "Lists the instances and their status"),
+           "", "Lists the instances and their status. The available fields"
+           " are (see the man page for details): oper_state, oper_ram,"
+           " name, os, pnode, snodes, admin_state, admin_ram, disk_template,"
+           " ip, mac, bridge, sda_size, sdb_size, vcpus. The default field"
+           " list is (in order): name, os, pnode, admin_state, oper_state,"
+           " oper_ram."),
   'reinstall': (ReinstallInstance, ARGS_ONE, [DEBUG_OPT, FORCE_OPT, os_opt],
                 "[-f] <instance>", "Reinstall the instance"),
   'remove': (RemoveInstance, ARGS_ONE,

diff --git a/scripts/gnt-node b/scripts/gnt-node
index 8078af7..df37be6 100755 (executable)
--- a/scripts/gnt-node
+++ b/scripts/gnt-node
@@ -300,7 +300,11 @@ commands = {
            "[<node_name>...]", "Show information about the node(s)"),
   'list': (ListNodes, ARGS_NONE,
            [DEBUG_OPT, NOHDR_OPT, SEP_OPT, USEUNITS_OPT, FIELDS_OPT],
-           "", "Lists the nodes in the cluster"),
+           "", "Lists the nodes in the cluster. The available fields"
+           " are (see the man page for details): name, pinst_cnt, pinst_list,"
+           " sinst_cnt, sinst_list, pip, sip, dtotal, dfree, mtotal, mnode,"
+           " mfree, bootid. The default field list is (in order): name,"
+           " dtotal, dfree, mtotal, mnode, mfree, pinst_cnt, sinst_cnt."),
   'remove': (RemoveNode, ARGS_ONE, [DEBUG_OPT],
              "<node_name>", "Removes a node from the cluster"),
   'volumes': (ListVolumes, ARGS_ANY,