bit-cron(1)

NAME
bit-cron - Execute a BIT cronjob and mail the results in a standard way

SYNOPSIS
bit-cron /etc/cronscripts/my.cron <other args>

DESCRIPTION
bit-cron is an attempt to tidy up cronjobs which run on production servers at BIT (and their customers).

This program accepts exactly one argument, a filename consisting of the cron definition. This file is then sourced and executed, but within a framework that makes crons much easier to live with. You SHOULD have the filename of your crondefinition end in ".cron", so it is apparent to other people that this is indeed a cron definition.

If your cron definition filename is does not begin with a forward slash, it is searched for in a list of directories, currently /usr/share/bit-cron/cronscripts/ /etc/cronscripts/ and the CWD.

CRON DEFINITION - VARIABLES
The cron definition file consists of the following shell variables:

PATH : Optional. You can set a standard path for your cron to search programs in. Note that cron sets a minimal path, so you probably need this if you are going to call programs from weird places. Example: PATH=$PATH

NAME : Mandatory. The name of your script. This MUST be a terse descriptive name consisting of [A-Za-z0-9-_], and in particular no whitespace. It's used in logs and mails. Example: NAME="example"

MASTERLOG : Optional. If this is set, the transcript of the log is copied to this file upon completion. If it is not set, the transcript is silently deleted. Please make sure that this filename is writable for the calling user, and that its name reveals who wrote it (including $NAME is a good idea). Example: MASTERLOG="/var/log/bit-cron/cron-example.log"

MAILTO : Optional. If this is set, the transcript of the log is mailed to this user using /usr/sbin/sendmail -t, in the event of no warnings, errors, or fatal errors, aka 'if all went well'. If it is not set, the mail is not sent on succesful completion of this cronjob. Please use with care if your cron runs often. Example: MAILTO="noise@bit.nl"

ESCALATE_MAILTO : Mandatory. If this is set, the transcript of the log is mailed to this user using /usr/sbin/sendmail -t, in the event of any warning, error or fatal error, aka 'if anything borked'. Please make sure that this address is not a single person, but rather a role account. This ensures better closure and continuity. Example: ESCALATE_MAILTO="olympus@bit.nl"

BITCRONLOCK : Optional. If this is set, the bit-cron script refuses to run while another instance of the same bit-cron script is running. This is called processlocking or concurrencylocking and ensures only one instance of the script is running at a specific time. Useful for crons that run at a fast pace that could hammer your server or services.

BITCRONLOCKSILENT : Optional. If this is set, the bit-cron script will not send mails about lockfiles are found, only when the lock time limit is reached.

BITCRONLOCKLIMIT : Default: 86400. Number of seconds a cron job may be locked for before alarm emails will be sent. This is a bit of a fallback to prevent locked jobs that no-one notices.

Variables your script MUST NOT change are: ERR, WRN, HOSTNAME, FATAL, FQDN

CRON DEFINITION - SCRIPT EXECUTION
Your cron-definition does not shebang. It begins with these variables. It then has at least one function called func_cron(), in which you write your cron just like you normally would, but each step is prepended by a short oneliner describing what you are doing and appended with a line stating you are done doing it, followed by an empty line.

In your func_cron() script, you have three functions at your disposal: warning $TEXT error $TEXT fatal $TEXT where warning() prints the TEXT and increments the warning counter, error() increments the error counter and fatal() increments the error counter and immediately halts execution of the cron.

Please note that your func_cron() function MUST NOT use exit. This messes up the clean execution of this script, prohibiting it from mailing or returning a decent exitcode to the calling shell.

EXAMPLE
Take for example the stock cron definitions in /usr/share/bit-cron/ :
PATH=$PATH
NAME="example"
MASTERLOG="/tmp/cron-example.log"
MAILTO="noise@yourdomain.tld"
ESCALATE_MAILTO="problems@yourdomain.tld"
func_cron()
{
echo "Running rsync"
rsync blabla || warning "Could not rsync"
echo "Done (rsync)"
echo ""
echo "Doing something crucial"
crucial.sh blabla || fatal "Could not do the crucial stuff, aborting!"
echo "Done (crucial)"
echo ""
echo "Succesfully executed the cron"
}

which can be executed in a crontab as such :
0 8 * * * bit-cron /usr/local/cronscripts/run_everyday_at_0800.cron

In the event of a fatal error (retval of crucial.sh != 0), the cronscript
stops and mails to the ESCALATE_MAILTO mail address that there was a
serious error which needs human intervention. If all went well, the
MAILTO address is sent an email with the log.

EXIT STATUS
Return values of bit-cron depend on the presence of errors or warnings. If there are no errors nor warnings, 0 is returned to the calling shell. If there are errors, 127 is returned. If there are no errors, but there are warnings, 126 is returned. If you set the RETVAL variable somewhere (which is optional), that value is returned instead.

SECURITY
Bit-cron will refuse to run cron definition files as root, when the cron definition file is not owned by root:root, or when the file is group or others writable. To allow this insecure behaviour, add --insecure as the first argument to bit-cron.

AUTHOR
Pim van Pelt <pim@ipng.nl>, BIT BV <support@bit.nl>

SEE ALSO
crond(8), crontab(5), sendmail(8)