1 HTOOLS(1) Ganeti | Version @GANETI_VERSION@
2 ===========================================
7 htools - Cluster allocation and placement tools for Ganeti
16 cluster capacity computation
22 saves cluster state for later reuse
29 ``htools`` is a suite of tools designed to help with allocation/movement
30 of instances and balancing of Ganeti clusters. ``htools`` is also the
31 generic binary that must be symlinked or hardlinked under each tool's
32 name in order to perform the different functions. Alternatively, the
33 environment variable HTOOLS can be used to set the desired role.
35 Installed as ``hbal``, it computes and optionally executes a suite of
36 instance moves in order to balance the cluster.
38 Installed as ``hspace``, it computes how many additional instances can
39 be fit on a cluster, while maintaining N+1 status. It can run on models
40 of existing clusters or of simulated clusters.
42 Installed as ``hail``, it acts as an IAllocator plugin, i.e. it is used
43 by Ganeti to compute new instance allocations and instance moves.
45 Installed as ``hscan``, it scans the local or remote cluster state and
46 saves it to files which can later be reused by the other roles.
51 Options behave the same in all program modes, but not all program modes
52 support all options. Some common options are:
55 Prints the node status, in a format designed to allow the user to
56 understand the node's most important parameters. If the command in
57 question makes a cluster transition (e.g. balancing or allocation),
58 then usually both the initial and final node status is printed.
60 It is possible to customise the listed information by passing a
61 comma-separated list of field names to this option (the field list
62 is currently undocumented), or to extend the default field list by
63 prefixing the additional field list with a plus sign. By default,
64 the node list will contain the following information:
67 a character denoting the status of the node, with '-' meaning an
68 offline node, '*' meaning N+1 failure and blank meaning a good
78 the memory used by the node itself
81 the memory used by instances
84 amount memory which seems to be in use but cannot be determined
85 why or by which instance; usually this means that the hypervisor
86 has some overhead or that there are other reporting errors
92 the reserved node memory, which is the amount of free memory
93 needed for N+1 compliance
102 the number of physical cpus on the node
105 the number of virtual cpus allocated to primary instances
108 number of primary instances
111 number of secondary instances
114 percent of free memory
120 ratio of virtual to physical cpus
123 the dynamic CPU load (if the information is available)
126 the dynamic memory load (if the information is available)
129 the dynamic disk load (if the information is available)
132 the dynamic net load (if the information is available)
134 -t *datafile*, \--text-data=*datafile*
135 Backend specification: the name of the file holding node and instance
136 information (if not collecting via RAPI or LUXI). This or one of the
137 other backends must be selected. The option is described in the man
140 The file should contain text data, line-based, with two empty lines
141 separating sections. The lines themselves are column-based, with the
142 pipe symbol (``|``) acting as separator.
144 The first section contains group data, with two columns:
149 The second sections contains node data, with the following columns:
156 - node physical cores
157 - offline field (as ``Y`` or ``N``)
161 The third section contains instance data, with the fields:
167 - instance status (in Ganeti's format, e.g. ``running`` or ``ERROR_down``)
168 - instance ``auto_balance`` flag (see man page **gnt-instance** (7))
169 - instance primary node
170 - instance secondary node(s), if any
171 - instance disk type (e.g. ``plain`` or ``drbd``)
174 The fourth section contains the cluster tags, with one tag per line
175 (no columns/no column processing).
177 The fifth section contains the ipolicies of the cluster and the node
178 groups, in the following format (separated by ``|``):
180 - owner (empty if cluster, group name otherwise)
181 - standard, min, max instance specs, containing the following values
193 Backend specification: collect data directly from the *cluster* given
194 as an argument via RAPI. If the argument doesn't contain a colon (:),
195 then it is converted into a fully-built URL via prepending
196 ``https://`` and appending the default RAPI port, otherwise it is
197 considered a fully-specified URL and used as-is.
200 Backend specification: collect data directly from the master daemon,
201 which is to be contacted via LUXI (an internal Ganeti protocol). An
202 optional *path* argument is interpreted as the path to the unix socket
203 on which the master daemon listens; otherwise, the default path used
204 by Ganeti (configured at build time) is used.
206 \--simulate *description*
207 Backend specification: instead of using actual data, build an empty
208 cluster given a node description. The *description* parameter must be
209 a comma-separated list of five elements, describing in order:
211 - the allocation policy for this node group (*preferred*, *allocable*
212 or *unallocable*, or alternatively the short forms *p*, *a* or *u*)
213 - the number of nodes in the cluster
214 - the disk size of the nodes (default in mebibytes, units can be used)
215 - the memory size of the nodes (default in mebibytes, units can be used)
216 - the cpu core count for the nodes
218 An example description would be **preferred,B20,100G,16g,4**
219 describing a 20-node cluster where each node has 100GB of disk
220 space, 16GiB of memory and 4 CPU cores. Note that all nodes must
221 have the same specs currently.
223 This option can be given multiple times, and each new use defines a
224 new node group. Hence different node groups can have different
225 allocation policies and node count/specifications.
228 Increase the output verbosity. Each usage of this option will
229 increase the verbosity (currently more than 2 doesn't make sense)
230 from the default of one.
233 Decrease the output verbosity. Each usage of this option will
234 decrease the verbosity (less than zero doesn't make sense) from the
238 Just show the program version and exit.
243 Some options accept not simply numerical values, but numerical values
244 together with a unit. By default, such unit-accepting options use
245 mebibytes. Using the lower-case letters of *m*, *g* and *t* (or their
246 longer equivalents of *mib*, *gib*, *tib*, for which case doesn't
247 matter) explicit binary units can be selected. Units in the SI system
248 can be selected using the upper-case letters of *M*, *G* and *T* (or
249 their longer equivalents of *MB*, *GB*, *TB*, for which case doesn't
252 More details about the difference between the SI and binary systems can
253 be read in the *units(7)* man page.
258 The environment variable ``HTOOLS`` can be used instead of
259 renaming/symlinking the programs; simply set it to the desired role and
260 then the name of the program is no longer used.
262 .. vim: set textwidth=72 :