# 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

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

### Manual Installation

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

## Usage

```bash
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

```bash
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

```bash
# Build Debian package
make pkg-deb

# Clean build artifacts  
make clean
```

## Author

Pim van Pelt <pim@ipng.ch>