commit 620a85fdb0b9221dbbb32ef1366deded932c83e1
Author: Iustin Pop <iustin@google.com>
Date:   Tue Oct 27 12:56:00 2009 +0900

    Unify the query fields for the storage framework
    
    This patch unifies the query fields in the storage framework for all
    types. Note that the information is still computed on-demand, so if e.g.
    the used disk space is not requested for the ‘file’ type, it won't be
    computed on nodes.
    
    Summary of changes:
    - improve the LVM storage type to support multiple lvm fields in the
      LIST_FIELDS declaration and constant (not-computed via lvm commands)
      fields
    - rename utils.GetFilesystemFreeSpace to utils.GetFilesystemStats
      returning tuple of (total, free)
    - add used and free as valid fields for lvm-vg (use being computed as
      vg_size-vg_free)
    - make allocatable accepted for all types (ones which are always
      allocatable always return True)
    - add a new list field ‘type’ that gives the current selected type; not
      much useful today (except for understanding what the default output
      is) but in the future might help if we want to list multiple types
    - add type, size and allocatable to the default output field list
    - update the man page with details on how, for file storage, size ≠ used
      + free for non-mountpoint cases
    
    Signed-off-by: Iustin Pop <iustin@google.com>
    Reviewed-by: Michael Hanselmann <hansmi@google.com>

diff --git a/man/gnt-node.sgml b/man/gnt-node.sgml
index 44ab6c2..a62edd0 100644
--- a/man/gnt-node.sgml
+++ b/man/gnt-node.sgml
@@ -794,8 +794,7 @@ node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  inst
       <para>
         The <option>--storage-type</option> option can be used to choose a
         storage unit type. Possible choices are <literal>lvm-pv</literal>,
-        <literal>lvm-vg</literal> or <literal>file</literal>. Depending on the
-        storage type, the available output fields change.
+        <literal>lvm-vg</literal> or <literal>file</literal>.
       </para>
 
       <para>
@@ -809,17 +808,24 @@ node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  inst
             </listitem>
           </varlistentry>
           <varlistentry>
+            <term>type</term>
+            <listitem>
+              <simpara>the type of the storage unit (currently just
+              what is passed in via
+              <option>--storage-type</option>)</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
             <term>name</term>
             <listitem>
-              <simpara>the physical drive name</simpara>
+              <simpara>the path/identifier of the storage unit</simpara>
             </listitem>
           </varlistentry>
           <varlistentry>
             <term>size</term>
             <listitem>
               <simpara>
-                the physical drive size
-                (<literal>lvm-pv</literal> and <literal>lvm-vg</literal> only)
+                total size of the unit; for the file type see a note below
               </simpara>
             </listitem>
           </varlistentry>
@@ -827,8 +833,7 @@ node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  inst
             <term>used</term>
             <listitem>
               <simpara>
-                used disk space
-                (<literal>lvm-pv</literal> and <literal>file</literal> only)
+                used space in the unit; for the file type see a note below
               </simpara>
             </listitem>
           </varlistentry>
@@ -837,7 +842,6 @@ node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  inst
             <listitem>
               <simpara>
                 available disk space
-                (<literal>lvm-pv</literal> and <literal>file</literal> only)
               </simpara>
             </listitem>
           </varlistentry>
@@ -845,8 +849,9 @@ node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  inst
             <term>allocatable</term>
             <listitem>
               <simpara>
-                whether physical volume is allocatable
-                (<literal>lvm-pv</literal> only)
+                whether we the unit is available for allocation
+                (only <literal>lvm-pv</literal> can change this
+                setting, the other types always report true)
               </simpara>
             </listitem>
           </varlistentry>
@@ -854,12 +859,25 @@ node1.example.com /dev/hdc1 xenvg instance1.example.com-sda_11001.data 256  inst
       </para>
 
       <para>
+        Note that for the <quote>file</quote> type, the total disk
+        space might not equal to the sum of used and free, due to the
+        method Ganeti uses to compute each of them. The total and free
+        values are computed as the total and free space values for the
+        filesystem to which the directory belongs, but the used space
+        is computed from the used space under that directory
+        <emphasis>only</emphasis>, which might not be necessarily the
+        root of the filesystem, and as such there could be files
+        outside the file storage directory using disk space and
+        causing a mismatch in the values.
+      </para>
+
+      <para>
         Example:
         <screen>
-# gnt-node list-storage node5.example.com
-Node              Name        Size Used   Free
-node5.example.com /dev/sda7 673.8G   0M 673.8G
-node5.example.com /dev/sdb1 698.6G 1.3G 697.4G
+node1# gnt-node list-storage node2
+Node  Type   Name        Size Used   Free Allocatable
+node2 lvm-pv /dev/sda7 673.8G 1.5G 672.3G Y
+node2 lvm-pv /dev/sdb1 698.6G   0M 698.6G Y
         </screen>
       </para>
     </refsect2>
