boot: Allow template to specify custom libvirt XML.
[mclu.git] / mclu.pod
1 =head1 NAME
2
3  mclu - Mini Cloud, a tiny, sane cloud
4
5 =head1 SUMMARY
6
7 mclu [-f mclu.conf] [--options] [list|status|boot|...] [...]
8
9 mclu --help
10
11 =head1 DESCRIPTION
12
13 C<mclu> (Mini Cloud, previously Mini Cluster) is probably the simplest
14 cloud management software possible.
15
16 Cloud management doesn't require a daemon running on each node.  We
17 already have L<sshd(8)> for secure access, and L<libvirtd(8)> to
18 manage the state of the guests.  On most Linux systems, those are
19 running out of the box.  That is sufficient to manage all te state we
20 care about.  C<mclu> just goes out and queries each node for that
21 information when it needs it (in parallel of course).  Nodes that are
22 switched off are handled by ignoring them.
23
24 For a small cloud, we can throw out features that aren't needed:
25 multi-user/multi-tenant, failover, VLANs, a GUI.
26
27 C<mclu> is essentially the smallest sensible interface to parallel
28 libvirt over ssh.  There are some extra features, such as the ability
29 to boot VMs from templates, but those are kept as minimal as possible.
30
31 C<mclu> is good for small clouds from 2 - 10 Linux nodes, that are
32 managed by a single user, where everything is located at a single
33 location on a single network, where you are happy to hack on small
34 shell scripts and manage everything from the command line.
35
36 =head2 EXAMPLES
37
38 Examine the state of the nodes (one node is switched on, three nodes
39 are off):
40
41  $ mclu status
42  ham0                   on
43                           total: 8pcpus 30.9G
44                            free: 29.9G
45  ham1                   off
46  ham2                   off
47  ham3                   off
48
49 Bring up another node (using wake-on-LAN):
50
51  $ mclu on ham1
52  Waking up 74:d4:35:51:ab:86...
53
54 Start a new instance on node C<ham1>, based on the C<rawhide> guest
55 template, with up to 20G of disk space:
56
57  $ mclu boot rawhide ham1:test --size 20G
58
59 Connect to the graphical console of the new guest:
60
61  $ mclu viewer test
62
63 If your local DHCP server and DNS are connected then you can probably
64 connect to the new instance by doing:
65
66  $ ssh test
67
68 =head1 GLOBAL OPTIONS
69
70 =over 4
71
72 =item B<--help>
73
74 Display brief help message and exit.
75
76 =item B<-f mclu.conf>
77
78 =item B<--config-file mclu.conf>
79
80 Specify the path to the configuration file.  If this command option is
81 I<not> given, then the environment variable C<MCLU_CONFIG> is used,
82 and if that environment variable is not set then C</etc/mclu.conf> is
83 used.
84
85 See also: L</CONFIGURATION FILE> below.
86
87 =item B<-v>
88
89 =item B<--verbose>
90
91 Enable verbose / debugging messages.
92
93 =item B<-V>
94
95 =item B<--version>
96
97 Display version number and exit.
98
99 =back
100
101 =head1 SUBCOMMANDS
102
103 =over 4
104
105 =item B<mclu boot template [host:]name [--memory ..] [--vcpus ..]>
106
107 Boot (create) a new instance from B<template>.  It will be started on
108 B<host> and named B<name>.  If the C<host:> prefix is not given then
109 it is started on the first host that has sufficient free memory.
110
111 The instance is created by running the template script.  You can
112 control resources using the following options:
113
114 =over 4
115
116 =item B<--console>
117
118 Open the serial console immediately after booting the guest.  This is
119 the same as using the C<mclu console> subcommand, but quicker.
120
121 =item B<--memory nnG>
122
123 Specify the amount of memory (RAM) to give this guest.  You can use
124 a number followed by a unit, eg. C<--memory 4G>
125
126 =item B<--size nnG>
127
128 Specify the amount of disk space to give this guest.  You can use
129 a number followed by a unit, eg. C<--size 20G>
130
131 =item B<--timezone TZ>
132
133 Specify the timezone, eg. C<--timezone Europe/London>
134
135 =item B<--vcpus N>
136
137 Specify the number of virtual CPUs to give to the guest.  The default
138 is the number of physical CPUs, but not more than 4.
139
140 =item B<--viewer>
141
142 Open the graphical console immediately after booting the guest.  This is
143 the same as using the C<mclu viewer> subcommand, but quicker.
144
145 =back
146
147 =item B<mclu console [host:]guest>
148
149 Connect to the serial console console of the named guest.
150
151 =item B<mclu destroy [host:]guest>
152
153 Destroy the named guest.
154
155 Note this permanently deletes the guest and its data.
156
157 =item B<mclu list [--active] [--all] [--templates]>
158
159 List all active (running) guests and/or templates.  You can use
160 the following options:
161
162 =over 4
163
164 =item B<--active>
165
166 List only active (running) guests.
167
168 =item B<--all>
169
170 List active (running) guests, and templates.  This is the default.
171
172 =item B<--templates>
173
174 List only templates.
175
176 =back
177
178 =item B<mclu off node|wildcard ...>
179
180 Switch the node(s) off.  Wildcards can be used in place of hostnames.
181
182 mclu checks that no guests are running on the nodes.  Migrate or shut
183 down the guests first.
184
185 =item B<mclu on node|wildcard ...>
186
187 Switch the node(s) on.  Wildcards can be used in place of hostnames.
188
189 This requires Wake-on-LAN support, both on the target host and in the
190 mclu configuration.  mclu must have been compiled with the L<wol(1)>
191 client installed, and the C<mclu.conf> file must list a MAC address
192 for each host:
193
194  [nodes]
195  host0 mac=11:22:33:44:55:66
196  host1 mac=11:22:33:44:55:67
197
198 =item B<mclu reboot [host:]guest>
199
200 Reboot the guest.
201
202 =item B<mclu status>
203
204 Display the status of the cloud.  This shows you which nodes are on
205 and off, and the amount of resources used and free on each node.
206
207 =item B<mclu viewer [host:]guest>
208
209 Open the graphical console of the guest (using L<virt-viewer(1)>).
210
211 =back
212
213
214 =head1 CONFIGURATION FILE
215
216
217
218
219
220 =head1 TEMPLATE FILES
221
222 Template files are shell scripts which the C<mclu> program calls to
223 perform various operations.
224
225 Template files must have the extension C<.template>, must be
226 executable (C<chmod +x *.template>), and they must live in the
227 template directory (usually found through the C<$MCLU_PATH>
228 environment variable).
229
230 Several template files are supplied with mclu sources, and it's a good
231 idea to consult those for examples and when creating your own
232 templates.
233
234 C<mclu> runs the template with a single parameter in order to "query"
235 the template.  All templates must support the C<probe> parameter,
236 which is used to test that the file is a template:
237
238  $ ./templates/rawhide.template probe
239  hello
240
241 Templates should exit with code 2 if they don't know about a parameter:
242
243  $ ./templates/rawhide.template unknown
244  $ echo $?
245  2
246
247 The current parameters are:
248
249 =over 4
250
251 =item base-image
252
253 The template MUST print the name of the image that it builds.  The
254 meaning of this generally follows the conventions of
255 L<virt-builder(1)>, if virt-builder is used by the template.
256
257 =item build
258
259 The template MUST build a disk image.  Because the C<template build>
260 command could run on any node in the cluster, it won't necessarily
261 have access to other local files on the same node that C<mclu> is
262 running on.
263
264 The following environment variables are passed to the template:
265
266 =over 4
267
268 =item C<$base_image>
269
270 The name of the base image.  This is the output of the C<base-image>
271 probe.
272
273 =item C<$format>
274
275 The output format (eg. C<qcow2>).
276
277 =item C<$name>
278
279 The hostname.
280
281 =item C<$output>
282
283 The output file.
284
285 =item C<$size>
286
287 (Optionally) The output size (in bytes).  If not specified, then the
288 template can choose a default size.
289
290 =item C<$timezone>
291
292 (Optionally) The timezone.
293
294 =back
295
296 =item disk-bus
297
298 The template MAY print the disk type supported by this guest.  Possible
299 values include C<ide>, C<virtio>, C<virtio-scsi>.
300
301 =item minimum-memory
302
303 The template MAY print the minimum memory (RAM) required by this
304 guest.  Abbreviations like C<1G> are supported.
305
306 =item minimum-size
307
308 The template MAY print the minimum disk space required by this guest.
309 Abbreviations like C<10G> are supported.
310
311 =item network-model
312
313 The template MAY print the network type supported by this guest.
314 Possible values include C<e1000>, C<virtio>.
315
316 =item probe
317
318 The template MUST print C<hello> followed by a newline, and then exit
319 with code 0.
320
321 =item recommended-memory
322
323 The template MAY print the recommended amount of memory (RAM), used if
324 the user does not select any other value.  Abbreviations like C<2G>
325 are supported.
326
327 =item xml
328
329 The template MAY specify custom libvirt XML.  Usually you should
330 I<not> specify this.  It is only used when you need very odd guest
331 configuration (especially when emulating other architectures).
332
333 The following environment variables are passed to the template:
334
335 =over 4
336
337 =item C<$name>
338
339 The guest name.
340
341 =item C<$format>
342
343 The disk format (eg. C<qcow2>).
344
345 =item C<$output>
346
347 The disk file name.
348
349 =item C<$memory_kb>
350
351 The size of the RAM in kilobytes.
352
353 =item C<$vcpus>
354
355 The number of virtual CPUs.
356
357 =item C<$mac_addr>
358
359 The MAC address.
360
361 =back
362
363 =back
364
365 =head1 ENVIRONMENT VARIABLES
366
367 =over 4
368
369 =item C<MCLU_CONFIG>
370
371 May be used to override the default configuration file location
372 (C</etc/mclu.conf>).  See L</CONFIGURATION FILE> above.
373
374 =item C<MCLU_PATH>
375
376 The path to the directory that contains template files.  See
377 L</TEMPLATE FILES> above.
378
379 =back
380
381 =head1 FILES
382
383
384
385
386 =head1 SEE ALSO
387
388 L<virt-builder(1)>,
389 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
390
391 =head1 AUTHORS
392
393 Richard W.M. Jones <rjones @ redhat . com>
394
395 =head1 COPYRIGHT
396
397 (C) Copyright 2014-2015 Red Hat Inc.
398
399 This program is free software; you can redistribute it and/or modify
400 it under the terms of the GNU General Public License as published by
401 the Free Software Foundation; either version 2 of the License, or
402 (at your option) any later version.
403
404 This program is distributed in the hope that it will be useful,
405 but WITHOUT ANY WARRANTY; without even the implied warranty of
406 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
407 GNU General Public License for more details.
408
409 You should have received a copy of the GNU General Public License
410 along with this program; if not, write to the Free Software
411 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.