Copyright © 2001-2004 Junichi Uekawa
Distributed under the terms and conditions of GPL version 2 or later.
Table of Contents
List of Tables
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 5.1, “update-cluster-add” ) or update-cluster-maccollect ( See Section 5.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' |
/sbin/ifconfig eth1 | sed -n 's/^.*HWaddr \(.*\)$/\1/p' |
hostname |
[1] The administrator may choose to use the debconf interface to regenerate cluster.xml by removing cluster.xml and invoking dpkg-reconfigure. The reason for this inconvenience is to prevent any data loss, so to preserve any important changes that are done to the configuration file.
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.
Table of Contents
The configuration file cluster.xml is located in /etc//update-cluster/cluster.xml and it contains list of host-based configurations, written in XML. The DTD for this configuration file is found in /usr/share/update-cluster/cluster.dtd.
When it says it is a master, it means it is the cluster master node, and is usually the localhost in the current model of update-cluster.
This is an obsolete concept.
It has been discussed that NFS might not fit in cluster.xml design, and possibility of requiring a systemwide configuration.
However, after more discussion, it was decided that a bootmaster section is appropriate for providing enough information for NFS mount-points.
And it was realized that the whole of systemwide.xml may fit in to cluster.xml header section, and thus it was dropped.
Table of Contents
There are several programs constructing the system of update-cluster. For details of these commands, see their manual pages.
update-cluster-add appends an entry to cluster.xml. Editing the XML configuration file by hand might be better for system administrators. This program is provided to allow automatic configuration programs to edit the configuration file with ease.
update-cluster-remove without any options just outputs XML file with contents reformatted with indents.
The program can be used to remove certain entries from cluster.xml. Mostly used in conjunction with update-cluster-parseconfig.
Reads in the XML configuration file, and outputs a space-delimited line-based data, a format often used for conventional configuration files.
Used in *.updatelist files when generating individual configuration files.
update-cluster-regenerate regenerates the configuration files for individual applications from cluster.xml
This program calls *.updatelist files to do the actual updating.
update-cluster-maccollect auto-adds hostnames to configuration file cluster.xml by listening to network interface for packets on the network, and searching for new MAC addresses not in the cluster.xml database.
It will try to generate IP addresses and hostnames from the configuration.
Table of Contents
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.
The current system is fixed with regards to “hostname”, “ip”, “mac” and “notes” information. For “notes”, only “master” is defined. Using these information is encouraged. An implementation of “bootmaster” is done to support some programs. “nfsroot” is deprecated. The DTD is defined in cluster.dtd.
Table 6.1. The individual fields of cluster.xml as defined in cluster.dtd
| Entry | Meaning | Example |
|---|---|---|
| cluster/host/ip | The IP address for the host | 192.168.0.1 |
| cluster/host/mac | The MAC address of the network interface card | AA:BB:C0:D2:E4:F6 |
| cluster/host/hostname | The hostname of the host | hostname |
| cluster/host/notes | 192.168.0.1 | |
| cluster/host/nfsroot | deprecated | deprecated |
| cluster/host/bootmaster | The IP address of the master node which this host shall boot from. Assign the IP address of itself or omit this entry entirely when it boots from itself, | 192.168.0.1 |
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.3 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.