############################################################################# # # This Cplant(TM) source code is the property of Sandia National # Laboratories. # # This Cplant(TM) source code is copyrighted by Sandia National # Laboratories. # # The redistribution of this Cplant(TM) source code is subject to the # terms of the GNU Lesser General Public License # (see cit/LGPL or http://www.gnu.org/licenses/lgpl.html) # # Cplant(TM) Copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004 # Sandia Corporation. # Under the terms of Contract DE-AC04-94AL85000, there is a non-exclusive # license for use of this work by or on behalf of the US Government. # Export of this program may require a license from the United States # Government. # ############################################################################# OVERVIEW ------------------------------------------------------- The concept of overlays is a central part of the CIT diskless hierarchy. For more information on the theory and background of this concept, please please refer to the "diskless.hierarchy" document, which is included as part of the diskless module. The following sections describe the practical aspects of how to switch between an existing overlay and how to implement a new overlay. WHEN DO I NEED A NEW OVERLAY? ------------------------------------------------------- Before embarking on how to create a new overlay be aware that you do not need to create a new overlay for every new package that you want to install on your nodes. You can always install a new rpm into the image for a given distribution by simply specifying a new root directory with the rpm command. For example, # rpm -ivvv /home/suse-9.1-x86_64/suse/x86_64/nameofrpm.x86_64.rpm --root /cluster/machine/$DISTRO/image Instead, overlays are intended to provide a granularity to make the management of nodes as easy as possible, or to provide a mechanism for installing software that requires very specific paths (for example, see the torque-maui module). HOW TO SWITCH BETWEEN root_rlogin and root_ssh_login ------------------------------------------------------- As an example of the sort of granularity that overlays can provide, consider the root_rlogin and root_ssh_login overlays, which enable one to change the security level on a per-node basis by simply modifying the overlays attribute. If you have not explicitly set an 'overlays' attribute for your node(s), then CIT uses the default_overlays from from CConf.pm. Typically, the defaults are: ROLE DISK root_rlogin common. (Note that the precedence order is left to right). Both the root_rlogin and root_ssh_login overlays are defined within CIT, but notice that only the root_rlogin is activated. To change from root_rlogin to root_ssh_login, first you need to explicitly set the overlays attribute for a given node: # device_mgr --set --overlays 'root_ssh_login DEFAULT' n5 You almost always want to keep the DEFAULT overlays attribute, but prepend any new overlays in front of the DEFAULT so that they will have higher precedence. The explicit addition of this attribute should in turn trigger build_diskless to update this node correctly. # build_diskless n5 --update build_diskless should now show 'OVERLAY root_ssh_login'. This example demonstrates how to switch between a predefined overlay. However, you may encounter a situation in which you need to add a new overlay. This is described in the following section. HOW TO CREATE A NEW OVERLAY ------------------------------------------------------- To create an overlay, there are a few places where you need to make changes; first, the overlay directory relative to your base image (/cluster/machine/$DISTRO/overlay), and second, the overlay attribute of your node(s) within your database. As a first step, create a new directory under the overlays directory of your current distribution (/cluster/machine/$DISTRO/overlay/$NEW) and fill it with your desired contents. Next, set the overlays attribute of you node. # device_mgr $NODE --set --overlays "$NEW DEFAULT" Note that this assumes that you have already created a distribution object and defined the sysarch attribute for your node. If you haven't then please consult the INSTALL.distros document for more information. HOW TO CHANGE DIRECTIVE FOR YOUR NEW OVERLAY ------------------------------------------------------- If you want to do more complicated actions with your overlay; for example, linking to other files or creating a directory to be cloned, the distro_mgr tool provides the capability to do this. Within CIT, each distribution object has its own set of attributes and directives. To view the settings for your current distribution, execute the distro_mgr command with the distribution that you have built for your nodes as its argument. # distro_mgr suse-9.1-i586 This should give you an idea not only of the complexity of the distribution object, but also some of the directives that you have available for your overlay. (Alternatively, you can also perldoc /cluster/lib/SoftConf.pm). To create a new directory to be cloned, add the following entry for the overlay to the distro object. # distro_mgr suse-9.1-i586 --overlay $NAME --set --install /dummy 0 --force Note that you currently need to specify the "--force" directive, otherwise you will receive an error about the overlay not being found (this is to prevent new overlays by being created by typos).