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