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