Update-cluster usage guide

Conventionally, for most Un*x like operating systems, including Debian, individual clustering related software have their own configuration files due to their individual development history. The result consists of duplicate configuration entries, and requires manual maintenance to be up-to-date.

These individual configuration files are usually user-customised, and should not usually be overwritten by automatic scripts. An automation, under control was required.

The aim of this project is to simplify the bulk configuration process for everyday tasks, and centralising the network related configuration files which had no standard base. Reliably obtaining a list of machines that is part of a cluster on a Debian cluster system was not previously possible.

This program attempts to provide a framework to perform automatic configuration on master node of a cluster. Use of this program on other nodes in a cluster is mildly supported, but not quite well supported at the moment. The system is to be designed to use minimum or no network bandwidth when communicating information.

This system provides an infrastructure that is useful even to computers that are not part of clusters, for centralising the location of information about the "list of available machines" which has previously been stored individually.

The basic model of update-cluster is this: A system administrator edits or generates a configuration file called cluster.xml, and runs update-cluster-regenerate all to regenerate configuration files for applications.

cluster.xml is a configuration file, and when installing update-cluster for the first time, the user is asked for reasonable default value by a debconf interface, and it is generated from the value if cluster.xml does not already exist. When the file exists, debconf interface will not modify the configuration file. ^[1]

The system administrator may use update-cluster-add ( See Section 1, “update-cluster-add” ) or update-cluster-maccollect ( See Section 5, “update-cluster-maccollect”) or other means to add information. For information of the localhost, make it marked as master in the notes element. Usually ifconfig eth0 gives the necessary information. Input the information with a command line like

# update-cluster-add --ip 192.168.1.1 --mac xx:xx:xx:xx:xx:xx --hostname beomaster --notes master

To obtain the IP address, do

/sbin/ifconfig eth1 | sed -n  's/^.*inet addr:\([^ ]*\).*$/\1/p'

. To obtain the MAC address, do

/sbin/ifconfig eth1 | sed -n  's/^.*HWaddr \(.*\)$/\1/p'

. To obtain the hostname, do

hostname

The update-cluster system concept is to construct a “ write-once, and everything works ” kind of system.

The configuration information is held in cluster.xml file. An arbitrary editor or the commands update-cluster-add and update-cluster-maccollect may be used to edit the configuration file. Especially, auto-configuration tools may want to use update-cluster-add program for interfacing with cluster.xml.

update-cluster-regenerate reads cluster.xml and generates configuration files from it. This is done using *.updatelist scripts to do actual work. These *.updatelist scripts are provided by individual application packages.

This way update-cluster provides the infrastructure, which each package can depend upon.

Also, note that update-cluster provides the infrastructure, but does not do much about creating the configuration files. The usage of the information provided by this system is not within the scope of this system. Individual programs are responsible for the use.

There are several programs constructing the system of update-cluster. For details of these commands, see their manual pages.

To provide support for update-cluster in Debian packages, the package needs to provide *.updatelist to regenerate the configuration file for the application. The content of the file is actually a shell script parsing the content of file specified by environmental variable CLUSTERXML.

The script must be installed with filename extension .updatelist in /usr/lib/update-cluster as an executable file. Also, the package needs to have a Suggests: line to suggest update-cluster

Alternatively, a Debian package can declare a Depends: relationship on update-cluster and call update-cluster-regenerate [command-radix] in the package postinst maintainer script. Note that the configuration file must not be marked as a conffile when doing this, and also note that user configuration files must not be ignorantly overwritten by automatic scripts.

Any script installed as /usr/lib/update-cluster/*.updatelist will be executed by update-cluster-regenerate script, they will need to update the configuration files, according to what is said by /etc/update-cluster/cluster.xml. A sample configuration file is shipped with this collection, called update-cluster-sample.updatelist which you can use to generate your own hook.

Programs update-cluster-parseconfig and update-cluster-remove are included to aid handling of the configuration file.

When such a script is installed, the Debian package should add a field to Suggests: update-cluster.

when there is “<notes>master</notes>”, that node is the master node, and this machine should be treated a bit differently.

For example, mpich machines_LINUX should not include master because it is implied, however, /etc/hosts should include the master node itself.

To get the list of hostnames which are not "master" and write it to /etc/mpich/machines_LINUX, it will be like

#! /bin/bash
cat $CLUSTERXML | update-cluster-remove --master | update-cluster-parseconfig ip > /etc/mpich/machines_LINUX
    

also, use of script snippet like :

 awk '{printit=1} /^#Auto-generated by
  update-cluster/,/^#End update-cluster/{printit=0} {if (printit) {print} }'
    

might be useful.

This document is about usage policy of update-cluster collection of software tools.

This document accompanies version 0.41.4 of update-cluster

The current maintainer is Junichi Uekawa, <dancer@debian.org> <dancer@netfort.gr.jp>. Main discussion about update-cluster has occurred in <debian-beowulf@lists.debian.org> mailing list. Please discuss about this document in the Debian Beowulf mailing list, or the Debian Developers mailing list, whichever seems more appropriate.

The people who contributed to this project are mainly, Viral <viral@debian.org> and Adam C. Powell IV.