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

Requirements, Recommendations, and Tips
for writing a script to build your configuration database.

Before writing your database creation script, read through the example
configure script to get an understanding of how to build a hierarchical
database, add a device, use collections, etc.  You may also want to find
existing configuration scripts for clusters with similar hardware and design
to yours.


REQUIREMENTS:
(at least the ones I know of so far...)

A few attributes are needed for all the tools to function properly.  You
can either set these in the initial configure script, or use the get*/set*
tools after the database is created.
- Every diskless node must have the "sysarch" attribute defined (rh-6.2-alpha)
- Every node must have it's "leader" attribute defined (node.n-0.t-1)
- Every node must have it's "image" attribute defined (vmlinuz-alpha.cluster)


RECOMMENDATIONS:
(not required, but these are "standard" ways of doing things, and will
probably make your life a lot easier)

- The admin node(s) should list itself in the "leader" attribute
- Other devices (not nodes) should have their "leader" attributes defined
- If you are using our rte capability, every node should have it's "vmname"
  attribute defined.  To initially dissable rte startup, set "vmname" to a
  non-existing vm. (such as "default")  To make all vm's visible to a node,
  (but load none of them) set the vmname attribute to "rte".  You can also
  use the set_vmname tool after the database has been created.
- Name your top level collection "equipment".
- Use collections to break up your objects by rack, purpose, etc.
- Right after creating a new device, store it in the database and add it to
  a group.
- Store a collection in the database right after adding the last item to it.
- Remember to $main::db->store for "equipment" (a common mistake)
- Name the admin node "admin-0".  ie: don't use the cluster name
- The primary interface of the admin node should be the machine net, not
  the world network.



TIPS:
(Things to watch out for and some shortcuts you can use once it all makes
sense...)

- If you will be adding devices repeatedly in a similar way, make a subroutine
  (create_DS10) to do it.  Similarly, if you will be adding many groups in a
  similar way, make a subroutine (create_comp_rack) for that too.  Remember,
  the aspects of structured programming still apply.
- When in doubt, include a device in the database.  Yes, it is possible to add
  them later, but it's easier now... trust me.
- Device port numbering can get confusing, particularly on RPC units where
  the physical ports are labled from "1" and the device hierarchy starts
  counting at "0".  So, WATCH OUT, be careful, double check, and run a couple
  tests to make sure you are addressing the port you intend to.
- Set the "vmname" attribute for leaders to "rte" and all others to "default".