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 theCrabClient
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
andtempl
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 noCRABID=
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 theMAILTO
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 ifcrabsh
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