=head1 DESCRIPTION
+C<mclu> (Mini Cloud, previously Mini Cluster) is probably the simplest
+cloud management software possible.
+Cloud management doesn't require a daemon running on each node. We
+already have L<sshd(8)> for secure access, and L<libvirtd(8)> to
+manage the state of the guests. On most Linux systems, those are
+running out of the box. That is sufficient to manage all te state we
+care about. C<mclu> just goes out and queries each node for that
+information when it needs it (in parallel of course). Nodes that are
+switched off are handled by ignoring them.
+For a small cloud, we can throw out features that aren't needed:
+multi-user/multi-tenant, failover, VLANs, a GUI.
+C<mclu> is essentially the smallest sensible interface to parallel
+libvirt over ssh. There are some extra features, such as the ability
+to boot VMs from templates, but those are kept as minimal as possible.
+C<mclu> is good for small clouds from 2 - 10 Linux nodes, that are
+managed by a single user, where everything is located at a single
+location on a single network, where you are happy to hack on small
+shell scripts and manage everything from the command line.
+
+=head2 EXAMPLES
+
+Examine the state of the nodes (one node is switched on, three nodes
+are off):
+
+ $ mclu status
+ ham0 on
+ total: 8pcpus 30.9G
+ free: 29.9G
+ ham1 off
+ ham2 off
+ ham3 off
+
+Bring up another node (using wake-on-LAN):
+
+ $ mclu on ham1
+ Waking up 74:d4:35:51:ab:86...
+
+Start a new instance on node C<ham1>, based on the C<rawhide> guest
+template, with up to 20G of disk space:
+
+ $ mclu boot rawhide ham1:test --size 20G
+
+Connect to the graphical console of the new guest:
+
+ $ mclu viewer test
+
+If your local DHCP server and DNS are connected then you can probably
+connect to the new instance by doing:
+
+ $ ssh test
=head1 GLOBAL OPTIONS
=back
-
-
-
=head1 SUBCOMMANDS
=over 4
=over 4
+=item B<--console>
+
+Open the serial console immediately after booting the guest. This is
+the same as using the C<mclu console> subcommand, but quicker.
+
=item B<--memory nnG>
Specify the amount of memory (RAM) to give this guest. You can use
-a number followed by a unit, eg. C<--memory=4G>
+a number followed by a unit, eg. C<--memory 4G>
+
+=item B<--size nnG>
+
+Specify the amount of disk space to give this guest. You can use
+a number followed by a unit, eg. C<--size 20G>
+
+=item B<--timezone TZ>
+
+Specify the timezone, eg. C<--timezone Europe/London>
=item B<--vcpus N>
Specify the number of virtual CPUs to give to the guest. The default
is the number of physical CPUs, but not more than 4.
+=item B<--viewer>
+
+Open the graphical console immediately after booting the guest. This is
+the same as using the C<mclu viewer> subcommand, but quicker.
+
=back
+=item B<mclu console [host:]guest>
+
+Connect to the serial console console of the named guest.
+
+=item B<mclu destroy [host:]guest>
+
+Destroy the named guest.
+
+Note this permanently deletes the guest and its data.
+
=item B<mclu list [--active] [--all] [--templates]>
List all active (running) guests and/or templates. You can use
host0 mac=11:22:33:44:55:66
host1 mac=11:22:33:44:55:67
+=item B<mclu reboot [host:]guest>
+
+Reboot the guest.
+
=item B<mclu status>
Display the status of the cloud. This shows you which nodes are on
and off, and the amount of resources used and free on each node.
+=item B<mclu viewer [host:]guest>
+
+Open the graphical console of the guest (using L<virt-viewer(1)>).
+
=back
=head1 TEMPLATE FILES
+Template files are shell scripts which the C<mclu> program calls to
+perform various operations.
+
+Template files must have the extension C<.template>, must be
+executable (C<chmod +x *.template>), and they must live in the
+template directory (usually found through the C<$MCLU_PATH>
+environment variable).
+
+Several template files are supplied with mclu sources, and it's a good
+idea to consult those for examples and when creating your own
+templates.
+
+C<mclu> runs the template with a single parameter in order to "query"
+the template. All templates must support the C<probe> parameter,
+which is used to test that the file is a template:
+
+ $ ./templates/rawhide.template probe
+ hello
+
+Templates should exit with code 2 if they don't know about a parameter:
+
+ $ ./templates/rawhide.template unknown
+ $ echo $?
+ 2
+
+The current parameters are:
+
+=over 4
+
+=item base-image
+
+The template MUST print the name of the image that it builds. The
+meaning of this generally follows the conventions of
+L<virt-builder(1)>, if virt-builder is used by the template.
+
+=item build
+
+The template MUST build a disk image. Because the C<template build>
+command could run on any node in the cluster, it won't necessarily
+have access to other local files on the same node that C<mclu> is
+running on.
+
+The following environment variables are passed to the template:
+
+=over 4
+
+=item C<$base_image>
+
+The name of the base image. This is the output of the C<base-image>
+probe.
+
+=item C<$format>
+The output format (eg. C<qcow2>).
+=item C<$guest_arch>
+
+The guest architecture (eg. "x86_64"). This is the output of the
+C<guest-arch> probe. If the template doesn't provide that, it
+defaults to the cluster node's host architecture.
+
+=item C<$name>
+
+The hostname.
+
+=item C<$output>
+
+The output file.
+
+=item C<$size>
+
+(Optionally) The output size (in bytes). If not specified, then the
+template can choose a default size.
+
+=item C<$timezone>
+
+(Optionally) The timezone.
+
+=back
+
+=item disk-bus
+
+The template MAY print the disk type supported by this guest. Possible
+values include C<ide>, C<virtio>, C<virtio-scsi>.
+
+=item guest-arch
+
+The template MAY print the guest architecture.
+
+If supplied, this acts as a hint when generating the XML in the C<mclu
+boot> subcommand. The default is to assume the guest architecture is
+the same as the cluster host on which the guest runs.
+
+=item minimum-memory
+
+The template MAY print the minimum memory (RAM) required by this
+guest. Abbreviations like C<1G> are supported.
+
+=item minimum-size
+
+The template MAY print the minimum disk space required by this guest.
+Abbreviations like C<10G> are supported.
+
+=item needs-external-kernel
+
+The template MAY print C<yes> or C<1>. If it does so then after the
+guest has been built, L<virt-get-kernel(1)> is run to extract the
+kernel and initrd from the guest, and these are used to boot the guest
+with an external kernel and initrd (ie. using the libvirt
+C<E<lt>kernelE<gt>> and C<E<lt>initrdE<gt>> directives).
+
+=item network-model
+
+The template MAY print the network type supported by this guest.
+Possible values include C<e1000>, C<virtio>.
+
+=item probe
+
+The template MUST print C<hello> followed by a newline, and then exit
+with code 0.
+
+=item recommended-memory
+
+The template MAY print the recommended amount of memory (RAM), used if
+the user does not select any other value. Abbreviations like C<2G>
+are supported.
+
+=item xml
+
+The template MAY specify custom libvirt XML. Usually you should
+I<not> specify this. It is only used when you need very odd guest
+configuration (especially when emulating other architectures).
+
+The following environment variables are passed to the template:
+
+=over 4
+
+=item C<$name>
+
+The guest name.
+
+=item C<$format>
+
+The disk format (eg. C<qcow2>).
+
+=item C<$output>
+
+The disk file name.
+
+=item C<$memory_kb>
+
+The size of the RAM in kilobytes.
+
+=item C<$vcpus>
+
+The number of virtual CPUs.
+
+=item C<$mac_addr>
+
+The MAC address.
+
+=back
+
+=back
=head1 ENVIRONMENT VARIABLES
git.annexia.org / mclu.git / blobdiff