X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/d26d808a7009a77c5e6e82bdde6c69c879e01e38..0547d608b4d5424e9192f5e2e7619393b5e2e250:/man/htools.rst

diff --git a/man/htools.rst b/man/htools.rst
index 1163099..a05039b 100644
--- a/man/htools.rst
+++ b/man/htools.rst
@@ -51,17 +51,196 @@ COMMON OPTIONS
 Options behave the same in all program modes, but not all program modes
 support all options. Some common options are:
 
--v, --verbose
+-p, \--print-nodes
+  Prints the node status, in a format designed to allow the user to
+  understand the node's most important parameters. If the command in
+  question makes a cluster transition (e.g. balancing or allocation),
+  then usually both the initial and final node status is printed.
+
+  It is possible to customise the listed information by passing a
+  comma-separated list of field names to this option (the field list
+  is currently undocumented), or to extend the default field list by
+  prefixing the additional field list with a plus sign. By default,
+  the node list will contain the following information:
+
+  F
+    a character denoting the status of the node, with '-' meaning an
+    offline node, '*' meaning N+1 failure and blank meaning a good
+    node
+
+  Name
+    the node name
+
+  t_mem
+    the total node memory
+
+  n_mem
+    the memory used by the node itself
+
+  i_mem
+    the memory used by instances
+
+  x_mem
+    amount memory which seems to be in use but cannot be determined
+    why or by which instance; usually this means that the hypervisor
+    has some overhead or that there are other reporting errors
+
+  f_mem
+    the free node memory
+
+  r_mem
+    the reserved node memory, which is the amount of free memory
+    needed for N+1 compliance
+
+  t_dsk
+    total disk
+
+  f_dsk
+    free disk
+
+  pcpu
+    the number of physical cpus on the node
+
+  vcpu
+    the number of virtual cpus allocated to primary instances
+
+  pcnt
+    number of primary instances
+
+  scnt
+    number of secondary instances
+
+  p_fmem
+    percent of free memory
+
+  p_fdsk
+    percent of free disk
+
+  r_cpu
+    ratio of virtual to physical cpus
+
+  lCpu
+    the dynamic CPU load (if the information is available)
+
+  lMem
+    the dynamic memory load (if the information is available)
+
+  lDsk
+    the dynamic disk load (if the information is available)
+
+  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
+  - node spindle count
+
+  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 section contains the cluster tags, with one tag per line
+  (no columns/no column processing).
+
+  The fifth section contains the ipolicies of the cluster and the node
+  groups, in the following format (separated by ``|``):
+
+  - owner (empty if cluster, group name otherwise)
+  - standard, min, max instance specs, containing the following values
+    separated by commas:
+    - memory size
+    - cpu count
+    - disk size
+    - disk count
+    - nic count
+  - disk templates
+  - vcpu ratio
+  - spindle ratio
+
+-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.
+
+-I|\--ialloc-src *path*
+  Backend specification: load data directly from an iallocator request
+  (as produced by Ganeti when doing an iallocator call).  The iallocator
+  request is read from specified path.
+
+\--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
+  - the spindle count for the nodes
+
+  An example description would be **preferred,B20,100G,16g,4,2**
+  describing a 20-node cluster where each node has 100GB of disk space,
+  16GiB of memory, 4 CPU cores and 2 disk spindles. 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)
   from the default of one.
 
--q, --quiet
+-q, \--quiet
   Decrease the output verbosity. Each usage of this option will
   decrease the verbosity (less than zero doesn't make sense) from the
   default of one.
 
--V, --version
+-V, \--version
   Just show the program version and exit.
 
 UNITS