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