1 HTOOLS(1) Ganeti | Version @GANETI_VERSION@
2 ===========================================
7 htools - Cluster allocation and placement tools for Ganeti
19 cluster capacity computation
25 saves cluster state for later reuse
28 cluster information printer
31 cluster rolling maintenance scheduler
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.
42 Installed as ``hbal``, it computes and optionally executes a suite of
43 instance moves in order to balance the cluster.
45 Installed as ``hcheck``, it preforms cluster checks and optionally
46 simulates rebalancing with all the ``hbal`` options available.
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.
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.
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.
58 Installed as ``hinfo``, it prints information about the current cluster
61 Installed as ``hroller``, it helps scheduling maintenances that require
62 node reboots on a cluster.
67 Options behave the same in all program modes, but not all program modes
68 support all options. Some common options are:
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.
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:
83 a character denoting the status of the node, with '-' meaning an
84 offline node, '*' meaning N+1 failure and blank meaning a good
94 the memory used by the node itself
97 the memory used by instances
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
108 the reserved node memory, which is the amount of free memory
109 needed for N+1 compliance
118 the number of physical cpus on the node
121 the number of virtual cpus allocated to primary instances
124 number of primary instances
127 number of secondary instances
130 percent of free memory
136 ratio of virtual to physical cpus
139 the dynamic CPU load (if the information is available)
142 the dynamic memory load (if the information is available)
145 the dynamic disk load (if the information is available)
148 the dynamic net load (if the information is available)
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
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.
160 The first section contains group data, with the following columns:
165 - tags (separated by comma)
167 The second sections contains node data, with the following columns:
171 - memory used by the node
175 - node physical cores
176 - offline/role field (``Y`` for offline nodes, ``N`` for online non-master
177 nodes, and ``M`` for the master node which is always online)
181 The third section contains instance data, with the fields:
187 - instance status (in Ganeti's format, e.g. ``running`` or ``ERROR_down``)
188 - instance ``auto_balance`` flag (see man page **gnt-instance**\(8))
189 - instance primary node
190 - instance secondary node(s), if any
191 - instance disk type (e.g. ``plain`` or ``drbd``)
194 The fourth section contains the cluster tags, with one tag per line
195 (no columns/no column processing).
197 The fifth section contains the ipolicies of the cluster and the node
198 groups, in the following format (separated by ``|``):
200 - owner (empty if cluster, group name otherwise)
201 - standard, min, max instance specs; min and max instance specs are
202 separated between them by a semicolon, and can be specified multiple
203 times (min;max;min;max...); each of the specs contains the following
204 values separated by commas:
215 Backend specification: collect data directly from the *cluster* given
216 as an argument via RAPI. If the argument doesn't contain a colon (:),
217 then it is converted into a fully-built URL via prepending
218 ``https://`` and appending the default RAPI port, otherwise it is
219 considered a fully-specified URL and used as-is.
222 Backend specification: collect data directly from the master daemon,
223 which is to be contacted via LUXI (an internal Ganeti protocol). An
224 optional *path* argument is interpreted as the path to the unix socket
225 on which the master daemon listens; otherwise, the default path used
226 by Ganeti (configured at build time) is used.
228 -I|\--ialloc-src *path*
229 Backend specification: load data directly from an iallocator request
230 (as produced by Ganeti when doing an iallocator call). The iallocator
231 request is read from specified path.
233 \--simulate *description*
234 Backend specification: instead of using actual data, build an empty
235 cluster given a node description. The *description* parameter must be
236 a comma-separated list of five elements, describing in order:
238 - the allocation policy for this node group (*preferred*, *allocable*
239 or *unallocable*, or alternatively the short forms *p*, *a* or *u*)
240 - the number of nodes in the cluster
241 - the disk size of the nodes (default in mebibytes, units can be used)
242 - the memory size of the nodes (default in mebibytes, units can be used)
243 - the cpu core count for the nodes
244 - the spindle count for the nodes
246 An example description would be **preferred,20,100G,16g,4,2**
247 describing a 20-node cluster where each node has 100GB of disk space,
248 16GiB of memory, 4 CPU cores and 2 disk spindles. Note that all nodes
249 must have the same specs currently.
251 This option can be given multiple times, and each new use defines a
252 new node group. Hence different node groups can have different
253 allocation policies and node count/specifications.
256 Increase the output verbosity. Each usage of this option will
257 increase the verbosity (currently more than 2 doesn't make sense)
258 from the default of one.
261 Decrease the output verbosity. Each usage of this option will
262 decrease the verbosity (less than zero doesn't make sense) from the
266 Just show the program version and exit.
271 Some options accept not simply numerical values, but numerical values
272 together with a unit. By default, such unit-accepting options use
273 mebibytes. Using the lower-case letters of *m*, *g* and *t* (or their
274 longer equivalents of *mib*, *gib*, *tib*, for which case doesn't
275 matter) explicit binary units can be selected. Units in the SI system
276 can be selected using the upper-case letters of *M*, *G* and *T* (or
277 their longer equivalents of *MB*, *GB*, *TB*, for which case doesn't
280 More details about the difference between the SI and binary systems can
281 be read in the **units**\(7) man page.
286 The environment variable ``HTOOLS`` can be used instead of
287 renaming/symlinking the programs; simply set it to the desired role and
288 then the name of the program is no longer used.
290 .. vim: set textwidth=72 :