code.grnet.gr Git - ganeti-local/blob - man/htools.rst

   1 HTOOLS(1) Ganeti | Version @GANETI_VERSION@
   2 ===========================================
   3
   4 NAME
   5 ----
   6
   7 htools - Cluster allocation and placement tools for Ganeti
   8
   9 SYNOPSIS
  10 --------
  11
  12 **hbal**
  13   cluster balancer
  14
  15 **hcheck**
  16   cluster checker
  17
  18 **hspace**
  19   cluster capacity computation
  20
  21 **hail**
  22   IAllocator plugin
  23
  24 **hscan**
  25   saves cluster state for later reuse
  26
  27 **hinfo**
  28   cluster information printer
  29
  30
  31 DESCRIPTION
  32 -----------
  33
  34
  35 ``htools`` is a suite of tools designed to help with allocation/movement
  36 of instances and balancing of Ganeti clusters. ``htools`` is also the
  37 generic binary that must be symlinked or hardlinked under each tool's
  38 name in order to perform the different functions. Alternatively, the
  39 environment variable HTOOLS can be used to set the desired role.
  40
  41 Installed as ``hbal``, it computes and optionally executes a suite of
  42 instance moves in order to balance the cluster.
  43
  44 Installed as ``hcheck``, it preforms cluster checks and optionally
  45 simulates rebalancing with all the ``hbal`` options available.
  46
  47 Installed as ``hspace``, it computes how many additional instances can
  48 be fit on a cluster, while maintaining N+1 status. It can run on models
  49 of existing clusters or of simulated clusters.
  50
  51 Installed as ``hail``, it acts as an IAllocator plugin, i.e. it is used
  52 by Ganeti to compute new instance allocations and instance moves.
  53
  54 Installed as ``hscan``, it scans the local or remote cluster state and
  55 saves it to files which can later be reused by the other roles.
  56
  57 Installed as ``hinfo``, it prints information about the current cluster
  58 state.
  59
  60 COMMON OPTIONS
  61 --------------
  62
  63 Options behave the same in all program modes, but not all program modes
  64 support all options. Some common options are:
  65
  66 -p, \--print-nodes
  67   Prints the node status, in a format designed to allow the user to
  68   understand the node's most important parameters. If the command in
  69   question makes a cluster transition (e.g. balancing or allocation),
  70   then usually both the initial and final node status is printed.
  71
  72   It is possible to customise the listed information by passing a
  73   comma-separated list of field names to this option (the field list
  74   is currently undocumented), or to extend the default field list by
  75   prefixing the additional field list with a plus sign. By default,
  76   the node list will contain the following information:
  77
  78   F
  79     a character denoting the status of the node, with '-' meaning an
  80     offline node, '*' meaning N+1 failure and blank meaning a good
  81     node
  82
  83   Name
  84     the node name
  85
  86   t_mem
  87     the total node memory
  88
  89   n_mem
  90     the memory used by the node itself
  91
  92   i_mem
  93     the memory used by instances
  94
  95   x_mem
  96     amount memory which seems to be in use but cannot be determined
  97     why or by which instance; usually this means that the hypervisor
  98     has some overhead or that there are other reporting errors
  99
 100   f_mem
 101     the free node memory
 102
 103   r_mem
 104     the reserved node memory, which is the amount of free memory
 105     needed for N+1 compliance
 106
 107   t_dsk
 108     total disk
 109
 110   f_dsk
 111     free disk
 112
 113   pcpu
 114     the number of physical cpus on the node
 115
 116   vcpu
 117     the number of virtual cpus allocated to primary instances
 118
 119   pcnt
 120     number of primary instances
 121
 122   scnt
 123     number of secondary instances
 124
 125   p_fmem
 126     percent of free memory
 127
 128   p_fdsk
 129     percent of free disk
 130
 131   r_cpu
 132     ratio of virtual to physical cpus
 133
 134   lCpu
 135     the dynamic CPU load (if the information is available)
 136
 137   lMem
 138     the dynamic memory load (if the information is available)
 139
 140   lDsk
 141     the dynamic disk load (if the information is available)
 142
 143   lNet
 144     the dynamic net load (if the information is available)
 145
 146 -t *datafile*, \--text-data=*datafile*
 147   Backend specification: the name of the file holding node and instance
 148   information (if not collecting via RAPI or LUXI). This or one of the
 149   other backends must be selected. The option is described in the man
 150   page **htools**(1).
 151
 152   The file should contain text data, line-based, with two empty lines
 153   separating sections. The lines themselves are column-based, with the
 154   pipe symbol (``|``) acting as separator.
 155
 156   The first section contains group data, with two columns:
 157
 158   - group name
 159   - group uuid
 160
 161   The second sections contains node data, with the following columns:
 162
 163   - node name
 164   - node total memory
 165   - node free memory
 166   - node total disk
 167   - node free disk
 168   - node physical cores
 169   - offline field (as ``Y`` or ``N``)
 170   - group UUID
 171   - node spindle count
 172
 173   The third section contains instance data, with the fields:
 174
 175   - instance name
 176   - instance memory
 177   - instance disk size
 178   - instance vcpus
 179   - instance status (in Ganeti's format, e.g. ``running`` or ``ERROR_down``)
 180   - instance ``auto_balance`` flag (see man page **gnt-instance** (7))
 181   - instance primary node
 182   - instance secondary node(s), if any
 183   - instance disk type (e.g. ``plain`` or ``drbd``)
 184   - instance tags
 185
 186   The fourth section contains the cluster tags, with one tag per line
 187   (no columns/no column processing).
 188
 189   The fifth section contains the ipolicies of the cluster and the node
 190   groups, in the following format (separated by ``|``):
 191
 192   - owner (empty if cluster, group name otherwise)
 193   - standard, min, max instance specs, containing the following values
 194     separated by commas:
 195     - memory size
 196     - cpu count
 197     - disk size
 198     - disk count
 199     - nic count
 200   - disk templates
 201   - vcpu ratio
 202   - spindle ratio
 203
 204 -m *cluster*
 205   Backend specification: collect data directly from the *cluster* given
 206   as an argument via RAPI. If the argument doesn't contain a colon (:),
 207   then it is converted into a fully-built URL via prepending
 208   ``https://`` and appending the default RAPI port, otherwise it is
 209   considered a fully-specified URL and used as-is.
 210
 211 -L [*path*]
 212   Backend specification: collect data directly from the master daemon,
 213   which is to be contacted via LUXI (an internal Ganeti protocol). An
 214   optional *path* argument is interpreted as the path to the unix socket
 215   on which the master daemon listens; otherwise, the default path used
 216   by Ganeti (configured at build time) is used.
 217
 218 -I|\--ialloc-src *path*
 219   Backend specification: load data directly from an iallocator request
 220   (as produced by Ganeti when doing an iallocator call).  The iallocator
 221   request is read from specified path.
 222
 223 \--simulate *description*
 224   Backend specification: instead of using actual data, build an empty
 225   cluster given a node description. The *description* parameter must be
 226   a comma-separated list of five elements, describing in order:
 227
 228   - the allocation policy for this node group (*preferred*, *allocable*
 229     or *unallocable*, or alternatively the short forms *p*, *a* or *u*)
 230   - the number of nodes in the cluster
 231   - the disk size of the nodes (default in mebibytes, units can be used)
 232   - the memory size of the nodes (default in mebibytes, units can be used)
 233   - the cpu core count for the nodes
 234   - the spindle count for the nodes
 235
 236   An example description would be **preferred,B20,100G,16g,4,2**
 237   describing a 20-node cluster where each node has 100GB of disk space,
 238   16GiB of memory, 4 CPU cores and 2 disk spindles. Note that all nodes
 239   must have the same specs currently.
 240
 241   This option can be given multiple times, and each new use defines a
 242   new node group. Hence different node groups can have different
 243   allocation policies and node count/specifications.
 244
 245 -v, \--verbose
 246   Increase the output verbosity. Each usage of this option will
 247   increase the verbosity (currently more than 2 doesn't make sense)
 248   from the default of one.
 249
 250 -q, \--quiet
 251   Decrease the output verbosity. Each usage of this option will
 252   decrease the verbosity (less than zero doesn't make sense) from the
 253   default of one.
 254
 255 -V, \--version
 256   Just show the program version and exit.
 257
 258 UNITS
 259 ~~~~~
 260
 261 Some options accept not simply numerical values, but numerical values
 262 together with a unit. By default, such unit-accepting options use
 263 mebibytes. Using the lower-case letters of *m*, *g* and *t* (or their
 264 longer equivalents of *mib*, *gib*, *tib*, for which case doesn't
 265 matter) explicit binary units can be selected. Units in the SI system
 266 can be selected using the upper-case letters of *M*, *G* and *T* (or
 267 their longer equivalents of *MB*, *GB*, *TB*, for which case doesn't
 268 matter).
 269
 270 More details about the difference between the SI and binary systems can
 271 be read in the *units(7)* man page.
 272
 273 ENVIRONMENT
 274 -----------
 275
 276 The environment variable ``HTOOLS`` can be used instead of
 277 renaming/symlinking the programs; simply set it to the desired role and
 278 then the name of the program is no longer used.
 279
 280 .. vim: set textwidth=72 :
 281 .. Local Variables:
 282 .. mode: rst
 283 .. fill-column: 72
 284 .. End: