From acd9fa11689a1f0fd02d979d2f0c6aee4337d475 Mon Sep 17 00:00:00 2001
From: Iustin Pop <iustin@google.com>
Date: Tue, 20 Sep 2011 17:29:20 +0900
Subject: [PATCH] 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 | 13 +++++----
man/hbal.rst | 29 +++++++++----------
man/hspace.rst | 51 +++++++++++----------------------
man/htools.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 113 insertions(+), 57 deletions(-)
diff --git a/man/hail.rst b/man/hail.rst
index 925fc44ad..7cba43d88 100644
--- a/man/hail.rst
+++ b/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
diff --git a/man/hbal.rst b/man/hbal.rst
index 1e054e576..1a98621cc 100644
--- a/man/hbal.rst
+++ b/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
diff --git a/man/hspace.rst b/man/hspace.rst
index 91375af2d..d08ae7906 100644
--- a/man/hspace.rst
+++ b/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
diff --git a/man/htools.rst b/man/htools.rst
index 3104bf0e7..843d20fe6 100644
--- a/man/htools.rst
+++ b/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)
--
GitLab