#############################################################################
#
#     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.
#
#############################################################################


DISTROS MODULE OVERVIEW
-------------------------
This module adds support for Software Configuration tools,
libraries, and the Distro class hierarchy.  It is leveraged
by tools in the "diskless" and "diskfull" modules to
modify the filesystems for both diskless and diskfull nodes.

PROCESS
--------
* Install the module following the standard steps
	# ./configure; make; make install; make test
* Make sure the software distribution is available in a single path
  For example, copy the source media to /home/suse/CD*
  (or use the --duplicate option with build_distro below)
* Add an object to the database to describe each
  software distribution you want to support with CIT
      # distro_mgr --types
      # distro_mgr --new --type Distro::RPM::SuSE::Pro::9_1::i586 suse-9.1-i586
  The object name can be anything, but a convention that indicates
  it's source is highly recommended. (Note that the actual name of the
  object, in this case, suse-9.1-i586, should match the sysarch attribute
  for the target node(s). You can obtain a list of the current device
  attributes using the following command: device_mgr --sysarch nodes).
* Define where the distribution's source is located
	# distro_mgr suse-9.1-i586 --set --source_dir '/home/suse/CD*'
  (not necessary if the image will be a duplicate of the current node) 
* If desired, customize the Distro object
	# distro_mgr --help
	# distro_mgr --set --image --help
	# distro_mgr suse-9.1-i586 --set --image --<directive> <target> <value>
  For example, make /etc/sudoers a real file instead of a link:
	# distro_mgr suse-9.1-i586 --set --image --clone /etc/sudoers dup
* Build the base image and set up the overlays
  (should be run as root)
	# build_distro suse-9.1-i586
  OR, if --source_dir not defined above, duplicate the current node:
	# build_distro --dup suse-9.1-i586

Now you should be ready to run build_diskless or build_diskfull.
See the docs in the diskless and diskfull modules for more information.
Note, however that the CIToolkit does not provide kernels as part of
the standard distribution. For information on the kernel requirements
for diskless booting using root-over-NFS, please consult the following 
documentation: diskless/doc/diskless.kernel.

If the current node is binary compatible with the distro you just built,
the "chroot_distro" tool can be used to more safely modify the image
while still providing access to the $CIT_HOME directory, tools, and
configuration info.  See "chroot_distro --man" for more information.


WARNING!
--------
If you are attempting to build a distribution for an architecture
that is different from your admin node, then be aware that the rpm
pre and post scriptlets may fail due to a chroot command  
that is used when specifying an alternate root directory (see
the rpm man page). 

If you do go ahead and build the distribution across architectures,
the following files will not be generated automatically and will 
definitely need to be created or added to the image directory of 
that distribution (under /cluster/machine):
	/etc/passwd
	/etc/shadow
	/etc/group
	/etc/sysconfig/boot
Also note that a node with a different architecture will not be 
able to do lookups of the cluster.db in the GDBM format on the 
admin node. Therefore in this situation, it is better to set up your database 
using LDAP. For more information, you can run the perldoc command on the
LDAP.pm module under MyDB.
 
The exception to this rule would be if you are attempting to build 
a distribution for the i586, and your admin node has the x86_64 architecture.
Since the x86_64 architecture was designed to be backward compatible,
this situation should work.  

In theory, you should also be able to mount the admin node's /cluster
directory from another x86_64 node and run the build_distro command, although
this approach has not been rigorously tested.