3 mclu - Mini Cloud, a tiny, sane cloud
7 mclu [-f mclu.conf] [--options] [list|status|boot|...] [...]
13 C<mclu> (Mini Cloud, previously Mini Cluster) is probably the simplest
14 cloud management software possible.
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.
24 For a small cloud, we can throw out features that aren't needed:
25 multi-user/multi-tenant, failover, VLANs, a GUI.
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.
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.
38 Examine the state of the nodes (one node is switched on, three nodes
49 Bring up another node (using wake-on-LAN):
52 Waking up 74:d4:35:51:ab:86...
54 Start a new instance on node C<ham1>, based on the C<rawhide> guest
55 template, with up to 20G of disk space:
57 $ mclu boot rawhide ham1:test --size 20G
59 Connect to the graphical console of the new guest:
63 If your local DHCP server and DNS are connected then you can probably
64 connect to the new instance by doing:
74 Display brief help message and exit.
78 =item B<--config-file mclu.conf>
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
85 See also: L</CONFIGURATION FILE> below.
91 Enable verbose / debugging messages.
97 Display version number and exit.
105 =item B<mclu boot template [host:]name [--memory ..] [--vcpus ..]>
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.
111 The instance is created by running the template script. You can
112 control resources using the following options:
118 Open the serial console immediately after booting the guest. This is
119 the same as using the C<mclu console> subcommand, but quicker.
121 =item B<--memory nnG>
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>
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>
131 =item B<--timezone TZ>
133 Specify the timezone, eg. C<--timezone Europe/London>
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.
142 Open the graphical console immediately after booting the guest. This is
143 the same as using the C<mclu viewer> subcommand, but quicker.
147 =item B<mclu console [host:]guest>
149 Connect to the serial console console of the named guest.
151 =item B<mclu destroy [host:]guest>
153 Destroy the named guest.
155 Note this permanently deletes the guest and its data.
157 =item B<mclu list [--active] [--all] [--templates]>
159 List all active (running) guests and/or templates. You can use
160 the following options:
166 List only active (running) guests.
170 List active (running) guests, and templates. This is the default.
178 =item B<mclu off node|wildcard ...>
180 Switch the node(s) off. Wildcards can be used in place of hostnames.
182 mclu checks that no guests are running on the nodes. Migrate or shut
183 down the guests first.
185 =item B<mclu on node|wildcard ...>
187 Switch the node(s) on. Wildcards can be used in place of hostnames.
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
195 host0 mac=11:22:33:44:55:66
196 host1 mac=11:22:33:44:55:67
198 =item B<mclu reboot [host:]guest>
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.
207 =item B<mclu viewer [host:]guest>
209 Open the graphical console of the guest (using L<virt-viewer(1)>).
214 =head1 CONFIGURATION FILE
220 =head1 TEMPLATE FILES
222 Template files are shell scripts which the C<mclu> program calls to
223 perform various operations.
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).
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
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:
238 $ ./templates/rawhide.template probe
241 Templates should exit with code 2 if they don't know about a parameter:
243 $ ./templates/rawhide.template unknown
247 The current parameters are:
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.
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
264 The following environment variables are passed to the template:
270 The name of the base image. This is the output of the C<base-image>
275 The output format (eg. C<qcow2>).
279 The guest architecture (eg. "x86_64"). This is the output of the
280 C<guest-arch> probe. If the template doesn't provide that, it
281 defaults to the cluster node's host architecture.
293 (Optionally) The output size (in bytes). If not specified, then the
294 template can choose a default size.
298 (Optionally) The timezone.
304 The template MAY print the disk type supported by this guest. Possible
305 values include C<ide>, C<virtio>, C<virtio-scsi>.
309 The template MAY print the guest architecture.
311 If supplied, this acts as a hint when generating the XML in the C<mclu
312 boot> subcommand. The default is to assume the guest architecture is
313 the same as the cluster host on which the guest runs.
317 The template MAY print the minimum memory (RAM) required by this
318 guest. Abbreviations like C<1G> are supported.
322 The template MAY print the minimum disk space required by this guest.
323 Abbreviations like C<10G> are supported.
327 The template MAY print the network type supported by this guest.
328 Possible values include C<e1000>, C<virtio>.
332 The template MUST print C<hello> followed by a newline, and then exit
335 =item recommended-memory
337 The template MAY print the recommended amount of memory (RAM), used if
338 the user does not select any other value. Abbreviations like C<2G>
343 The template MAY specify custom libvirt XML. Usually you should
344 I<not> specify this. It is only used when you need very odd guest
345 configuration (especially when emulating other architectures).
347 The following environment variables are passed to the template:
357 The disk format (eg. C<qcow2>).
365 The size of the RAM in kilobytes.
369 The number of virtual CPUs.
379 =head1 ENVIRONMENT VARIABLES
385 May be used to override the default configuration file location
386 (C</etc/mclu.conf>). See L</CONFIGURATION FILE> above.
390 The path to the directory that contains template files. See
391 L</TEMPLATE FILES> above.
403 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
407 Richard W.M. Jones <rjones @ redhat . com>
411 (C) Copyright 2014-2015 Red Hat Inc.
413 This program is free software; you can redistribute it and/or modify
414 it under the terms of the GNU General Public License as published by
415 the Free Software Foundation; either version 2 of the License, or
416 (at your option) any later version.
418 This program is distributed in the hope that it will be useful,
419 but WITHOUT ANY WARRANTY; without even the implied warranty of
420 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
421 GNU General Public License for more details.
423 You should have received a copy of the GNU General Public License
424 along with this program; if not, write to the Free Software
425 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.