NAME

gx-cron-job - Execute gx-map commands (for use in a cron job)

SYNOPSIS

gx-cron-job -help

gx-cron-job -version

gx-cron-job [options] [files]

DESCRIPTION

gx-cron-job, part of the gx-map system, is an administrative command. It is intended to simplify the job of setting up cron jobs for gx-map. Rather than setting up multiple cron jobs for various commands, you can run a single instance of gx-cron-job once per minute; it will execute other commands based on the gx-cron-job.conf file. Or you can run it in daemon mode and bypass cron altogether.

OPTIONS

Option processing is done using the Perl Getopt::Long module.

Options may be specified with a single or double leading '-' character. Option names may be abbreviated to whatever is unique. Arguments may be separated either by a blank or by an '=' character. For example, ``-foobar 42'', ``--foobar=42'', and ``-foob 42'' would all be equivalent.

-help
Display a usage message and exit.

-version
Display the software version number and exit.

-daemon
Run in a continuous loop, checking for jobs once per minute. The default is a single execution, suitable for running in a cron job.

In either mode, gx-cron-job re-reads the config file on every iteration (if its timestamp has changed), so any changes to the gx-cron-job.conf file will be reflected immediately.

-config-file file
Use the specified configuration file. The default is etc/gx-map/gx-cron-job in the gx-map installation directory.

-[no]check
By default, gx-cron-job checks on startup that the specified commands are executable. Use -nocheck to disable this check.

-dryrun
Display commands but don't execute them.

-debugging
Enable debugging output.

USAGE

The gx-map system depends on certain administrative commands to be executed repeatedly, usually from a cron job. It's possible to execute the necessary commands directly from your crontab, but the gx-cron-job command is intended to simplify this.

The behavior of the gx-cron-job command is controlled by a configuration file; see below.

CONFIGURATION FILE

The default gx-cron-job configuration file is etc/gx-map/gx-cron-job.conf in the gx-map installation directory. This file is not installed by default, but a sample configuration file is provided in the release as sample-gx-cron-job.conf.

The configuration file consists of a sequence of sections. Each section consists of a line containing only an opening brace '{', a sequence of lines each containing an attribute name followed by the corresponding attribute value, and a line consisting only of a closing brace '}'. (The similarity to the format of the requests.log file is not a coincidence; the same code is used to parse both.)

Sections are processed in the order specified in the etc/gx-map/gx-cron-job.conf file. Multiple commands are executed in sequence, not concurrently.

The permitted attributes are:

name string
An arbitrary name for this section, used in error messages.

interval minutes
interval minutes+minutes
How often the command is executed. The value may be either a decimal integer X, indicating that the command is executed every X minutes, or a pair of the form X+Y, which causes the command to be executed every X minutes with an Y-minute offset.

For example, ``interval 15'' causes the command to be executed at 0, 15, 30, and 45 minutes after each hour; ``interval 15+5'' causes it to be executed at 5, 20, 35, and 50 minutes after each hour.

Intervals are based on raw Unix time (elapsed time since 1970-01-01 00:00:00 GMT). For example, a command with an interval of 1440 minutes (24 hours) will execute at midnight UTC, not midnight local time. For an interval that is a factor of one hour, this shouldn't be relevant.

The interval attribute is mandatory.

hostname name
Execute the command only if running on the specified host. The hostname is checked against the result of the Gridmap_Utils::Get_Hostname function, which may not be the same as the result of the system hostname command. (Use gx-util-test get_hostname to check this.)

command
There can be one or more commands in each section. If no absolute path is specified (i.e., the command does not start with a '/' character), it is assumed to be in the sbin directory of the gx-map installation directory. The commands are executed in the order specified.

At least one command must be specified.

Within the command, the string ``%HOSTNAME%'' is replaced with the full hostname on which the command is executed (see gx-util-test get_hostname), and the string ``%VERSION%'' is replaced with the gx-map version number.

Within

SEE ALSO

gx-map(7), gx-util-test(8)

AUTHOR

Keith Thompson, San Diego Supercomputer Center, <kst@sdsc.edu>

COPYRIGHT AND LICENSE

See the file LICENSE in the gx-map distribution, installed in the etc/gx-map subdirectory.