bitcron

A framework for writing robust cron scripts with enhanced error handling, warning management, and automatic email reporting capabilities.

Overview

bitcron is designed to make cron jobs more reliable and easier to monitor by providing:

Structured error and warning reporting
Automatic email notifications for both successful runs and error conditions
Configurable logging with optional master log files
Fatal error handling that immediately stops execution
Clean exit codes for proper monitoring

Installation

From Debian Package

make pkg-deb
sudo dpkg -i ../bitcron_*.deb

Manual Installation

sudo cp src/bitcron /usr/bin/
sudo mkdir -p /etc/bitcron /var/log/bitcron
sudo cp etc/example.cron /etc/bitcron/

Usage

bitcron [-n] /path/to/crondefinition.cron [arg [arg ..]]

-n: Dry-run mode - output goes to stdout instead of email
crondefinition.cron: Path to your cron definition file
Additional arguments are passed to your bitcron_main() function

Cron Definition File Format

Your cron definition file must set these variables and implement a bitcron_main() function:

Required Variables

NAME: Terse descriptive name (alphanumeric, dash, underscore only)
AUTHOR: Your full name for tracking purposes
ESCALATE_MAILTO: Email address for error/warning notifications

Optional Variables

PATH: Search path for programs (recommended)
MAILTO: Email address for successful completion notifications
MASTERLOG: Path to persistent log file (e.g., /var/log/bitcron/${NAME}.log)

Example

NAME="backup-database"
AUTHOR="John Doe"
MAILTO="admin@example.com"
ESCALATE_MAILTO="alerts@example.com"
MASTERLOG="/var/log/bitcron/${NAME}.log"

bitcron_main()
{
    echo "Starting database backup"
    
    if ! pg_dump mydb > /backup/mydb.sql; then
        error "Database backup failed"
        return
    fi
    
    echo "Database backup completed successfully"
}

Available Functions

Within your bitcron_main() function, you have access to:

warning "message": Log a warning (increments warning counter)
error "message": Log an error (increments error counter)
fatal "message": Log a fatal error and immediately exit

Search Paths

bitcron searches for cron definition files in:

./ (current directory)
~/bitcron/
/etc/bitcron/
/usr/local/etc/bitcron/

Exit Codes

0: Success (no errors or warnings)
126: Warnings occurred (no errors)
127: Errors occurred
128: Usage error or missing required variables
Custom: Set RETVAL variable to override

Email Notifications

bitcron automatically sends emails using /usr/sbin/sendmail -t:

Success: Sent to MAILTO (if set) when no errors/warnings occur
Errors/Warnings: Sent to ESCALATE_MAILTO (always) and CC to MAILTO (if set)

Building

# Build Debian package
make pkg-deb

# Clean build artifacts  
make clean

Author

Pim van Pelt pim@ipng.ch

3.0 KiB Raw Permalink Blame History