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


Content
-------

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


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

   Please read through this entire installation procedure before beginning
   with the installation of Grid Engine.


2) Download the current distribution
------------------------------------

   Grid Engine is available from the following download servers:

   From Sun Microsystems:

      http://www.sun.com/gridware

   From the Grid engine Open Source site:

      http://gridengine.sunsource.net


3) Create a 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.  We recommend 'sgeadmin' as the
   administrator account belonging to the 'adm' group.

   The administrator account must exist on all hosts in the cluster prior 
   to installation.  This can be done by either including this information
   in the local NIS/NIS+ database, or by adding entries explicitly to
   /etc/passwd and /etc/group on all hosts.

   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. The port number below shold be seen as an example only.

      o NIS (Yellow Pages) services or NIS+ database
     
        Add the following to the services database:

           sge_commd          536/tcp     # communication port for Grid Engine

      o Add the above line manually to the /etc/services file on each machine 


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

   As the Grid Engine administrator user, do the following:

   If you received the distribution in "tar.gz" format

      o Create a directory for Grid Engine (eg, /gridware/sge).
        This directory must be accessible via NFS to all Grid Engine
        hosts. It can be either on a host in the cluster (eg, the master
        host), or on a dedicated file server or file server appliance.
        
        NOTE: this directory is hereafter referred to as $SGE_ROOT.

      o Unpack the distribution to this directory.

      o Verify the file permissions with the script

            $SGE_ROOT/util/setfileperm.sh

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

   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)

   If you received the distribution in another format

      o Follow the directions you received how to install the files of the
        distribution with the correct permissions


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

   o Grid Engine must be installed as root

     The 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 Grid Engine is installed, the administrator user
     can handle all day to day operations, and you can grant administrative
     rights to ordinary users as well.

   o Machine rebooting

     The machines DO NOT need to be rebooted as part of the Grid Engine
     installation. (The exception is if you run Grid Engine, Enhanced
     Edition, on SGI systems).

   o Host list file

     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 Shell configuration

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

     o Remove all stty commands from the login files
     o Bracket the stty commands with an 'if' statement which checks for a
       terminal before executing. For example, in csh syntax:

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


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

   The installation is a two step process. First, the Grid Engine files are
   installed and configured on the master. Then, a small installation script
   is executed on each execution host to configure and start the daemons,
   as well as 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 on all exec hosts
   in a single step from the secure machine.

   o Step One - Install the master host

     As root, on the master host, cd to $SGE_ROOT and run:

        ./install_qmaster

     This will install the Grid Engine master/scheduler. 


   o Step Two - Install execution hosts

     As root on the execution host machines, cd to $SGE_ROOT and run:

        ./install_execd

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

     o Noninteractive installation

       If you wish to run the install scripts and accept all default options
       without interaction, you can execute them with the -auto and -fast
       flags, for example:

          ./install_execd -auto -fast

       './install_execd -help' and './install_qmaster -help' will give a list
       of all flags for each command.
     
     o Cluster installation

       If you want to install many exec hosts simultaneously using the default
       options, you can use the 'install_cluster.sh' script in the directory
       $SGE_ROOT/util.  This script needs to be run from a machine which has
       root rsh privilege on all exec hosts.  Please note that each machine
       needs to already fulfill the prerequisite conditions listed in Steps
       3 and 4.  'install_cluster.sh -help' will tell you its usage.

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

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

   C-shell syntax:

      % source $SGE_ROOT/default/common/settings.csh

   Bourne shell syntax:

      % . $SGE_ROOT/default/common/settings.sh

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

      % qsub $SGE_ROOT/examples/jobs/sleeper.sh

   You should see output similar to the following:

      % qsub $SGE_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   (shows full listing of the queues)


8) Using 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, where I/O
   is directed to a file. Note that qsub only accepts shell scripts, not
   executable files --- wrapper scripts must be used to submit binary
   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
   -----

   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) Copyright
------------
___INFO__MARK_BEGIN__
   This following copyright statement applies to this file only. It does not
   imply that this statement covers other files of a Grid Engine
   distribution. See the directory '<sge_root>/3rdparty' for a summary of
   other copyrights of this Grid Engine distribution.

   The Contents of this file are made available subject to the terms of
   the Sun Industry Standards Source License Version 1.2
 
   Sun Microsystems Inc., March, 2001
 
 
   Sun Industry Standards Source License Version 1.2
   =================================================
   The contents of this file are subject to the Sun Industry Standards
   Source License Version 1.2 (the "License"); You may not use this file
   except in compliance with the License. You may obtain a copy of the
   License at http://gridengine.sunsource.net/Gridengine_SISSL_license.html
 
   Software provided under this License is provided on an "AS IS" basis,
   WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
   WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
   MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
   See the License for the specific provisions governing your rights and
   obligations concerning the Software.
 
   The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 
   Copyright: 2001 by Sun Microsystems, Inc.
 
   All Rights Reserved.
___INFO__MARK_END__
