Add README.md

README.md

@@ -0,0 +1,123 @@
+# 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>