Client Configuration

There are two Crab client commands: the crab utility, and the crabsh wrapper shell. Cron jobs can either be run under crabsh, or they can be updated to report their own status to the Crab server.

Configuration

The Crab clients are configured by a crab.ini file which can be placed either in /etc/crab/ or ~/.crab/. The file specifies how to contact the Crab server, and the username and hostname which the client will use to report cron jobs.

% cp doc/crab.ini ~/.crab/

The configuration can be checked with the crab info command. This reports the settings, and indicates which configuration files were read. It is a useful way to check that everything is in order before importing a crontab.

The crabsh Wrapper

crabsh is a wrapper script designed to act like a shell. It can therefore be invoked by cron via the SHELL variable, for example:

PYTHONPATH=/path/to/crab/lib
SHELL=/path/to/crab/scripts/crabsh
0 10 * * 1-5 CRABID=test echo "Test cron job"

Where the rules following the SHELL assignment will be run with the wrapper. The PYTHONPATH will need to be set if Crab is not installed where the system can find it. Cron requires the full path when specifying the SHELL. The CRABID parameter is used to give the cron job a convenient and unique name. This is optional, unless there are multiple jobs with the same command, in which case they would otherwise be indistinguishable. However if it specified, then it must be unique for a given host and user, as the Crab server will use it in preference to the command string to identify cron job reports.

crabsh will notify the server when the job starts, and when it finishes, assuming it succeeded if the exit status was zero.

Crab-aware Cron Jobs

Alternatively a cron job can report its own status to the Crab server. The most straightforward way to do this is to execute the crab utility. So a cron job written as a shell script could include commands such as:

% crab start -c "$0"
% crab finish -c "$0"
% crab fail -c "$0"

In this way you can also report a warning with crab warning or an unknown status with crab unknown.

Python

If the cron job is written in Python, it could import crab.client directly and make use of the CrabClient class.

Perl

A Perl module WWW::Crab::Client is also available.

Other languages

Other language libraries could be written. They would need to make HTTP PUT requests with an appropriate JSON message.

Managing the Cron Job List

The Crab server needs to be given the schedule for each job so that it can detect when a job is late or missed. This is done by “importing” a user’s crontab file:

% crab import

The database entries can then be checked by “exporting” them, again using the crab utility:

% crab export
> CRON_TZ=Pacific/Honolulu
> 0 10 * * 1-5 CRABID=test echo "Test cron job"

The output is a set of crontab-style lines representing the entries from the database. The crontab can be retrieved exactly as last imported (from a separate database table containing the raw crontab) by giving the --raw option as follows:

% crab export --raw

This is useful as a backup in case a crontab is accidentally lost. However it will not contain any new jobs which have been added automatically by the Crab server since the last import.

Cron Job Parameters

In order to specify the Crab specific parameters of a cron job, Bourne-style shell variables at the start of a command are used. The syntax for each cron job is as follows:

<schedule> [CRABIGNORE=yes] [CRABID=<identifier>] <command string>

A command starting with CRABIGNORE set to a value other than 0/no/off/false will be ignored when importing a crontab, and crabsh will not report its status to the Crab server.

A CRABID specification will override any CRABID environment variable in effect, and is a better way of specifying the identifier as it can not apply to more than one cron job. There should not be multiple jobs with the same identifier for any user and host.

The Crab parameters can be placed in any order before the remainder of the command string, but they must precede any other variables.

Environment Variables

CRABCLIENTHOSTNAME

The host name to be used by Crab clients to identify themselves, overriding any value in the configuration files.

CRABECHO

If present and not set to 0/no/off/false then crabsh will print out the standard output and standard error it receives from the cron job. This allows the output to be sent by email via cron’s default behavior as well as being captured by the Crab system.

CRABHOME

If present overrides the Crab server home directory, where the res and templ directories are to be found.

CRABHOST

Specifies the Crab server to which clients should connect, overriding the setting in the configuration file.

CRABID

Specifies the job identifier which crabsh will use to file reports if there is no CRABID= variable at the start of the cron command. This should be used with caution to avoid specifying the same identifier for multiple cron jobs.

CRABIGNORE

Prevents Crab from acting on specific cron jobs. Jobs imported with this value present and not set to 0/no/off/false will not be entered into the database. Additionally if the crabsh wrapper script is used to run such a job, it will not report its status to the Crab server.

CRABPIDFILE

Gives the path to a PID file which crabsh should use to control the execution of a cron job. When this parameter is set, it will use the file to try not to run multiple copies of the job at the same time. Each job should have a separate PID file, so this parameter is most conveniently given at the start of a command string.

CRABPORT

Specifies the port on the Crab server, overriding the setting in the configuration file.

CRABQUIET

If present and not set to 0/no/off/false then crabsh will not write fallback messages to standard output except in case of failure. Such messages would normally be sent by cron to the MAILTO address. This option can also be specified via the client configuration files.

CRABSHELL

The shell which crabsh will use to invoke the cron job command. Defaults to /bin/sh regardless of the user’s shell to replicate cron’s behavior.

CRABSYSCONFIG

The directory to be searched for system-level configuration files. If not set, then /etc/crab will be used.

CRABUSERCONFIG

A directory to search for user-level configuration files. If not set then ~/.crab will be used.

CRABUSERNAME

The user name to be used by Crab clients to identify themselves, overriding any value in the configuration files.

CRABWATCHDOG

Specifies a timeout (in minutes) which crabsh should apply to the cron job, killing it and reporting status “watchdog” if exceeded. (Requires Python 3.3 or the subprocess32 backport module.)

CRON_TZ

Cron reads this variable to know in which timezone to interpret the crontab schedule. When the server receives a crontab, it will check for this timezone and use it to override the general timezone which the crab utility will send with the crontab (if it is able to determine it).

MAILTO

Configures the email address to which cron sends email. This is useful when CRABECHO is on, or if crabsh needs to report a failure to contact the Crab server.

SHELL

Cron uses this variable to select the shell which will be used to execute the cron jobs. The full path must be specified. Crab does not use this variable itself.

TZ

This can be set to the system timezone, in which case crab import will use it as the default timezone for the crontab.

Example Configuration File

Here is the example client configuration file crab.ini which is distributed with Crab:

# Configure how to connect to the server where the Crab daemon is running.
[server]
host = localhost
port = 8000
# Timeout for communication with the server (seconds).
# timeout = 30
# Number of times to attempt to connect to server.
# max_tries = 1
# Delay between connection attempts (seconds).
# retry_delay = 5

# Configuration for this client.
[client]
# Override hostname provided by OS if required.
# hostname = host

# Override username provided by OS if required.
# username = user

# Attempt to use fully qualified domain name for client (if not specified).
# use_fqdn = false

# Configure crabsh behavior.
[crabsh]
# Choose whether to honor the inhibit message on job start.
# allow_inhibit = true
# Write fallback messages to standard output only on failure.
# quiet = false