Installing a Grid Engine 6.0 Update Release
              -------------------------------------------

1) Who needs to read this document
2) Prerequisites
3) Stopping the Grid Engine cluster to start jobs
4) Shutting down the Grid Engine qmaster, scheduler and execution daemons
5) Installing the patch and restarting the software
6) Berkeley DB database update needed
   6.1) Backup BDB
   6.2) Update BDB
7) New startup script template for qmaster and execd startup (6.0u1)
   7.1) Recreate the startup script
   7.2) Copy the new startup scripts
8) Restarting the software
9) New functionality delivered with SGE 6.0 update releases
   9.1.  Avoid setting of LD_LIBRARY_PATH; inherited job environment (6.0u2)
   9.2.  DRMAA Java[TM] language binding available (6.0u2)
   9.3.  New options to optimize memory overhead and speed of qstat (6.0u2)
   9.4.  Tuning parameter for sharetree spooling (6.0u2)
   9.5.  New man pages (6.0u2)
   9.6.  Support for Solaris 10 on AMD64 (Opteron) (6.0u4)
   9.7.  Installation Improvements (6.0u4)
   9.8.  Berkeley DB database tools are included in the distribution (6.0u6)
   9.9.  Reworked "qstat -xml" output (6.0u7)
   9.10. Reworked PE range matching algorithm in the scheduler (6.0u7)
   9.11. New monitoring feature in qmaster (6.0u7)
   9.12. New parameter for specialized job deletion (6.0u7)
   9.13. New reporting parameter to control accounting file flush time (6.0u7)
   9.14. New reporting parameter for consumable resources control (6.0u12)

1) Who needs to read this document
----------------------------------

   This document describes how to install a Grid Engine 6.0 update release
   from a previous 6.0 revision.

   If you make a new installation of Grid Engine 6.0 or a newer update
   release please follow the directions in the N1 Grid Engine manuals which
   can be found at http://docs.sun.com.

   The terms "update release", "patch", "patch release", and "distribution"
   in this document are used interchangeably and refer to the most recent
   courtesy distribution of Grid Engine which includes binaries,
   documentation and architecture independent files (the "common" package)
   available on the binary download page.


2) Prerequisites
-----------------

   The courtesy binary distribution always contains a full set of all
   binaries.

   These installation instructions assume that you are running a homogenous
   Grid Engine cluster (called "the software") where all hosts share the
   same directory for the binaries. If you are running the software in a
   heterogenous environment (mix of different binary architectures), you
   need to apply the patch installation for all binary architectures as well
   as the "common" and "arco" packages.

   If you installed the software on local filesystems, you need to install
   all relevant patches on all hosts where you installed the software
   locally.

   By default, there should by no running jobs when the patch is installed.
   There may pending batch jobs, but no pending interactive jobs (qrsh,
   qmake, qsh, qtcsh).

   It is possible to install the patch with running batch jobs. To avoid a
   failure (and possible loss of your jobs) of a running 'sge_shepherd'
   process, it is necessary to move the old sge_shepherd binary (and copy it
   back prior to the installation of the patch).

   You cannot install the patch with running interactive jobs, 'qmake' jobs
   or with running parallel jobs which use the tight integration support
   (control_slaves=true in PE configuration is set).

   It is required to update all binaries and the "common" package to the
   same revision level. A mix if different versions of Grid Engine daemons
   and commands is not supported.


3. Stopping the Grid Engine cluster to start jobs
-------------------------------------------------

   Disable all queues so that no new jobs are started:

      # qmod -d '*'

   Optional (only needed if there are running jobs which should continue to
   run when the patch is installed):

      # cd $SGE_ROOT/bin
      # mv <arch>/sge_shepherd <arch>/sge_shepherd.sge60

   It is important that the binary is moved with the "mv" command. It should
   not be copied because this could cause the crash of an active shepherd
   process which is currently running job when the patch is installed.


4. Shutting down the Grid Engine qmaster, scheduler and execution daemons
-------------------------------------------------------------------------

   You need to shutdown (and restart) the qmaster and scheduler daemon and
   all running execution daemons.

   Shutdown all your execution hosts. Login to all your execution hosts and
   stop the execution daemons:

      # /etc/init.d/sgeexecd softstop

   Then login to your qmaster machine and stop qmaster and scheduler:

      # /etc/init.d/sgemaster stop

   Now verify with the 'ps' command that all Grid Engine daemons on all
   hosts are stopped. If you decided to rename the 'sge_shepherd' binary so
   that running jobs can continue to run during the patch installation, you
   must not kill the 'sge_shepherd' binary (process).


5. Installing the patch and restarting the software
---------------------------------------------------

   Now install the update release by unpacking all 'tar.gz' files (all
   binary packages and the "common" package).


6) Berkeley DB database update needed
-------------------------------------

   After installing this patch, and before restarting your cluster you need
   to update your Berkeley DB (BDB) database in the following cases:

      - you choose the BDB spooling option (not needed for classic
        spooling) either locally or with the BDB RPC option, and you are
        upgrading your cluster from SGE 6.0 or SGE 6.0u1 or SGE 6.0u2 or 
        SGE 6.0u3 to SGE 6.0u4 or higher.  

   6.1. Backup BDB
   ---------------

      For safety reasons, please make a full backup of your existing
      configuration. To perform a backup use this command

         % inst_sge -bup

   6.2. Update BDB
   ---------------

      Upgrade your BDB database. This is done as follows:

         % inst_sge -updatedb


7. New startup script template for qmaster and execd startup (6.0u1)
--------------------------------------------------------------------

   This patch changes the startup script of qmaster/scheduler/shadowd (the
   "sgemaster" script) and the startup script of the execution daemon
   ("sgeexecd"). Since these scripts are created from a template it is
   necessary to recreate the startup scripts and install them in the system
   wide boot script directory (e.g. /etc/init.d).

   The patch for Grid Engine 6.0u1 or higher comes with a few fixes for the
   startup script templates. If you are updating from Grid Engine 6.0 to a
   newer release you should create a new startup script. If you already
   updated to Grid Engine 6.0u1 or higher and you already executed the steps
   outlined below you don't need to repeat them.

   7.1. Recreate the startup script
   --------------------------------

      The new scripts are installed in <sge_root>/<cell>/common. A backup of
      the original scripts is saved in this directory as

         sgemaster_YYYY-MM-DD_HH:MM:ss
         sgeexecd_YYYY-MM-DD_HH:MM:ss

      where YYYY-MM-DD_HH:MM:ss defines the current date and time.

      Login as the root or admin user and source the environment settings
      for Grid Engine. The example below assumes your current shell is the
      Bourne shell or Korn shell

         # cd <sge_root>
         # . <cell>/common/settings.sh
         # ./inst_sge -rccreate

      The new startup scripts will be installed in <sge_root>/<cell>/common.

   7.2. Copy the new startup scripts
   ---------------------------------

      Copy the new startup scripts to the system wide rc file location on
      all qmaster, shadowd and execution hosts. Depending on the operating
      system this can be one of the following directories:

      - /etc/init.d
      - /etc/rc.d
      - /sbin/init.d


8. Restarting the software
--------------------------

   Please login to your qmaster machine and execution hosts and enter:

      # /etc/init.d/sgemaster etc/init.d/sgeexecd

   After restarting the software, you may again enable your queues:

      # qmod -e '*'

   If you renamed the shepherd binary, you may safely delete the old binary
   when all jobs which where running prior the patch installation have
   finished.


9. New functionality delivered with this patch
----------------------------------------------

   9.1. Avoid setting of LD_LIBRARY_PATH; inherited job environment (6.0u2)
   ------------------------------------------------------------------------

   There are two new "execd_params" (defined in the global or local cluster
   configuration) which control the environment inherited by a job:

      SET_LIB_PATH
      INHERIT_ENV

   By default, SET_LIB_PATH is false and INHERIT_ENV is true.  If
   SET_LIB_PATH is true and INHERIT_ENV is true, each job will inherit the
   environment of the shell that started the execd, with the SGE lib
   directory prepended to the lib path.  If SET_LIB_PATH is true and
   INHERIT_ENV is false, the environment of the shell that started the execd
   will not be inherited by jobs, and the lib path will contain only the
   SGE lib directory.  If SET_LIB_PATH is false and INHERIT_ENV is true,
   each job will inherit the environment of the shell that started the execd
   with no additional changes to the lib path.  If SET_LIB_PATH is false and
   INHERIT_ENV is false, the environment of the shell that started the execd
   will not be inherited by jobs, and the lib path will be empty.
   Environment variables which are normally overwritten by the shepherd,
   such as PATH or LOGNAME, are unaffected by these new parameters.

   9.2. DRMAA Java[TM] language binding available (6.0u2)
   ------------------------------------------------------

   The DRMAA Java language binding is now available. The DRMAA Java language
   binding library and documentation is contained in the patch for the
   "common" package. The DRMAA Java language binding library is located in
   the directory

      <sge_root>/lib/drmaa.jar

   The documentation can be found in

      <sge_root>/doc/javadocs

   9.3. New options to optimize memory overhead and speed of qstat (6.0u2)
   -----------------------------------------------------------------------

   The qstat client command has been enhanced to reduce the overall amount
   of memory which is requested from the qmaster. To enable these changes it
   is necessary to change the qstat default behavior. This is possible by
   defining a cluster-global or user-specific sge_qstat file. More
   information can be found in sge_qstat(5) manual page. In addition two new
   qstat options ("-u" and "-s") have been introduced to be used with the
   sge_qstat default file. Find more information in qstat(1).

   9.4. Tuning parameter for sharetree spooling (6.0u2)
   ----------------------------------------------------

   A new "qmaster_param" (configured in the global cluster configuration):

      STREE_SPOOL_INTERVAL=<time>

   can be configured to control the interval for how often the sharetree
   usage is spooled. The interval can be set to any time in the following
   formats:

       HH:MM:SS or
       <int>

   E.g.:

      STREE_SPOOL_INTERVAL=0:05:00
      STREE_SPOOL_INTERVAL=300

   This parameter is a tuning parameter only. It has the biggest effect on a
   system using classic spooling and bigger sharetrees and a slow
   filesystem.

   9.5. New man pages (6.0u2)
   --------------------------

   The following man pages have been added to the distribution:

      sge_qstat(5)     - new default request file for qstat(1)
      gethostbyaddr(1) - man page for commands in <sge_root>/utilbin/<arch>
      gethostbyname(1) - man page for commands in <sge_root>/utilbin/<arch>
      gethostname(1)   - man page for commands in <sge_root>/utilbin/<arch>
      getservbyname(1) - man page for commands in <sge_root>/utilbin/<arch>
      qping(1)         - man page for utility to monitor Grid Engine daemon
                         communication
   - Renamed man pages:
      sge_h_aliases.z -> host_aliases.z
      sge_h_aliases.5 -> host_aliases.5

   - Pre formatted and uncompressed man pages have been added to

      <sge-root>/catman/cat/cat{1,3,5,8}

   9.6. Support for Solaris 10 on AMD64 (Opteron) (6.0u4)
   ------------------------------------------------------
   
   A new binary architecture was introduced for Solaris 10 with 64bit 
   support on AMD64 Opteron CPUs. The new architecture is fully supported
   like all other architectures.

   9.7. Installation Improvements (6.0u4)
   --------------------------------------

   - Berkeley DB (BDB) RPC server auto installation and de-installation is now
    supported
   - Backup/restore for classic and BDB RPC server spooling supported
   - Daemon startup scripts create Linux LSB conforming "lock" file
   - Improved diagnosis messages during auto installation
   - Execution daemon un-installation leaves no references to de-installed
    execution host


   9.8. Berkeley DB database tools are included in the distribution (6.0u5)
   ------------------------------------------------------------------------

   All Berkeley DB database tools are now part of the N1 Grid Engine
   distribution (not for Microsoft Windows platform)

     db_archive 
     db_checkpoint
     db_deadlock 
     db_dump
     db_load
     db_printlog
     db_recover
     db_stat
     db_upgrade
     db_verify

   The HTML documentation for these tools is part of the "common" patch and
   can be found in:

     <sge_root>/doc/bdbdocs


   9.9. Reworked "qstat -xml" output (6.0u7)
   -----------------------------------------

   The schema for "qstat -xml" and the "qstat -xml" output have been
   reworked to ensure consistency between them and easy parsing of them via
   JAXB. The most noticeable change will the date output. It follows now the
   XML datetime format.


   9.10. Reworked PE range matching algorithm in the scheduler (6.0u7)
   -------------------------------------------------------------------

   The PE range matching algorithm is now adaptable and learns from the past
   decisions. This will lead to a much faster scheduling decision in case of
   pe-ranges. This can be controlled by a new scheduling configuration
   parameter: SELECT_PE_RANGE_ALG.  It allows to restore the old behavior. 

   See sge_conf(5) for more information.


   9.11. New monitoring feature in qmaster (6.0u7)
   -----------------------------------------------

   The monitoring allows to get detailed statistics what the qmaster
   threads are doing and how busy they are.  The statistics can be accessed
   via "qping -f" or from the qmaster messages file.  The feature is controlled
   by two qmaster configuration parameters:

      MONITOR_TIME          specifying the time interval for the statistics
      LOG_MONITOR_MESSAGE   enables/ disables the logging of the monitoring
                            messages into the qmaster messages file.

   See sge_conf(5) for more information.


   9.12. New parameter for specialized job deletion (6.0u7)
   --------------------------------------------------------

   A new "execd_param" (configured in the global cluster configuration):

      ENABLE_ADDGRP_KILL=true

   can be configured to enable addition code within the execution host to
   delete jobs. If this parameter is set then the supplementary group id's
   are used to identify all processes which are to be terminated when a job
   should be deleted. It has only effect for following architectures:

      sol*
      lx*
      osf4
      tru64

   See sge_conf(5) under "gid_range" for more information.


   9.13. New reporting parameter to control accounting file flush time (6.0u7)
   ---------------------------------------------------------------------------

   A new reporting parameter, "accounting_flush_time", controls the flush
   period for the accounting file. Previously, both the accounting and
   reporting files were flush at the same interval. Now they can be set
   independently. Additionally, buffering of the accounting file can now be
   disabled, allowing accounting data to be written to the accounting file
   as soon as it becomes available.

   See sge_conf(5) for more information.

   
   9.14. New reporting parameter for consumable resources control (6.0u12)
   -----------------------------------------------------------------------

   The new reporting parameter "log_consumables" controls writing of
   consumable resources to the reporting file. Default (log_consumables=true)
   is to write information about all consumable resources (their current usage
   and their capacity) to the reporting file, whenever a consumable resource
   changes either in definition, or in capacity, or when the usage of a
   consumable resource changes. When log_consumables is set to false, only
   those variables will be written to the reporting file, that are configured
   in the report_variables in the exec host configuration, see host_conf(5)
   for further information about report_variables.

   The default (log_consumables=true) has been chosen to be backward compatible
   to 6.1u2, but it is recommended to switch to log_consumables=false, and add
   the required consumables to the report_variables in the global host
   (qconf -me global).