124 lines
3.0 KiB
Markdown
124 lines
3.0 KiB
Markdown
# 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>
|