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

diff --git a/mclu.pod b/mclu.pod
index 51d216e..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
 
@@ -224,6 +274,12 @@ probe.
 
 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.
@@ -248,6 +304,14 @@ template can choose a default size.
 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
@@ -258,6 +322,14 @@ guest.  Abbreviations like C<1G> are supported.
 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.
@@ -274,6 +346,42 @@ 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