README

   1 mclu (mini cluster) is a virtualization cluster manager.
   2
   3 The key features:
   4
   5  - Entirely command line driven.
   6
   7  - No required dependencies except libvirt and ssh.
   8
   9  - Only designed for tiny clusters (up to around 10 hosts).
  10
  11  - Nothing to install on the nodes except libvirtd and sshd.
  12
  13  - Single, simple configuration file.
  14
  15 Example commands
  16 ----------------------------------------------------------------------
  17
  18    mclu status                   Display status of the cluster
  19    mclu list                     List all virtual machines on the cluster
  20    mclu wake ham0                Wake up node 'ham0' in the cluster
  21    mclu shutdown ham0            Shut down node 'ham0' in the cluster
  22    mclu start ham0:vm            Start vm on node 'ham0'
  23    mclu stop ham0:*              Stop all VMs on node 'ham0'
  24    mclu migrate *:* ham2:        Live migrate all VMs to 'ham2'
  25    mclu build ham3:vm fedora-20  Build and run a new Fedora 20 VM on node 'ham3'
  26    mclu console ham3:fedora-20   Show me the serial console of a VM
  27    mclu viewer ham3:fedora-20    Show me the graphical console of a VM
  28    mclu info                     Print general configuration information
  29    mclu --help                   Print help on all commands
  30
  31 Configuration notes
  32 ----------------------------------------------------------------------
  33
  34 mclu is based around the idea that you have a small collection of
  35 fairly similar "nodes".  Ideally they would be identical nodes, if you
  36 want live migration to work seamlessly, but they don't have to be.
  37
  38 Here is a picture of the cluster that I run mclu on:
  39 http://rwmj.wordpress.com/2014/04/28/caseless-virtualization-cluster-part-5/#content
  40
  41 The nodes can be up or down.  mclu deals transparently with nodes
  42 being switched off.  If you configure wake-on-LAN (usually a BIOS
  43 setting) then mclu will be able to wake up nodes.
  44
  45 There is also one "control" node, which could be your laptop or could
  46 be one of the cluster nodes.  This is where you run the 'mclu'
  47 command, and also where the single configuration file is located
  48 (mclu.conf, usually located in /etc/mclu).  The guest libvirt XML
  49 files are also stored on the control node (usually /etc/mclu/xmls).
  50
  51 Each node must be accessible from the control node over ssh.  Each
  52 node must be running the libvirt daemon (libvirtd).
  53
  54 mclu uses a mix of ssh commands and remote libvirt to manage the
  55 nodes.  You should configure ssh so it can access the nodes without
  56 needing passwords (eg. using ssh-agent).  If you use the default
  57 libvirt URI (see config file) then you also need to set up
  58 passwordless root ssh access to the nodes; there are other ways to
  59 configure this, eg. opening the libvirtd port on each node, but they
  60 are probably not as secure.
  61
  62 Each node, including the control node, must have access to shared
  63 storage where the guest disk images are stored.  The easiest way to do
  64 this is to export /var/lib/libvirt/images from one machine and
  65 NFS-mount it on all the nodes (and also to have a nice fast network).
  66 Cluster filesystems are another possibility.  mclu does NOT support
  67 non-shared storage nor storage migration.
  68
  69 Guests run on a single node at a time.  You can list/start/stop/
  70 migrate them using mclu.  The requirement for a guest to be running on
  71 a single node may be enforced if you run libvirt sanlock or virtlockd.
  72 This requires further configuration, see:
  73 http://libvirt.org/locking.html
  74 https://rwmj.wordpress.com/2014/05/08/setting-up-virtlockd-on-nfs/#content
  75
  76 If sanlock/virtlockd is not running then mclu will try its best not to
  77 have the guest running in two places at once (if it happens, this will
  78 cause permanent disk corruption in the guest).
  79
  80 For guest live migration to work transparently, you will probably want
  81 to configure libvirt bridged networking and open firewall ports
  82 49152-49215 on every node.
  83
  84 Bridged networking means that each guest appears as a local machine on
  85 your network, and if it migrates then network connections will not be
  86 interrupted.  See:
  87 http://wiki.libvirt.org/page/Networking#Bridged_networking_.28aka_.22shared_physical_device.22.29
  88
  89 The firewall ports have to be opened because libvirt cannot (yet?)  do
  90 fully managed migration over two SSH connections (even though the
  91 documentation says it can).  Hopefully they will fix this soon.
  92
  93 Dependencies
  94 ----------------------------------------------------------------------
  95
  96 To get a full list of the required and optional dependencies, look at:
  97
  98  - configure.ac
  99  - mclu.spec.in
 100
 101 Building it
 102 ----------------------------------------------------------------------
 103
 104 If building straight from git, then do:
 105
 106   autoreconf -i
 107
 108 To build:
 109
 110   ./configure --prefix /usr --sysconfdir /etc
 111   make
 112
 113 To run without installing:
 114
 115  - Edit the configuration file (mclu.conf).
 116
 117  - Run commands such as:
 118
 119    ./run status
 120    ./run list
 121
 122 To install:
 123
 124  - sudo make install
 125
 126  - Edit the configuration file (/etc/mclu/mclu.conf).
 127
 128  - Run commands such as:
 129
 130    mclu status
 131    mclu list
 132
 133 Developer information
 134 ----------------------------------------------------------------------
 135
 136 The license is GPLv2+.
 137
 138 The git repo is:
 139
 140   http://git.annexia.org/?p=mclu.git;a=summary
 141
 142 There is no mclu mailing list.  Send patches to the virt-tools mailing list:
 143
 144   http://www.redhat.com/mailman/listinfo/virt-tools-list