X-Git-Url: http://git.annexia.org/?p=mclu.git;a=blobdiff_plain;f=mclu.pod;h=63b9b2093540702028932ac36d61d32fc3b1c677;hp=45b9bd5a4de3edca88b73ad7dd13f97987e4f18a;hb=97b5c2a2402eef41726e54ed6797e8b7d3336058;hpb=f7d1a79773b8b04dfcd13c2dd2f6ae3b70d43663

diff --git a/mclu.pod b/mclu.pod
index 45b9bd5..63b9b20 100644
--- a/mclu.pod
+++ b/mclu.pod
@@ -10,10 +10,60 @@ mclu --help
 
 =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
 
@@ -48,9 +98,6 @@ Display version number and exit.
 
 =back
 
-
-
-
 =head1 SUBCOMMANDS
 
 =over 4
@@ -66,16 +113,35 @@ control resources using the following options:
 
 =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>
@@ -129,6 +195,10 @@ for each host:
  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
@@ -149,8 +219,170 @@ Open the graphical console of the guest (using L<virt-viewer(1)>).
 
 =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