                Installation Summary for Sun Grid Engine
                ----------------------------------------

                   Copyright  2001 Sun Microsystems, Inc.
                      Use is subject to license terms


1. Review the following installation instructions
2. Download the current distribution
3. Create a Sun Grid Engine administrator account and set up service port
4. Create a directory and unpack the distribution
5. Additional information before installing
6. Install Sun Grid Engine
7. Verify installation
8. Using Sun Grid Engine
9. Contact and support information


1) Review the following installation instructions
-------------------------------------------------

   Please read through this entire installation procedure before beginning.


2) Download the current distribution from our FTP site
------------------------------------------------------

   Please see our web page at http://www.sun.com/software/gridware


3) Create a Sun Grid Engine administrator account and set up service port
-------------------------------------------------------------------------

   An administrator account must be specified. The administrator can be an
   existing user or a new user may be created for this task. This account
   will own all of the files and it is used to configure and maintain the
   cluster once the software is installed.

   The administrator account must exist prior to installation. We recommend
   'sgeadmin' as the administrator account belonging to the 'adm' group.

   The software uses a tcp port for communication. All hosts in the cluster
   must use the same port number. The port number can be set in the
   following places:

      o NIS (Yellow Pages) services or NIS+ database
     
        Add the following to the services database (the port number does not
        matter, it must be unused on your system and should be a reserved
        port)

           codine_commd   536/tcp # example communication port for Sun Grid Engine

      o Or, add the above manually to the /etc/services file on each machine 


4) Create a directory and unpack the distribution
-------------------------------------------------

   As the Sun Grid Engine administrator, do the following:

   If you received the distribution in "pkgadd" format

      o Install the packages with "pkgadd" on your file server

        (all files will have the correct permissions and ownership)

   or if you received the distribution in "tar.gz" format

      o Create a directory for Sun Grid Engine. This directory must be
        accessible to all Sun Grid Engine clients and execution hosts. We
        recommend /gridware/sge .

      o Unpack the distribution to this directory.

      o Please verify the file permissions with the script

            <codine_root>/util/setfileperm.sh

        (all Sun Grid Engine directories and files should be owned by the
        administrator, some files need to be installed suid root)

        This script must run on a machine where user root has appropriate
        permissions to chown/chmod file. This script not necessarily need to
        run on the qmaster machine.


5) Additional information before installing
-------------------------------------------

   o Sun Grid Engine must be installed as root

     The Sun Grid Engine installation program needs to be run as root in
     order to start the daemons. Root does NOT need write permission on the
     fileserver. Once Sun Grid Engine is installed, the administrator can
     handle all day to day operations.

   o Machine rebooting

     The machines DO NOT need to be rebooted as part of the Sun Grid Engine
     installation.

   o It may be more convenient to have a file with the list of hosts that
     will be installed. The format for this file is one hostname per line. 
     The names may also be typed in manually when the installation prompts.

   o If any stty commands exist in the users' startup scripts, jobs
     submitted to Sun Grid Engine may fail as there is no terminal
     associated with a Sun Grid Engine batch job. If there are stty
     commands, one of the following must be done:

     o Remove all stty commands (and commands accessing a tty, like e.g.
       "biff") from the login files
     o Bracket the stty commands with an 'if' statement which checks for a
       terminal before executing. For example:

       tty -s             # checks terminal status
       if ($status == 0)  # succeeds if a terminal is present
         <place all stty commands in here>
       endif


6) Install Sun Grid Engine
--------------------------

   The installation is a two step process. First, the Sun Grid Engine files
   are installed and configured on the master. Then, a small installation is
   done on each execution host to configure and start the daemons, and to
   add automatic daemon startup to the init area. This requires logging on
   to each execution host as root and manually running the install program. 
   Alternatively, if there is a secure machine with root rsh access to all
   machines, the execution host install can be done from a single machine.

   o Step One - Install the master host

     As root, on the master host, run:

        install_qmaster

     This will install the Sun Grid Engine master. 

        install_execd

   o Step Two - Install execution hosts

     As root on the execution host machines, run:

        install_execd

     The installation programs start the Sun Grid Engine daemons, so at the
     completion of a successful install, Sun Grid Engine is up and running.
     If the master host will also be an execution host, run the following
     command as well:


7) Verify installation
----------------------

   After the installation is completed, the installation can be verified. 
   There are some sample scripts in $CODINE_ROOT/examples/jobs. First,
   source the proper settings file to setup the Sun Grid Engine environment:

      C-shell syntax:

         source $CODINE_ROOT/default/common/settings.csh

      Bourne shell syntax:

         . $CODINE_ROOT/default/common/settings.sh

   Then, to verify Sun Grid Engine is accepting jobs, execute the following:

      qsub $CODINE_ROOT/examples/jobs/sleeper.sh

   You should see output similar to the following:

      % qsub $CODINE_ROOT/examples/jobs/sleeper.sh 
      your job 1 ("Sleeper") has been submitted

   Verify that all of the queues have been installed properly by running
   the following:

      % qstat -f   (full listing of the queues)


8) Using Sun Grid Engine
------------------------

The main submit commands are qsub, qrsh and qtcsh. See the man pages for
submit(1) and qtcsh(1) for more details. 

qsub
----
In general, qsub is used for traditional batch submit, that is where
I/O is directed to a file. Note that qsub only accepts shell scripts, 
not executable files. There is an application script, qs, which will allow
qsub to accept executable files directly.

qrsh
----

Qrsh acts similar to the rsh command, except that a host name is not given.
Instead, a shell script or an executable file is run, potentially on any
node in the cluster. I/O is directed back to the submitter's terminal
window. By default if the job cannot be run immediately, qrsh will not 
queue the job. Using the '-now no' flag to qrsh will allow jobs to queue.
Note that I/O can be redirected with the shell redirect operators. For
example, to run the uname -a command:

qrsh uname -a

The uname of some machine the scheduler selects in the cluster will then
be displayed on the submitting terminal. To redirect the output,

qrsh uname -a > /tmp/myfile

The output from uname will be written to /tmp/myfile on the submitting
host. To allow the command to queue:

qrsh -now no uname -a

If a suitable host is not immediately available the command will block
until a suitable host is available. At that time, the command output will
be displayed on the submitting terminal.  

See the qrsh(1) man page for more details.

qtcsh
-----

Sun Grid Engine contains a modified tcsh, qtcsh which will automatically
submit jobs listed in a task file to the cluster. See the qtcsh(1) man page
for more details.


9) Contact and support information
----------------------------------

   http://www.sun.com/gridware
   http://supportforum.sun.com/gridengine/index.html
