                 Rotating and truncating Grid Engine logfiles
                 --------------------------------------------

___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__

Content
-------
1) Description
2) Variables
3) Command line parameters
4) Examples
5) Using logrotate

1) Description
--------------
 
   Grid Engine daemons create logfiles called "messages" in their respective
   spool directories. Also an 'accounting' file is created. The current Grid
   Engine release provides no mechanism for truncating and rotating the log
   files and the 'accounting' file automatically.

   Therefore a script template for truncating logfiles, and the accounting
   file is provided in the directory

      <sge_root>/util/logchecker.sh

   This script is copied during qmaster installation to the
   '<sge_root>/<sge_cell>/common' directory.

   Alternatively, you may use a system facility like logrotate(1) --
   see 5) below.

   The script is not activated by any of the Grid Engine daemons
   automatically. It is intended to be edited according to the needs of your
   site. After customizing the script you can add it to your crontab(s). The
   script is designed to run in verbose mode or completely silent. It can
   also run in a mode where it only prints what would be done. The script
   accepts only two command line parameters for overriding the "ACTION_ON"
   parameter and the location of the exec daemon spool directory (see
   below).


   Grid Engine daemons create logfiles in the following directories. 
   'qmaster_spool_dir' and 'execd_spool_dir' are defined in the global
   cluster configuration, the '<execd_spool_dir>' can be overridden in the
   local cluster configuration of every execution host (usually this is not
   done). The <sge_cell> directory usually is called 'default', and only if
   the $SGE_CELL variable is used, 'default' is overridden.

   Location of Grid Engine log files:

      <qmaster_spool_dir>/messages
      <execd_spool_dir>/<hostname>/messages
      <sge_root>/<sge_cell>/common/accounting

   Since these directories can all be located in the same directory
   hierarchy in a shared NFS filesystem, or the execd spool directories can
   point to a local directory, it is possible to specify with the
   "ACTION_ON" parameter (see below) what 'messages' files should be rotated
   when the script is called.


2) Variables
------------

   The following variables need to be configured in the script. The "|"
   character specifies an alternative. All variables in the script must be
   entered in Bourne shell syntax. So there may be no white space before or
   after the equal "=" sign.

   UNCONFIGURED=yes|no

      After the script is configured you should set this value to "no". If
      set to "yes" (or any other value), the script only will print out what
      would be done.
 
      Default: UNCONFIGURED=yes


   ECHO=:|echo

      The colon ":" is the null command in the shell. If you set the
      variable to this value, the script will work silently (only error
      messages are printed).  If you set the value to "echo" the script will
      print what it is currently doing.

      Default: ECHO=echo


   SGE_ROOT=<your_sge_root>

      Enter the path of your SGE_ROOT directory here.

      Default: SGE_ROOT=undefined

   SGE_CELL=default|<your_cell_name>

      Enter the name of your cell, if not 'default'

      Default: SGE_CELL=default


   ACTION_ON=1|2|3|4

      1 = work on qmaster and scheduler "messages" files only
      2 = work on "messages" file on current host only
      3 = work on all accessible execd "messages" files of global config
      4 = work on qmaster "messages" and all accessible execd "messages" files

      Default: ACTION_ON=4

   ACTIONSIZE=<size_inkilobyte>

      rotate/delete only if file size exceeds ACTIONSIZE in kilobytes. If
      ACTIONSIZE is set to 0, always work on "messages" file.

      Default: ACTIONSIZE=0


   KEEPOLD=<number>

      Defines the number of old messages files to be preserved. E.g. "30"
      means that "messages.0" to "messages.29" are saved. A value of "0"
      means no backup is done. The most recent messages file has the
      extension ".0".

      Default: KEEPOLD=30
      
   GZIP=yes|no

      yes = compress rotated "messages.0" file with gzip
      no  = leave rotated "messages.0" file uncompressed

      Default: GZIP=yes


   ACCT=yes|no

      yes = rotate accounting file when rotating qmaster 'messages' file
      no  = don't rotate accounting file

      Default: ACCT=no

3) Command line parameters
--------------------------

   The script accepts the following command line parameters:

   -execd_spool <spool_dir_of_local_execd>

      Define the base directory of the execd spool directory. Do not add the
      unqualified hostname in the command line. The hostname is added
      automatically by the script.

   -action_on 1|2|3|4

      Override the "ACTION_ON" variable in the script.


4) Examples:
------------

   a) All Grid Engine spool directories are shared. You can call the script
      on any of your Grid Engine hosts or on your file server.

      --> set ACTION_ON to "4" in the script. Set other values according to
          your needs and add the script to your crontab of one of the above
          machines.


   b) Grid Engine execd spool are defines only through the global
      cluster configuration, but point to a local directory.

     --> set ACTION_ON="3". Add the start of the script to all crontabs
         of your execds in your cluster. On your qmaster machine (or on your
         file server) add the following call of the script to your crontab:

         <path_to_script>/logchecker.sh -action_on 1


   c) Grid Engine spool directories of execds are defined in the local
      configuration.

      --> . Set ACTION_ON="2" in the script

          . On  your qmaster machine (or on your file server) add the
            following call of the script to your crontab:

               <path_to_script>/logchecker.sh -action_on 1

          . On your exec hosts add the following line:

               <path_to_script>/logchecker.sh -execd_spool <local_execd_spool>


5) Using logrotate

It is possible simply to use logrotate(1) (or a similar system) to do
the rotation on the same basis as files from syslog(8) etc. Here is a
logrotate example, placed in /etc/logrotate.d/sge. It is necessary to
substitute the actual values of $SGE_ROOT and $SGE_CELL for your
installation.
$SGE_ROOT/$SGE_CELL/common/accounting {
    compress
    missingok
    notifempty
    maxage 400
    monthly
    rotate 14
}

$SGE_ROOT/$SGE_CELL/spool/*/messages {
    compress
    missingok
    notifempty
    maxage 30
    weekly
    rotate 5
}

$SGE_ROOT/$SGE_CELL/spool/dbwriter/dbwriter.log {
    compress
    missingok
    notifempty
    maxage 30
    weekly
    rotate 5
}

# If MONITOR=1 in the scheduler params
$SGE_ROOT/$SGE_CELL/common/schedule {
    compress
    missingok
    notifempty
    maxage 2
    daily
    rotate 2
}

# Don't compete with dbwriter.
#$SGE_ROOT/$SGE_CELL/common/reporting {
#    compress
#    missingok
#    notifempty
#    maxage 90
#    weekly
#    rotate 12
#}
