## root / man / htools.rst @ 54f834df

History | View | Annotate | Download (7.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 | d26d808a | Iustin Pop | **hspace** |

16 | d26d808a | Iustin Pop | cluster capacity computation |

17 | d26d808a | Iustin Pop | |

18 | d26d808a | Iustin Pop | **hail** |

19 | d26d808a | Iustin Pop | IAllocator plugin |

20 | d26d808a | Iustin Pop | |

21 | d26d808a | Iustin Pop | **hscan** |

22 | d26d808a | Iustin Pop | saves cluster state for later reuse |

23 | d26d808a | Iustin Pop | |

24 | d26d808a | Iustin Pop | |

25 | d26d808a | Iustin Pop | DESCRIPTION |

26 | d26d808a | Iustin Pop | ----------- |

27 | d26d808a | Iustin Pop | |

28 | d26d808a | Iustin Pop | |

29 | d26d808a | Iustin Pop | ``htools`` is a suite of tools designed to help with allocation/movement |

30 | d26d808a | Iustin Pop | of instances and balancing of Ganeti clusters. ``htools`` is also the |

31 | d26d808a | Iustin Pop | generic binary that must be symlinked or hardlinked under each tool's |

32 | d26d808a | Iustin Pop | name in order to perform the different functions. Alternatively, the |

33 | d26d808a | Iustin Pop | environment variable HTOOLS can be used to set the desired role. |

34 | d26d808a | Iustin Pop | |

35 | d26d808a | Iustin Pop | Installed as ``hbal``, it computes and optionally executes a suite of |

36 | d26d808a | Iustin Pop | instance moves in order to balance the cluster. |

37 | d26d808a | Iustin Pop | |

38 | d26d808a | Iustin Pop | Installed as ``hspace``, it computes how many additional instances can |

39 | d26d808a | Iustin Pop | be fit on a cluster, while maintaining N+1 status. It can run on models |

40 | d26d808a | Iustin Pop | of existing clusters or of simulated clusters. |

41 | d26d808a | Iustin Pop | |

42 | d26d808a | Iustin Pop | Installed as ``hail``, it acts as an IAllocator plugin, i.e. it is used |

43 | d26d808a | Iustin Pop | by Ganeti to compute new instance allocations and instance moves. |

44 | d26d808a | Iustin Pop | |

45 | d26d808a | Iustin Pop | Installed as ``hscan``, it scans the local or remote cluster state and |

46 | d26d808a | Iustin Pop | saves it to files which can later be reused by the other roles. |

47 | d26d808a | Iustin Pop | |

48 | d26d808a | Iustin Pop | COMMON OPTIONS |

49 | d26d808a | Iustin Pop | -------------- |

50 | d26d808a | Iustin Pop | |

51 | d26d808a | Iustin Pop | Options behave the same in all program modes, but not all program modes |

52 | d26d808a | Iustin Pop | support all options. Some common options are: |

53 | d26d808a | Iustin Pop | |

54 | d7731f51 | Iustin Pop | -p, --print-nodes |

55 | d7731f51 | Iustin Pop | Prints the node status, in a format designed to allow the user to |

56 | d7731f51 | Iustin Pop | understand the node's most important parameters. If the command in |

57 | d7731f51 | Iustin Pop | question makes a cluster transition (e.g. balancing or allocation), |

58 | d7731f51 | Iustin Pop | then usually both the initial and final node status is printed. |

59 | d7731f51 | Iustin Pop | |

60 | d7731f51 | Iustin Pop | It is possible to customise the listed information by passing a |

61 | d7731f51 | Iustin Pop | comma-separated list of field names to this option (the field list |

62 | d7731f51 | Iustin Pop | is currently undocumented), or to extend the default field list by |

63 | d7731f51 | Iustin Pop | prefixing the additional field list with a plus sign. By default, |

64 | d7731f51 | Iustin Pop | the node list will contain the following information: |

65 | d7731f51 | Iustin Pop | |

66 | d7731f51 | Iustin Pop | F |

67 | d7731f51 | Iustin Pop | a character denoting the status of the node, with '-' meaning an |

68 | d7731f51 | Iustin Pop | offline node, '*' meaning N+1 failure and blank meaning a good |

69 | d7731f51 | Iustin Pop | node |

70 | d7731f51 | Iustin Pop | |

71 | d7731f51 | Iustin Pop | Name |

72 | d7731f51 | Iustin Pop | the node name |

73 | d7731f51 | Iustin Pop | |

74 | d7731f51 | Iustin Pop | t_mem |

75 | d7731f51 | Iustin Pop | the total node memory |

76 | d7731f51 | Iustin Pop | |

77 | d7731f51 | Iustin Pop | n_mem |

78 | d7731f51 | Iustin Pop | the memory used by the node itself |

79 | d7731f51 | Iustin Pop | |

80 | d7731f51 | Iustin Pop | i_mem |

81 | d7731f51 | Iustin Pop | the memory used by instances |

82 | d7731f51 | Iustin Pop | |

83 | d7731f51 | Iustin Pop | x_mem |

84 | d7731f51 | Iustin Pop | amount memory which seems to be in use but cannot be determined |

85 | d7731f51 | Iustin Pop | why or by which instance; usually this means that the hypervisor |

86 | d7731f51 | Iustin Pop | has some overhead or that there are other reporting errors |

87 | d7731f51 | Iustin Pop | |

88 | d7731f51 | Iustin Pop | f_mem |

89 | d7731f51 | Iustin Pop | the free node memory |

90 | d7731f51 | Iustin Pop | |

91 | d7731f51 | Iustin Pop | r_mem |

92 | d7731f51 | Iustin Pop | the reserved node memory, which is the amount of free memory |

93 | d7731f51 | Iustin Pop | needed for N+1 compliance |

94 | d7731f51 | Iustin Pop | |

95 | d7731f51 | Iustin Pop | t_dsk |

96 | d7731f51 | Iustin Pop | total disk |

97 | d7731f51 | Iustin Pop | |

98 | d7731f51 | Iustin Pop | f_dsk |

99 | d7731f51 | Iustin Pop | free disk |

100 | d7731f51 | Iustin Pop | |

101 | d7731f51 | Iustin Pop | pcpu |

102 | d7731f51 | Iustin Pop | the number of physical cpus on the node |

103 | d7731f51 | Iustin Pop | |

104 | d7731f51 | Iustin Pop | vcpu |

105 | d7731f51 | Iustin Pop | the number of virtual cpus allocated to primary instances |

106 | d7731f51 | Iustin Pop | |

107 | d7731f51 | Iustin Pop | pcnt |

108 | d7731f51 | Iustin Pop | number of primary instances |

109 | d7731f51 | Iustin Pop | |

110 | d7731f51 | Iustin Pop | scnt |

111 | d7731f51 | Iustin Pop | number of secondary instances |

112 | d7731f51 | Iustin Pop | |

113 | d7731f51 | Iustin Pop | p_fmem |

114 | d7731f51 | Iustin Pop | percent of free memory |

115 | d7731f51 | Iustin Pop | |

116 | d7731f51 | Iustin Pop | p_fdsk |

117 | d7731f51 | Iustin Pop | percent of free disk |

118 | d7731f51 | Iustin Pop | |

119 | d7731f51 | Iustin Pop | r_cpu |

120 | d7731f51 | Iustin Pop | ratio of virtual to physical cpus |

121 | d7731f51 | Iustin Pop | |

122 | d7731f51 | Iustin Pop | lCpu |

123 | d7731f51 | Iustin Pop | the dynamic CPU load (if the information is available) |

124 | d7731f51 | Iustin Pop | |

125 | d7731f51 | Iustin Pop | lMem |

126 | d7731f51 | Iustin Pop | the dynamic memory load (if the information is available) |

127 | d7731f51 | Iustin Pop | |

128 | d7731f51 | Iustin Pop | lDsk |

129 | d7731f51 | Iustin Pop | the dynamic disk load (if the information is available) |

130 | d7731f51 | Iustin Pop | |

131 | d7731f51 | Iustin Pop | lNet |

132 | d7731f51 | Iustin Pop | the dynamic net load (if the information is available) |

133 | d7731f51 | Iustin Pop | |

134 | acd9fa11 | Iustin Pop | -t *datafile*, --text-data=*datafile* |

135 | acd9fa11 | Iustin Pop | Backend specification: the name of the file holding node and instance |

136 | acd9fa11 | Iustin Pop | information (if not collecting via RAPI or LUXI). This or one of the |

137 | acd9fa11 | Iustin Pop | other backends must be selected. The option is described in the man |

138 | acd9fa11 | Iustin Pop | page **htools**(1). |

139 | acd9fa11 | Iustin Pop | |

140 | acd9fa11 | Iustin Pop | The file should contain text data, line-based, with two empty lines |

141 | acd9fa11 | Iustin Pop | separating sections. The lines themselves are column-based, with the |

142 | acd9fa11 | Iustin Pop | pipe symbol (``|``) acting as separator. |

143 | acd9fa11 | Iustin Pop | |

144 | acd9fa11 | Iustin Pop | The first section contains group data, with two columns: |

145 | acd9fa11 | Iustin Pop | |

146 | acd9fa11 | Iustin Pop | - group name |

147 | acd9fa11 | Iustin Pop | - group uuid |

148 | acd9fa11 | Iustin Pop | |

149 | acd9fa11 | Iustin Pop | The second sections contains node data, with the following columns: |

150 | acd9fa11 | Iustin Pop | |

151 | acd9fa11 | Iustin Pop | - node name |

152 | acd9fa11 | Iustin Pop | - node total memory |

153 | acd9fa11 | Iustin Pop | - node free memory |

154 | acd9fa11 | Iustin Pop | - node total disk |

155 | acd9fa11 | Iustin Pop | - node free disk |

156 | acd9fa11 | Iustin Pop | - node physical cores |

157 | acd9fa11 | Iustin Pop | - offline field (as ``Y`` or ``N``) |

158 | acd9fa11 | Iustin Pop | - group UUID |

159 | acd9fa11 | Iustin Pop | |

160 | acd9fa11 | Iustin Pop | The third section contains instance data, with the fields: |

161 | acd9fa11 | Iustin Pop | |

162 | acd9fa11 | Iustin Pop | - instance name |

163 | acd9fa11 | Iustin Pop | - instance memory |

164 | acd9fa11 | Iustin Pop | - instance disk size |

165 | acd9fa11 | Iustin Pop | - instance vcpus |

166 | acd9fa11 | Iustin Pop | - instance status (in Ganeti's format, e.g. ``running`` or ``ERROR_down``) |

167 | acd9fa11 | Iustin Pop | - instance ``auto_balance`` flag (see man page **gnt-instance** (7)) |

168 | acd9fa11 | Iustin Pop | - instance primary node |

169 | acd9fa11 | Iustin Pop | - instance secondary node(s), if any |

170 | acd9fa11 | Iustin Pop | - instance disk type (e.g. ``plain`` or ``drbd``) |

171 | acd9fa11 | Iustin Pop | - instance tags |

172 | acd9fa11 | Iustin Pop | |

173 | acd9fa11 | Iustin Pop | The fourth and last section contains the cluster tags, with one tag |

174 | acd9fa11 | Iustin Pop | per line (no columns/no column processing). |

175 | acd9fa11 | Iustin Pop | |

176 | acd9fa11 | Iustin Pop | -m *cluster* |

177 | acd9fa11 | Iustin Pop | Backend specification: collect data directly from the *cluster* given |

178 | acd9fa11 | Iustin Pop | as an argument via RAPI. If the argument doesn't contain a colon (:), |

179 | acd9fa11 | Iustin Pop | then it is converted into a fully-built URL via prepending |

180 | acd9fa11 | Iustin Pop | ``https://`` and appending the default RAPI port, otherwise it is |

181 | acd9fa11 | Iustin Pop | considered a fully-specified URL and used as-is. |

182 | acd9fa11 | Iustin Pop | |

183 | acd9fa11 | Iustin Pop | -L [*path*] |

184 | acd9fa11 | Iustin Pop | Backend specification: collect data directly from the master daemon, |

185 | acd9fa11 | Iustin Pop | which is to be contacted via LUXI (an internal Ganeti protocol). An |

186 | acd9fa11 | Iustin Pop | optional *path* argument is interpreted as the path to the unix socket |

187 | acd9fa11 | Iustin Pop | on which the master daemon listens; otherwise, the default path used |

188 | acd9fa11 | Iustin Pop | by Ganeti (configured at build time) is used. |

189 | acd9fa11 | Iustin Pop | |

190 | acd9fa11 | Iustin Pop | --simulate *description* |

191 | acd9fa11 | Iustin Pop | Backend specification: instead of using actual data, build an empty |

192 | acd9fa11 | Iustin Pop | cluster given a node description. The *description* parameter must be |

193 | acd9fa11 | Iustin Pop | a comma-separated list of five elements, describing in order: |

194 | acd9fa11 | Iustin Pop | |

195 | acd9fa11 | Iustin Pop | - the allocation policy for this node group (*preferred*, *allocable* |

196 | acd9fa11 | Iustin Pop | or *unallocable*, or alternatively the short forms *p*, *a* or *u*) |

197 | acd9fa11 | Iustin Pop | - the number of nodes in the cluster |

198 | acd9fa11 | Iustin Pop | - the disk size of the nodes (default in mebibytes, units can be used) |

199 | acd9fa11 | Iustin Pop | - the memory size of the nodes (default in mebibytes, units can be used) |

200 | acd9fa11 | Iustin Pop | - the cpu core count for the nodes |

201 | acd9fa11 | Iustin Pop | |

202 | acd9fa11 | Iustin Pop | An example description would be **preferred,B20,100G,16g,4** |

203 | acd9fa11 | Iustin Pop | describing a 20-node cluster where each node has 100GB of disk |

204 | acd9fa11 | Iustin Pop | space, 16GiB of memory and 4 CPU cores. Note that all nodes must |

205 | acd9fa11 | Iustin Pop | have the same specs currently. |

206 | acd9fa11 | Iustin Pop | |

207 | acd9fa11 | Iustin Pop | This option can be given multiple times, and each new use defines a |

208 | acd9fa11 | Iustin Pop | new node group. Hence different node groups can have different |

209 | acd9fa11 | Iustin Pop | allocation policies and node count/specifications. |

210 | acd9fa11 | Iustin Pop | |

211 | d26d808a | Iustin Pop | -v, --verbose |

212 | d26d808a | Iustin Pop | Increase the output verbosity. Each usage of this option will |

213 | d26d808a | Iustin Pop | increase the verbosity (currently more than 2 doesn't make sense) |

214 | d26d808a | Iustin Pop | from the default of one. |

215 | d26d808a | Iustin Pop | |

216 | d26d808a | Iustin Pop | -q, --quiet |

217 | d26d808a | Iustin Pop | Decrease the output verbosity. Each usage of this option will |

218 | d26d808a | Iustin Pop | decrease the verbosity (less than zero doesn't make sense) from the |

219 | d26d808a | Iustin Pop | default of one. |

220 | d26d808a | Iustin Pop | |

221 | d26d808a | Iustin Pop | -V, --version |

222 | d26d808a | Iustin Pop | Just show the program version and exit. |

223 | d26d808a | Iustin Pop | |

224 | d26d808a | Iustin Pop | UNITS |

225 | d26d808a | Iustin Pop | ~~~~~ |

226 | d26d808a | Iustin Pop | |

227 | d26d808a | Iustin Pop | Some options accept not simply numerical values, but numerical values |

228 | d26d808a | Iustin Pop | together with a unit. By default, such unit-accepting options use |

229 | d26d808a | Iustin Pop | mebibytes. Using the lower-case letters of *m*, *g* and *t* (or their |

230 | d26d808a | Iustin Pop | longer equivalents of *mib*, *gib*, *tib*, for which case doesn't |

231 | d26d808a | Iustin Pop | matter) explicit binary units can be selected. Units in the SI system |

232 | d26d808a | Iustin Pop | can be selected using the upper-case letters of *M*, *G* and *T* (or |

233 | d26d808a | Iustin Pop | their longer equivalents of *MB*, *GB*, *TB*, for which case doesn't |

234 | d26d808a | Iustin Pop | matter). |

235 | d26d808a | Iustin Pop | |

236 | d26d808a | Iustin Pop | More details about the difference between the SI and binary systems can |

237 | d26d808a | Iustin Pop | be read in the *units(7)* man page. |

238 | d26d808a | Iustin Pop | |

239 | d26d808a | Iustin Pop | ENVIRONMENT |

240 | d26d808a | Iustin Pop | ----------- |

241 | d26d808a | Iustin Pop | |

242 | d26d808a | Iustin Pop | The environment variable ``HTOOLS`` can be used instead of |

243 | d26d808a | Iustin Pop | renaming/symlinking the programs; simply set it to the desired role and |

244 | d26d808a | Iustin Pop | then the name of the program is no longer used. |

245 | d26d808a | Iustin Pop | |

246 | d26d808a | Iustin Pop | .. vim: set textwidth=72 : |

247 | d26d808a | Iustin Pop | .. Local Variables: |

248 | d26d808a | Iustin Pop | .. mode: rst |

249 | d26d808a | Iustin Pop | .. fill-column: 72 |

250 | d26d808a | Iustin Pop | .. End: |