Before starting GrIDS
Starting Grids and Defining the Heirarchy :


     GrIDS uses a hierarchy of departments to manage the collection of
machines being monitored.  Each host being monitored by GrIDS must be 
placed under the control of a department ( graph engine/aggregator ). 
Departments, in turn, can be managed by a department at the next highest
level in the hierarchy.  An initial  placement of hosts into departments and 
departments into the hierarchy must be configured upon starting GrIDS. 
This initial configuration is defined and added to the GrIDS database
using the "$GRIDSPATH/user_interface/grids.db" file.


     When grids is started it will examine the file grids/code/user_interface
grids.db to determine the hierarchy.  The syntax and structure of this file
will be illustrated in the following examples.  First, as shown in the following
excerpt from "grids.db", all hosts in the initial configuration are added
to the 'host_to_os' perl hash reference.  One simply includes the host-name and
it's corresponding OS as a key/value pair in the has.  This list must contain
all hosts in all departments that will be included in the initial hierarchy.

----------------------------------------------------------------------------
#  Standard startup config stuff

$grids_rsh = 'rsh';

##
##  These structures are the *authoritative* master lists of hosts.
##  NOTE :: All hosts must be *DECLARED* here, even if their OS type is unknown:
##

$self->{'host_to_os'} = {
	'host1.edu' => 'solaris',
	'host2.edu' => 'irix',
	'host3.edu' => 'sunos',
	'host4.edu' => 'ultrix',
	'host5.edu' => 'linux',
	'host6.edu' => 'unknown',
};
------------------------------------------------------------------------------
  

   Next, data structures are defined that associate host-names to departments
in the hierarchy.  The following portion of code from the "grids.db" file 
illustrates a typical setup assigning hosts to two different departments.

------------------------------------------------------------------------------
#  Now set up list references of hosts to be used for each department:
#  TYPICAL FORMAT: 
#  $self->{'<dept-name>_hosts'} = [
#	   '<first-host>',
#	   '<second-host>',
#	   '<third-host>',
#                .
#                .
#          '<last-host>',
#          ];

$self->{'ROOT_hosts'} = [
				'host1.edu',
				'host2.edu',
				];
$self->{'dept1_hosts'} = [
				'host3.edu',
				'host4.edu',
                                ];
------------------------------------------------------------------------------

Each list reference simply contains all the hostnames that will be grouped
in a single department.  Notice that the names of the list references; 
'ROOT_hosts' and 'dept1_hosts', are completely arbitrary as they will be 
refered to by the user later in the "grids.db" script.

   The next section of "grids.db" shows how command line arguments can be
used to select different hierarchy configurations using the same startup
database.  In this case, the second argument given in the grids startup
script, $ARGV[1], indicates which configuration block recieves control.
For example, the grids control script executed as '% grids start agg' will
start grids using the hierarchy defined in the GEOM_AGG control block.

------------------------------------------------------------------------------

CONFIG:
{       # so can __last__ out of this as a block.

    last CONFIG unless $ARGV[0] eq 'start';

  # CAUTION -- backwards compatibility not fully tested
    goto GEOM_AGG if $ARGV[1] eq 'agg';
    goto GEOM_BIGROOT if $ARGV[1] eq 'bigroot';
    goto GEOM_START;  # default for backwards compatibility

    die "Allowed <grids start> parameters are agg or bigroot\n";
    last CONFIG;  # Important, to handle "else" cases of above GOTO.

------------------------------------------------------------------------------

After all initial hosts have been defined and grouped by department, 
the startup hierarchy database is configured.    The following section of code from
the "grids.db" file illustrate how this can be done.

------------------------------------------------------------------------------
#
#  AGG Hierarchy - Partitions all hosts into departments based upon their
#                  room location.  Hierarcy is only 2 deep.
#
 
 GEOM_AGG:   #  This sections gets entered when using the "agg" option in the
             #  grids startup script ( e.g. "% grids start agg" )

    $num_hosts = 0;
    foreach $key ( keys %{$self->{'host_to_os'}} ) {
	$num_hosts++;
    }

#  Choose the host for the Hierarchy Server
    $self->{'ohs_host'} = 'root_server.edu';

#  Define the geometry of all departments
    @dept_geometry = (
		      
		      {
			  DEPT_NAME => 'ROOT',  PARENT_DEPT => 0,
			  SM_HOST => $self->{'ROOT_hosts'}[1],
			  AGG_HOST => $self->{'ROOT_hosts'}[0],
			  NUM_HOSTS => $#{$self->{'ROOT_hosts'}}+1,
			  SPECIFIC_HOSTS => [ @{$self->{'ROOT_hosts'}} ], 
		      },

		      {
			  DEPT_NAME => 'dept1', PARENT_DEPT => 'ROOT',
			  SM_HOST => $self->{'dept1_hosts'}[1],
			  AGG_HOST => $self->{'dept1_hosts'}[0],
			  NUM_HOSTS => $#{$self->{'dept1_hosts'}}+1,
			  SPECIFIC_HOSTS => [ @{$self->{'dept1_hosts'}} ], 
		      );
  
    last CONFIG;
# end AGG section

------------------------------------------------------------------------------

Each element of the @dept_geometry array is a perl hash reference.  
Keys of each hash define the item being configured. Departments are
defined by name, their parent department in the hierarchy, if any,
is identified, hosts running critical componants are selected and
all the managed hosts are added.

###
###   This next heirarchy uses the same departments as the previous , but a different departmnet
###   geometery.  Thus for this hierarchy we need not enumerate the department assignments for each
###   host,  since we are using the already defined department assignments from before.
###


#
#  BIGROOT Hierarchy - Adds all hosts into a single root department with
#                      no children.
#  

   GEOM_BIGROOT: #  This sections gets entered when using the "bigroot" option 
                #  in the grids startup script ( e.g. "% grids start bigroot" )

    $num_hosts = 0;
    my @common_hosts;
    foreach $key ( keys %{$self->{'host_to_os'}} ) {
	$num_hosts++;
	push @common_hosts, $key;
    }

#  Choose the host for the Hierarchy Server
    $self->{'ohs_host'} = 'root_server.edu';

#  my @common_tmplist = &old_grids_common_config ($num_hosts, $num_hosts);

    @dept_geometry = (
		      {
			  DEPT_NAME => 'ROOT',  PARENT_DEPT => 0,
			  SM_HOST => $common_hosts[1],
			  AGG_HOST => $common_hosts[0],
			  NUM_HOSTS => $#common_hosts + 1,
			  SPECIFIC_HOSTS => [ @common_hosts ], 
		      },
		      );
    
    last CONFIG;
# end BIGROOT section

##################################################
#  Default Hierarchy - Create a single department with hosts in one room.
##################################################
  GEOM_START:   #  This sections gets entered when no third option is specified
              #  grids startup script ( e.g. "% grids start" )

    $num_hosts = 0;
    foreach $key ( keys %{$self->{'host_to_os'}} ) {
	$num_hosts++;
    }

#  Choose the host for the Hierarchy Server
    $self->{'ohs_host'} = 'root_server.edu';

#  Define the geometry of all departments
    @dept_geometry = (
		      
		      {
			  DEPT_NAME => 'ROOT',  PARENT_DEPT => 0,
			  SM_HOST => $self->{'ROOT_hosts'}[1],
			  AGG_HOST => $self->{'ROOT_hosts'}[0],
			  NUM_HOSTS => $#{$self->{'ROOT_hosts'}}+1,
			  SPECIFIC_HOSTS => [ @{$self->{'ROOT_hosts'}} ], 
		      }

		      );
  
    last CONFIG;
# end default START section
################################################

}       # so can __last__ out of CONFIG as a block.

1;