From 50fd3ff80dbb76b1cf02e791cf8b3747ddaeeb7b Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Fri, 9 May 2014 10:07:08 +0100 Subject: [PATCH] Move configuration documentation to separate file, and expand. --- CONFIGURATION | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile.am | 2 +- README | 59 +------------------------------------ mclu.spec.in | 2 +- 4 files changed, 98 insertions(+), 60 deletions(-) create mode 100644 CONFIGURATION diff --git a/CONFIGURATION b/CONFIGURATION new file mode 100644 index 0000000..bbd7be1 --- /dev/null +++ b/CONFIGURATION @@ -0,0 +1,95 @@ +Configuring mclu +---------------- + +Introduction +------------ + +mclu is based around the idea that you have a small collection of +fairly similar "nodes". Ideally they would be identical nodes, if you +want live migration to work seamlessly, but they don't have to be. + +Here is a picture of the cluster that I run mclu on: +http://rwmj.wordpress.com/2014/04/28/caseless-virtualization-cluster-part-5/#content + +Nodes, control node, NFS server +------------------------------- + +There is also one "control" node, which could be your laptop or could +be one of the cluster nodes. This is where you run the 'mclu' +command, and also where the single configuration file is located +(mclu.conf, usually located in /etc/mclu). + +Each node must be accessible from the control node over ssh. Each +node must be running the libvirt daemon (libvirtd). + +mclu uses a mix of ssh commands and remote libvirt to manage the +nodes. You should configure ssh so it can access the nodes without +needing passwords (eg. using ssh-agent). If you use the default +libvirt URI (see config file) then you also need to set up +passwordless root ssh access to the nodes; there are other ways to +configure this, eg. opening the libvirtd port on each node, but they +are probably not as secure. + +Each node, including the control node, must have access to shared +storage where the guest disk images are stored. The easiest way to do +this is to export /var/lib/libvirt/images from one machine and +NFS-mount it on all the nodes (and also to have a nice fast network). +Cluster filesystems are another possibility. mclu does NOT support +non-shared storage nor storage migration. + +Wake-on-LAN +----------- + +The nodes can be up or down. mclu deals transparently with nodes +being switched off. If you configure wake-on-LAN (usually a BIOS +setting) then mclu will be able to wake up nodes. + +Running guests +-------------- + +The guest libvirt XML files are also stored on the control node +(usually /etc/mclu/xmls). Guests are created as transient, which +means the libvirt daemon running on each node does not have a +persistent configuration of any guest. + +Guests run on a single node at a time. You can list/start/stop/ +migrate them using mclu. The requirement for a guest to be running on +a single node may be enforced if you run libvirt sanlock or virtlockd. +This requires further configuration, see: +http://libvirt.org/locking.html +https://rwmj.wordpress.com/2014/05/08/setting-up-virtlockd-on-nfs/#content + +If sanlock/virtlockd is not running then mclu will try its best not to +have the guest running in two places at once (if it happens, this will +cause permanent disk corruption in the guest). + +Migration +--------- + +For guest live migration to work transparently, you will probably want +to configure libvirt bridged networking and open firewall ports +49152-49215 on every node. + +Bridged networking means that each guest appears as a local machine on +your network, and if it migrates then network connections will not be +interrupted. See: +http://wiki.libvirt.org/page/Networking#Bridged_networking_.28aka_.22shared_physical_device.22.29 + +The firewall ports have to be opened because libvirt cannot (yet?) do +fully managed migration over two SSH connections (even though the +documentation says it can). Hopefully they will fix this soon. + +Editing guest configuration or disk images +------------------------------------------ + +The guest configuration (libvirt XML) is stored in the xmls directory +(usually /etc/mclu/xmls). You can edit this file directly if you want. +Changes will not take effect until the guest is restarted. + +The guest disk images are located in the images directory (usually +/var/lib/libvirt/images). You can use libguestfs against these in +read-only mode (or read-write mode PROVIDED the guest is not running). + +You can also create or import guests by dropping an XML file and an +image into those directories. (But it might be easier to use the +'mclu build' and 'mclu import' subcommands). diff --git a/Makefile.am b/Makefile.am index 4447916..a1ae11d 100644 --- a/Makefile.am +++ b/Makefile.am @@ -18,7 +18,7 @@ ACLOCAL_AMFLAGS = -I m4 # Why doesn't automake include _SCRIPTS and _DATA ...? -EXTRA_DIST = mclu.spec $(pkgdata_SCRIPTS) $(conf_DATA) +EXTRA_DIST = CONFIGURATION mclu.spec $(pkgdata_SCRIPTS) $(conf_DATA) # This rule just ensures that the wrapper binary and Python files get # installed when we do 'make install'. diff --git a/README b/README index 65aa631..f9feeb1 100644 --- a/README +++ b/README @@ -31,64 +31,7 @@ Example commands Configuration notes ---------------------------------------------------------------------- -mclu is based around the idea that you have a small collection of -fairly similar "nodes". Ideally they would be identical nodes, if you -want live migration to work seamlessly, but they don't have to be. - -Here is a picture of the cluster that I run mclu on: -http://rwmj.wordpress.com/2014/04/28/caseless-virtualization-cluster-part-5/#content - -The nodes can be up or down. mclu deals transparently with nodes -being switched off. If you configure wake-on-LAN (usually a BIOS -setting) then mclu will be able to wake up nodes. - -There is also one "control" node, which could be your laptop or could -be one of the cluster nodes. This is where you run the 'mclu' -command, and also where the single configuration file is located -(mclu.conf, usually located in /etc/mclu). The guest libvirt XML -files are also stored on the control node (usually /etc/mclu/xmls). - -Each node must be accessible from the control node over ssh. Each -node must be running the libvirt daemon (libvirtd). - -mclu uses a mix of ssh commands and remote libvirt to manage the -nodes. You should configure ssh so it can access the nodes without -needing passwords (eg. using ssh-agent). If you use the default -libvirt URI (see config file) then you also need to set up -passwordless root ssh access to the nodes; there are other ways to -configure this, eg. opening the libvirtd port on each node, but they -are probably not as secure. - -Each node, including the control node, must have access to shared -storage where the guest disk images are stored. The easiest way to do -this is to export /var/lib/libvirt/images from one machine and -NFS-mount it on all the nodes (and also to have a nice fast network). -Cluster filesystems are another possibility. mclu does NOT support -non-shared storage nor storage migration. - -Guests run on a single node at a time. You can list/start/stop/ -migrate them using mclu. The requirement for a guest to be running on -a single node may be enforced if you run libvirt sanlock or virtlockd. -This requires further configuration, see: -http://libvirt.org/locking.html -https://rwmj.wordpress.com/2014/05/08/setting-up-virtlockd-on-nfs/#content - -If sanlock/virtlockd is not running then mclu will try its best not to -have the guest running in two places at once (if it happens, this will -cause permanent disk corruption in the guest). - -For guest live migration to work transparently, you will probably want -to configure libvirt bridged networking and open firewall ports -49152-49215 on every node. - -Bridged networking means that each guest appears as a local machine on -your network, and if it migrates then network connections will not be -interrupted. See: -http://wiki.libvirt.org/page/Networking#Bridged_networking_.28aka_.22shared_physical_device.22.29 - -The firewall ports have to be opened because libvirt cannot (yet?) do -fully managed migration over two SSH connections (even though the -documentation says it can). Hopefully they will fix this soon. +See `CONFIGURATION'. Dependencies ---------------------------------------------------------------------- diff --git a/mclu.spec.in b/mclu.spec.in index 3ee0ab7..8a28572 100644 --- a/mclu.spec.in +++ b/mclu.spec.in @@ -43,7 +43,7 @@ make DESTDIR=$RPM_BUILD_ROOT install %files -%doc COPYING README +%doc CONFIGURATION COPYING README %dir %{_sysconfdir}/mclu/ %dir %{_sysconfdir}/mclu/xmls/ %config(noreplace) %{_sysconfdir}/mclu/mclu.conf -- 1.8.3.1