htools: man page improvements

This patch moves all the backend options into the main htools man
page, and it adds documentation for the -t option, which so far was
not documented w.r.t. the file structure.

Signed-off-by: Iustin Pop <iustin@google.com>
Reviewed-by: Michael Hanselmann <hansmi@google.com>

man/hail.rst

@@ -68,19 +68,20 @@ The options that can be passed to the program are as follows:
   man page **htools**(1) for more details about this option.
 
 -t *datafile*, --text-data=*datafile*
-  The name of the file holding cluster information, to override the
-  data in the JSON request itself. This is mostly used for debugging.
+  The name of the file holding cluster information, to override the data
+  in the JSON request itself. This is mostly used for debugging. The
+  format of the file is described in the man page **htools**(1).
 
 --simulate *description*
-  Similar to the **-t** option, this allows overriding the cluster
-  data with a simulated cluster. For details about the description,
-  see the man page **hspace**(1).
+  Backend specification: similar to the **-t** option, this allows
+  overriding the cluster data with a simulated cluster. For details
+  about the description, see the man page **htools**(1).
 
 -S *filename*, --save-cluster=*filename*
   If given, the state of the cluster before and the iallocator run is
   saved to a file named *filename.pre-ialloc*, respectively
   *filename.post-ialloc*. This allows re-feeding the cluster state to
-  any of the htools utilities.
+  any of the htools utilities via the ``-t`` option.
 
 -v
   This option increases verbosity and can be used for debugging in order

man/hbal.rst

@@ -325,32 +325,29 @@ The options that can be passed to the program are as follows:
   metrics and thus the influence of the dynamic utilisation will be
   practically insignificant.
 
--t *datafile*, --text-data=*datafile*
-  The name of the file holding node and instance information (if not
-  collecting via RAPI or LUXI). This or one of the other backends must
-  be selected.
-
 -S *filename*, --save-cluster=*filename*
   If given, the state of the cluster before the balancing is saved to
   the given file plus the extension "original"
   (i.e. *filename*.original), and the state at the end of the
   balancing is saved to the given file plus the extension "balanced"
   (i.e. *filename*.balanced). This allows re-feeding the cluster state
-  to either hbal itself or for example hspace.
+  to either hbal itself or for example hspace via the ``-t`` option.
+
+-t *datafile*, --text-data=*datafile*
+  Backend specification: the name of the file holding node and instance
+  information (if not collecting via RAPI or LUXI). This or one of the
+  other backends must be selected. The option is described in the man
+  page **htools**(1).
 
 -m *cluster*
- Collect data directly from the *cluster* given as an argument via
- RAPI. If the argument doesn't contain a colon (:), then it is
- converted into a fully-built URL via prepending ``https://`` and
- appending the default RAPI port, otherwise it's considered a
- fully-specified URL and is used as-is.
+  Backend specification: collect data directly from the *cluster* given
+  as an argument via RAPI. The option is described in the man page
+  **htools**(1).
 
 -L [*path*]
-  Collect data directly from the master daemon, which is to be
-  contacted via the luxi (an internal Ganeti protocol). An optional
-  *path* argument is interpreted as the path to the unix socket on
-  which the master daemon listens; otherwise, the default path used by
-  ganeti when installed with *--localstatedir=/var* is used.
+  Backend specification: collect data directly from the master daemon,
+  which is to be contacted via LUXI (an internal Ganeti protocol). The
+  option is described in the man page **htools**(1).
 
 -X
   When using the Luxi backend, hbal can also execute the given

man/hspace.rst

@@ -250,53 +250,34 @@ The options that can be passed to the program are as follows:
   are reported by RAPI as such, or that have "?" in file-based input
   in any numeric fields.
 
--t *datafile*, --text-data=*datafile*
-  The name of the file holding node and instance information (if not
-  collecting via RAPI or LUXI). This or one of the other backends must
-  be selected.
-
 -S *filename*, --save-cluster=*filename*
   If given, the state of the cluster at the end of the allocation is
   saved to a file named *filename.alloc*, and if tiered allocation is
   enabled, the state after tiered allocation will be saved to
   *filename.tiered*. This allows re-feeding the cluster state to
   either hspace itself (with different parameters) or for example
-  hbal.
+  hbal, via the ``-t`` option.
+
+-t *datafile*, --text-data=*datafile*
+  Backend specification: the name of the file holding node and instance
+  information (if not collecting via RAPI or LUXI). This or one of the
+  other backends must be selected. The option is described in the man
+  page **htools**(1).
 
 -m *cluster*
- Collect data directly from the *cluster* given as an argument via
- RAPI. If the argument doesn't contain a colon (:), then it is
- converted into a fully-built URL via prepending ``https://`` and
- appending the default RAPI port, otherwise it's considered a
- fully-specified URL and is used as-is.
+  Backend specification: collect data directly from the *cluster* given
+  as an argument via RAPI. The option is described in the man page
+  **htools**(1).
 
 -L [*path*]
-  Collect data directly from the master daemon, which is to be
-  contacted via the luxi (an internal Ganeti protocol). An optional
-  *path* argument is interpreted as the path to the unix socket on
-  which the master daemon listens; otherwise, the default path used by
-  ganeti when installed with *--localstatedir=/var* is used.
+  Backend specification: collect data directly from the master daemon,
+  which is to be contacted via LUXI (an internal Ganeti protocol). The
+  option is described in the man page **htools**(1).
 
 --simulate *description*
-  Instead of using actual data, build an empty cluster given a node
-  description. The *description* parameter must be a comma-separated
-  list of five elements, describing in order:
-
-  - the allocation policy for this node group (*preferred*, *allocable*
-    or *unallocable*, or alternatively the short forms *p*, *a* or *u*)
-  - the number of nodes in the cluster
-  - the disk size of the nodes (default in mebibytes, units can be used)
-  - the memory size of the nodes (default in mebibytes, units can be used)
-  - the cpu core count for the nodes
-
-  An example description would be **preferred,B20,100G,16g,4**
-  describing a 20-node cluster where each node has 100GB of disk
-  space, 16GiB of memory and 4 CPU cores. Note that all nodes must
-  have the same specs currently.
-
-  This option can be given multiple times, and each new use defines a
-  new node group. Hence different node groups can have different
-  allocation policies and node count/specifications.
+  Backend specification: similar to the **-t** option, this allows
+  overriding the cluster data with a simulated cluster. For details
+  about the description, see the man page **htools**(1).
 
 --tiered-alloc *spec*
   Besides the standard, fixed-size allocation, also do a tiered

man/htools.rst

@@ -131,6 +131,83 @@ support all options. Some common options are:
   lNet
     the dynamic net load (if the information is available)
 
+-t *datafile*, --text-data=*datafile*
+  Backend specification: the name of the file holding node and instance
+  information (if not collecting via RAPI or LUXI). This or one of the
+  other backends must be selected. The option is described in the man
+  page **htools**(1).
+
+  The file should contain text data, line-based, with two empty lines
+  separating sections. The lines themselves are column-based, with the
+  pipe symbol (``|``) acting as separator.
+
+  The first section contains group data, with two columns:
+
+  - group name
+  - group uuid
+
+  The second sections contains node data, with the following columns:
+
+  - node name
+  - node total memory
+  - node free memory
+  - node total disk
+  - node free disk
+  - node physical cores
+  - offline field (as ``Y`` or ``N``)
+  - group UUID
+
+  The third section contains instance data, with the fields:
+
+  - instance name
+  - instance memory
+  - instance disk size
+  - instance vcpus
+  - instance status (in Ganeti's format, e.g. ``running`` or ``ERROR_down``)
+  - instance ``auto_balance`` flag (see man page **gnt-instance** (7))
+  - instance primary node
+  - instance secondary node(s), if any
+  - instance disk type (e.g. ``plain`` or ``drbd``)
+  - instance tags
+
+  The fourth and last section contains the cluster tags, with one tag
+  per line (no columns/no column processing).
+
+-m *cluster*
+  Backend specification: collect data directly from the *cluster* given
+  as an argument via RAPI. If the argument doesn't contain a colon (:),
+  then it is converted into a fully-built URL via prepending
+  ``https://`` and appending the default RAPI port, otherwise it is
+  considered a fully-specified URL and used as-is.
+
+-L [*path*]
+  Backend specification: collect data directly from the master daemon,
+  which is to be contacted via LUXI (an internal Ganeti protocol). An
+  optional *path* argument is interpreted as the path to the unix socket
+  on which the master daemon listens; otherwise, the default path used
+  by Ganeti (configured at build time) is used.
+
+--simulate *description*
+  Backend specification: instead of using actual data, build an empty
+  cluster given a node description. The *description* parameter must be
+  a comma-separated list of five elements, describing in order:
+
+  - the allocation policy for this node group (*preferred*, *allocable*
+    or *unallocable*, or alternatively the short forms *p*, *a* or *u*)
+  - the number of nodes in the cluster
+  - the disk size of the nodes (default in mebibytes, units can be used)
+  - the memory size of the nodes (default in mebibytes, units can be used)
+  - the cpu core count for the nodes
+
+  An example description would be **preferred,B20,100G,16g,4**
+  describing a 20-node cluster where each node has 100GB of disk
+  space, 16GiB of memory and 4 CPU cores. Note that all nodes must
+  have the same specs currently.
+
+  This option can be given multiple times, and each new use defines a
+  new node group. Hence different node groups can have different
+  allocation policies and node count/specifications.
+
 -v, --verbose
   Increase the output verbosity. Each usage of this option will
   increase the verbosity (currently more than 2 doesn't make sense)