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>).
287 (Optionally) The output size (in bytes). If not specified, then the
288 template can choose a default size.
292 (Optionally) The timezone.
298 The template MAY print the disk type supported by this guest. Possible
299 values include C<ide>, C<virtio>, C<virtio-scsi>.
303 The template MAY print the minimum memory (RAM) required by this
304 guest. Abbreviations like C<1G> are supported.
308 The template MAY print the minimum disk space required by this guest.
309 Abbreviations like C<10G> are supported.
313 The template MAY print the network type supported by this guest.
314 Possible values include C<e1000>, C<virtio>.
318 The template MUST print C<hello> followed by a newline, and then exit
321 =item recommended-memory
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>
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).
333 The following environment variables are passed to the template:
343 The disk format (eg. C<qcow2>).
351 The size of the RAM in kilobytes.
355 The number of virtual CPUs.
365 =head1 ENVIRONMENT VARIABLES
371 May be used to override the default configuration file location
372 (C</etc/mclu.conf>). See L</CONFIGURATION FILE> above.
376 The path to the directory that contains template files. See
377 L</TEMPLATE FILES> above.
389 L<http://www.redhat.com/mailman/listinfo/virt-tools-list>
393 Richard W.M. Jones <rjones @ redhat . com>
397 (C) Copyright 2014-2015 Red Hat Inc.
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.
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.
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.