docs: Add description and examples.

diff --git a/mclu.pod b/mclu.pod
index 51d216e..aeff24b 100644 (file)
--- 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