############################################################################# # # 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. # ############################################################################# BASIC DEPENDENCIES ------------------ Prior to getting started, be aware that the CIToolkit and the CIT install procedure require a few common Unix tools: -Perl (version 5.00503 requires a patch which should be included in the CIT distribution. More recent versions should be fine.) -make -rsync -a C++ compiler (such as gcc) for installing new modules from CPAN INSTALL PROCEDURES ------------------ In general, the procedure for installing any module, including the base module, involves changing into that module's directory, running its configure script, and then executing the 'make' command. This sequence of commands is summarized below. cd ./configure make make install make test Therefore, for the base module, as with every module that you will install, first cd into the base directory, and then execute the perl script, called configure. Note that almost all scripts, including configure, support the '--help' option for notes on usage and syntax. For those few that do not, you can always read the comments in the top of the file. The configure script will check for dependencies and create a Makefile in this same directory, which you can then execute by typing the 'make' command. If this executes correctly, then it will prompt you with the phrase OK to 'make install'. At this point, type 'make install', and you will be prompted with the phrase "'base' module installed". To complete the process, type 'make test'. At this point, CIT will have copied the appropriate files, modules, and directories into your new cluster home directory, by default this is located under your root filesystem with the name 'cluster', and in this document is hereafter referred to as CIT_HOME. This is the foundation for managing and controlling your cluster; for example, CIT_HOME contains your configuration files, the tools for manipulating your cluster, and the image for the nodes. Underneath CIT_HOME, you will see the following four subdirectories: bin -- CIT tools for manipulating your database and hardware config -- configuration files for CIT doc -- documentation to support CIT lib -- CIT libraries to support devices/objects As you install additional modules, CIT will copy files into these directories. As may be expected, the bin directory contains a series of tools, config contains the necessary files for a particular configuration of a cluster, and the lib directory will contain all the perl modules that define the classes and methods used to set up and control devices. Now that you have your CIT_HOME directory, the first thing you need to do is to source the cluster.env located within your CIT_HOME/config directory to set all the necessary environment variables. Note that you can also add ". CIT_HOME/config/cluster.env" to your .bash_profile, which will make these variables available within your environment. Next, since every cluster operates using a cluster database, which stores all of the information describing the hardware of a particular cluster, the next step in building your cluster is to set up this database using a database creation script. The creation and setup is one of the more complicated aspects of managing your cluster, however, once you have an accurate and working database, it greatly simplifies your interaction with the system. To help you in setting up the database, there are many examples of database configuration scripts for existing systems that are available in the machines module (CIT-*-machines.tgz). However, probably the best example is the ACME database, which is included as part of the base distribution within the doc directory (configure-ACME-library-style.pl). For the novice CIT user, the best place to start is with the ACME tutorial, which will get you started using a virtual environment. This tutorial, called ACME-TUTORIAL, is delivered as part of the base module, and is located in the doc directory under CIT_HOME. This tutorial likewise includes an example database creation script, configure-ACME-library-style.pl, which should be located in your cluster/doc directory. When you execute the configure-ACME-library-style.pl, it will create the database under CIT_HOME/config. At this point, it is worthwhile to read the tutorial and to closely examine the configure-ACME-library-style.pl script. These should provide a template for how to set up your cluster. For more general information on how to get help, also consult the README file in this directory. There are also other resource under the CIT_HOME/doc directory. Another place to looks is the CI.checklist, the Cluster Integration Checklist, which provides more of an overview as to what sorts of services and setup you will need on your admin node to get the cluster up and running. Also, within this same directory, the Attribute.defs.pod document provides a list of the attributes available to different devices and what they mean within cit.