                                                        From: G.Filippi
                                                        Date: 11 May 1999

             VLT-SW-FEB99 - STANDARD ENVIRONMENT
             ===================================

The Standard Environment provides a configurable way to set up the 
environment variables of every VLT user, both development and operational 
ones, and to keep trace of the configuration files needed to customize
the operating system and any other product used in the VLT Software.

The Standard Environment is made up by a set of files, some common to all
installation, some machine or user specific. The files are managed by
two (cmm-ed) modules:

  stdEnv   contains the part common to all installation

  std<xxx> contains the part specific to the <xxx> group of machines.
           At present, the following groups of machines are defined:

           ESO-Paranal
              stdDEP       VLT Development Machines       
              stdVLT       VLT (TCS & Instruments)  
              stdDFS       Data Flow System Machines 

           ESO-LaSilla
              stdDEL       VLT Development Machines   
              std3P6       3.6                              
              stdNTT       NTT                            

           ESO-Garching
              stdDEV       VLT Development Machines         
              stdDMD       Data Managemen Division Development
              stdODT       ODT Machines       
              stdVCM       VLT Control Model 

           ESO-Santiago
              stdDES       Development Machines    



Being the one providing all definitions to the rest, the standard environment
cannot rely on anything else and therefore needs some "hardcoded" assumptions,
namely the /vlt/System directory to store files and procedures. The directory
has the following structure:

    /vlt/System/
	   |-- ....                   common login scripts
	   |-- X11/app-defaults/....  X11 resource definitions 
	   |-- config/....            machine-specific configuration
	   |-- stdRoot                configuration utility
	   |-- actions/....           common configuration scripts 
	   |-- templates/....         common configuration templates

The /vlt/System is build/maintained by installing from the stdEnv module.
As a pragmatical compromise, a tarred version of /vlt/System is provided
as part of the VLTSW distribution tape. This allows to establish the
system on an empty system in order to carry on the VLTSW installation.
Once the system is installed, the normal tools can be used to handle the
update.

As said, the Standard Environment provides:
  - a consistent and configurable set of environment variables,
  - a way to keep trace of OS configuration files.


Configuring The environment variables
-------------------------------------

The first task of the Standard Environment is to provide each user running 
in the system of a consistent and complete set of environment variables.
In order to work, the typical Unix variables (PATH, MANPATH,...),
the one requested by the products used by the VLTSW (WIND_BASE, RTAPROOT, ..)
and the one defined by the VLTSW development (VLTROOT, INTROOT, ...) must
be properly defined.

This must be done for every user of the machine. To assure that and to allow
a certain degree of freedom in the configuration, the system is organized
in a cascade of files, some standard to all installation, some machine
specific, some user specific.

The standard interactive shell for the VLT project is the csh. Therefore 
each new shell (unless the -f is specified) will execute: 

  /etc/csh.login     this file is reduce to a minimum content.
		     Let's ignore it for the moment.

  ~/.cshrc           this provides the environment set-up. This script
		     In order not to interfere with rem* command,
		     this script MUST NOT produce output or being interactive!

It the shell is a login shell, an other file will also be executed:

   ~/.login          typically aliases and other definitions useful
		     for an interactive session are defined here.
   
The Standard Environment substitues the user files with a link to 
some general files. For instance:

      .cshrc@ -> /vlt/System/Cshrc
      .login@ -> /vlt/System/Login

Each common file (f.i., Cshrc) has a typical structure:
  - first execute a standard script          (/vlt/System/System.cshrc),
  - if exist, execute a "user-defined" file  ($HOME/.cshrc.local)

The /vlt/System/System.cshrc is responsible therefore for providing
the basic definitions, i.e., what needed to use the VLTSW!
Because of the many possible configuration in which it could be used,
the /vlt/System/System.cshrc is structured in a way that some easy
customization can be done at machine and/or user level.

The /vlt/System/System.cshrc is organized in three sections:

 - in the first part, the standard set of UNIX variable is set.
   This depends only on which OS we are working (HP-UX and SUN-Solaris,
   see the release notes for the exact version supported by each VLTSW
   release).

 - in the second section, a set of internal variables are set. These
   variables are controlling how the following section will 
   set up the environment.
   The internal variables are set by:
    - providing some defaults
    - reading what defined by the /vlt/System/config/`hostname`.cshrc
    - if present, reading what defined by the ~/config/`hostname`.cshrc.local
   This scheme allows to have a machine wide set of definitions and
   if requested, each user can override/complete the definitions.

   As possible example of /vlt/System/config/`hostname`.cshrc
   (or as a user defined ~/config/`hostname`.cshrc.local) the file 
   can contain the following lines:

    For full CCS (HP):
      set X11_ONLY_EXISTS = TRUE
      setenv VLTROOT /vlt/FEB99
      setenv VLTDATA /vltdata
      setenv MIDASHOME /midas
      setenv MIDVERS 98NOV
      set STARCAT_EXISTS = TRUE
      setenv ACC_HOST te13
      setenv WIND_BASE /vlt/vw5.3
      set RTAP_EXISTS = TRUE
      setenv RTAPENV wte13

    For CCSlite:
      set X11_ONLY_EXISTS = TRUE
      setenv VLTROOT /vlt/FEB99-CCSlite
      setenv VLTDATA /vltdata
      setenv WIND_BASE /vlt/vw5.3
      set RTAP_EXISTS = FALSE
      setenv RTAPENV  <your-CCSlite-environment>
      setenv MIDASHOME /midas
      setenv MIDVERS 98NOV
      set STARCAT_EXISTS = TRUE
      setenv ACC_HOST te13
    
    For NO-CCS:
      setenv NOCCS defined
      setenv VLTROOT /vlt/FEB99-NOCCS
      unsetenv WIND_BASE
      set RTAP_EXISTS = FALSE
      unsetenv RTAPENV 


 - in the third section, based on the internal variables now defined,
   the environment is completed.
    
The usage of customized configuration files together with the fefinition
of a minimum set of variables that are controlling the overall configuration,
allow to separate the minimum level of information the user has to
give from what that can be put into standard and common files.

Before continuing, it is important to understand the difference between the
two levels of customization the user has:

   ~/config/`hostname`.cshrc.local
         if present, this file is read before doing the generation of the
	 environment. It may be used to override the default environment
	 (for instance to select a different VLTROOT) or to add informations
	 that are used to build many variables (like setting the INTROOT)i.
	 There is one file per machine. If the home directory is mounted by 
	 several machines, the user has the possibility to have 
	 a different set up for each machine.

   ~/.cshrc.local
         if present, it is executed after that the standard set up is completed.
	 This file is typically used to add some user preferences, like
	 defining the PRINTER ar adding something to the PATH. Do not 
	 use this to change VLTROOT or INTROOT! It will take a lot of work
	 in doing it here ....
         There is only one file for all machines. If differences are
	 needed, use the switch structure, as indicated by the template.

The ".cshrc" is the most complicated case. The other configuration files
(.login, .logout, ...) have just the system wide file (/vlt/System/System....)
and the optional user defined one (~/<name>.local)


Cookbook
--------
To configure <hostname> (all actions are as "vltmgr", unless otherwise 
specified):

  - get stdEnv installed. If this is the first installation, get 
    /vlt/System from another computer or from the tape. If the VLTSW
    is already installed, get the latest stdEnv and install it:
          cd stdEnv/src
          make all man install 

  - according to the installation you are doing,
    edit properly /vlt/System/config/<hostname>.cshrc

  - according to your preferences you can also set the VUE root menu
    by editing /vlt/System/Vuewmrc 


For every user that has to use the system:
  
  - login as user
   
  - create the proper links by executing

        /vlt/System/setEnvironment

    (follow the instruction given by the procedure)

  - if necessary, edit:

       ~/config/<hostname>.cshrc.local   to override system settings
       .cshrc.local, .login.local        to add user's preferences

    This can be done at any time bythe user.



Keep Trace of OS Configuration Files
------------------------------------
While stdEnv takes care to provide the standard files under /vlt/System,
it is up to the specific std<Xxx> module to provide the configuration files 
/vlt/System/config/*.cshrc, one for each machine in the group!

Due to the big number of involved computers, The usage of std<xxx> 
is mandatory on target installations (Garching, PARANAL, LaSilla).
Considering the limited number of computers involved and the
preliminary status of this documentation, Consortia
are not requested to use the following, but to proper configure the
terget files. Nevertheless, the following approach can help in keeping
things cleaner, therefore Consortia are invited to use it.

An example of an existing std<xxx> (stdVLT) is given in the patched file
provided for FEB99 release.


The machine specific information is collected in the machine-group module
(std<Xxx>). Each machine-group module contains therefore:

    std<Xxx>
           |-- src/     
	   |     |-- Makefile        
	   |     |-- Vueprofile
	   |     |-- Vuewmrc[.<user>][.<hostname>]
	   |
	   |-- config/....            machine-specific configuration


The Vue* files are provided to customise the Visual User Environment
for HP-UX. This is still temporary, because it is planned to
standardize on both HP and SUN the use of the CDE (Common Desktop
Environment).


The second task of the Standard Environment is to provide a way to 
keep trace of the various configuration files and actions needed
to set up a computer that has to be used for the VLT development and
or operation.

To work properly, the VLT Software, actually the products and the 
developments that are making it up, require that several system
files are properly edited. In addition, other actions like changing
kernel parameters, addind a patch, .... may be necessary to
have a working system. Although all these actions are properly 
described in the Installation Manual, executing by hand each of
them may be tedious and error prone.

Therefore, the Standard Environment has been extended by adding
a way to handle such configuration actions.

The basic idea is to have, in one hand, a table that tells the system 
which actions have to be performed and, in the other hand, a set of
actions (scripts and templates) that can be used to set up a machine.
Both the table and the action to be used can be standard or "tailored" 
on a specific machine or group of machines.

The stdEnv module provides a set of standard actions and templates
that can be used for all machines. They are made available under the
/vlt/System directory. In addition, it provides a template for the table
and a standard utility (stdRoot) that can be used to "check" or
to "install" the configuration.

The data specific to a machine or to a group of machines is instead
handle by the std<Xxx> module.

To explain how it works, it is worth to just follow an example.
Let's suppose that the machine "wins" has to be configured. The machine
is part of the VLT Control Model (stdVCM).

First step is to have the up-to-date stdEnv (either from the tape or
from the cmm archive) installed under /vlt/System. 
Then one needs the configuration module for the machine group: i
in this case stdVCM.


Each machine-group module contains, in addition to the config files:
 
    std<Xxx>
           |-- src/     
	   |     |-- hosts.conf.dat
	   |     |-- Config-Files[.<hostname>]
	   |
	   |-- actions/....           machine-specific configuration scripts 
	   |-- templates/....         machine-specific configuration templates


 - hosts.conf.dat:  
     a list of pairs: <machine names> <keyword> 
     At present possible keywords are:
	  FCCS    for RTAP-CCS installed systems
	  CCSL    for CCS-lite installed systems
	  NOCCS   for NO-CCS   installed systems
     Example:
       wa1tcs  FCCS
       wu1uws  FCCS
       wu1oh   CCSLite

    Each configuration item is also labeled with one
    or more keywords.
    When configuring <machine names>, only configuration 
    items matching <keyword> will be used.

 - Config-Files
   Config-Files.`hostname`
    A table containing the type of "templates" to be processed.
    Every line of these files has the following format:
     "template_name"
     "target_name"
     "target_directory"
     "protection"
     "owner"
     "group"
     "type"         possible values: FCCS,CCSL,NOCCS
     "action"       to be executed. The system search an executable
                    in the following order:
                        ../actions/"action".`hostname`
                        ../actions/"action"
                        /vlt/System/actions/"action"
     "parameters"   additional ones to be passed to the action

    The common default table has the same format and it is located in
     
     /vlt/System/templates/Config-Files


    The configuration utility (/vlt/System/stdRoot) builds a configuration 
    database by successively reading:
   
      1) /vlt/System/templates/Config-Files
      2) ./Config-Files
      3) ./Config-Files.`hostname`
 
    What written in 3 overwrites 2 that overwrites 1. Adding/changing allow
    tailoring the actions to be executed on a machine per machine basis.


    The usage of the tables allows to defines actions that have to be
    done for all the machines in the group (Config-Files) or only for one
    specific machine (Config-Files.`hostname`).

    (REMARK: we use the word "template" because originally these
    were only template files to be copied into specific destinations.
    Later the concept has been extended, so any configuration activity
    can be represented by an entry in one of the tables)

   
 - actions/....           machine-specific configuration scripts 
 - templates/....         machine-specific configuration templates

    These offer another possibility in configuring Both the template file 
    and the script file that control the configuration action can be 
    created as machine group and/or machine specific files. in the
    machine group module.

    The configuration utility (/vlt/System/stdRoot) will search an action to 
    be executed looking for:
          ../actions/<action>.`hostname
          ../actions/<action>
          /vlt/System/actions/<action>

    In the same way, each action will look for a template-file starting from:
          ../templates/<file>.`hostname
          ../templates/<file>
          /vlt/System/templates/<file>



Cookbook
--------

To configure <hostname> (all actions are as "vltmgr", unless otherwise 
specified):

 - get stdEnv installed. If this is the first installation, get 
   /vlt/System from another computer or from the tape. If the VLTSW
   is already installed, get the latest stdEnv and install it:
	 cd stdEnv/src
	 make all man install 

 - identify to which group <hostname> belongs, and get the std<Xxx>

 - edit properly std<Xxx>/config/<hostname>.cshrc
   Install the files:  make all man install

 - execute the stdRoot utility in check mode:
  
	     /vlt/System/stdRoot CHECK
	     
 - based on the output, decide whether the standard templates are OK
   (i.e., the suggested changes should be applied) or you need to add
   templates for <hostname>. If such, add the necessary files under
   std<Xxx>/templates/<file><hostname>

 - based on the usgae of the machine, decide whether you need to 
   overwrite or extend the the general configuration tables (the system
   one: /vlt/System/templates/Config-Files and the group one:
   std<Xxx>/src/Config-Files). If so, add a new file:
    
	  std<Xxx>/src/Config-Files.<hostname>

   and edit accordingly to your needs.

 - if necessary, add script files to implement machine specific actions:

           std<Xxx>/actions/<action>.<hostname>


 - repeat the CHECK until you are sure that all the configuration actions
   you need to have on the machine are listed and all templates are correct.

 - login as "root", cd to std<Xxx>/src and execute the changes:

	      /vlt/System/stdRoot INSTALL

   (some action can be done only as root!)

 - repeat the CHECK. This time, all checks should be OK.

                         ____oOo____
