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