cronn

KO | EN

gitlite — search

#hacktoberfest #typescript #golang #machine-learning #rust #deep-learning #docker #macos #nodejs #kubernetes #awesome-list #vue #pytorch #mcp

(★ 113)

cron service with extras

cronn Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# cronn - cli cron replacement and scheduler container

[![Build Status](https://github.com/umputun/cronn/workflows/build/badge.svg)](https://github.com/umputun/cronn/actions) [![Coverage Status](https://coveralls.io/repos/github/umputun/cronn/badge.svg?branch=master)](https://coveralls.io/github/umputun/cronn?branch=master)

Cronn is a crontab jobs scheduler with some nice extras. It allows to run commands on specified time intervals and can be used directly as well as from a container.

## Why cronn?

Simple cron scheduling with visibility. Single binary, embedded SQLite, no external dependencies.

**What you get**:

- crontab and YAML formats (auto-detected by extension)
- web dashboard with job history and manual execution
- hot reload on config changes (+ SIGHUP support)
- graceful shutdown waits for running jobs
- auto-resume after container/process restart
- date templates including business day support
- conditional execution (CPU/memory/disk thresholds, custom scripts)
- per-job settings override global config in YAML
- notifications (Slack, Telegram, email, webhook)
- retry with backoff, jitter, deduplication, log rotation

**What you won't deal with**:

- silent failures with logs scattered across system files
- environment differences between shell and scheduler
- multiple config files per job
- Node.js or Python runtime requirements
- external database setup

## Use cases

- Run any job with easy to use cli scheduler
- Schedule tasks in containers (`cronn` can be used as CMD or ENTRYPOINT)
- Use `ghcr.io/umputun/cronn` as a base image

## Installation

### From GitHub Releases

download the latest release for your platform from the [releases page](https://github.com/umputun/cronn/releases/latest).

### Homebrew (macOS and Linux)

```bash
brew install umputun/apps/cronn
```

### Debian/Ubuntu (deb package)

```bash
# download and install the latest deb package
wget https://github.com/umputun/cronn/releases/latest/download/cronn_<version>_linux_amd64.deb
sudo dpkg -i cronn_<version>_linux_amd64.deb
```

### RHEL/CentOS/Fedora (rpm package)

```bash
# download and install the latest rpm package
wget https://github.com/umputun/cronn/releases/latest/download/cronn_<version>_linux_amd64.rpm
sudo rpm -i cronn_<version>_linux_amd64.rpm
```

### Alpine Linux (apk package)

```bash
# download and install the latest apk package
wget https://github.com/umputun/cronn/releases/latest/download/cronn_<version>_linux_amd64.apk
sudo apk add --allow-untrusted cronn_<version>_linux_amd64.apk
```

### Docker

```bash
docker pull ghcr.io/umputun/cronn:latest
docker run -v $(pwd)/crontab:/srv/crontab ghcr.io/umputun/cronn -f /srv/crontab
```

releases are automated via GitHub Actions. to create a new release, push a tag:

```bash
git tag v1.x.x
git push origin v1.x.x
```

## Basic usage
 
- `cronn -c "30 23 * * 1-5 command arg1 arg2 ..."` - runs `command` with `arg1` and `arg2` every day at 23:30
- `cronn -c "@every 5s ls -la"` - runs `ls -la` every 5 seconds
- `cronn -f crontab` - runs jobs from the `crontab` file (traditional crontab format)
- `cronn -f config.yml` - runs jobs from the `config.yml` file (YAML format, auto-detected by extension)
- `cronn -f crontab --web.enabled --web.address=:8080` - runs jobs with web dashboard available at http://localhost:8080

Scheduling can be defined as:

- standard 5-parts crontab syntax `minute, hour, day-of-month, month, day-of-week`
- @syntax (descriptors), like `@every 5m`, `@midnight`, `@daily`, `@yearly`, `@annually`, `@monthly`, `@weekly` and `@hourly`.

Cronn also understands various day-realted templates evaluated at the time of job's execution:

**Standard Date Templates:**

- `{{.YYYYMMDD}}` - current day in local TZ
- `{{.YYYYMMDDEOD}}` - current business day based on EOD threshold (default: 17:00)
- `{{.YYYY}}` - current year
- `{{.YYYYMM}}` - year and month
- `{{.YYMMDD}}` - current day (short form YYMMDD)
- `{{.YY}}` - current year (short form)
- `{{.MM}}` - current month
- `{{.DD}}` - current day
- `{{.ISODATE}` - day-time formatted as `2006-01-02T00:00:00.000Z` (RFC3339)
- `{{.UNIX}}` - unix timestamp (in seconds)
- `{{.UNIXMSEC}}` - unix timestamp (in milliseconds)

**Weekday Templates (W-prefixed):**

These templates automatically skip backward to the previous business day (skipping weekends by default):

- `{{.WYYYYMMDD}}` - previous business day
- `{{.WYYYYMMDDEOD}}` - previous business day with EOD logic
- `{{.WYYYY}}` - year from previous business day
- `{{.WYYYYMM}}` - year-month from previous business day
- `{{.WYYMMDD}}` - short date from previous business day
- `{{.WISODATE}}` - ISO date from previous business day
- `{{.WYY}}`, `{{.WMM}}`, `{{.WDD}}` - year/month/day components from previous business day

**Business Day Logic:**

- EOD (End of Day) templates use a threshold hour (default: 17:00/5pm) to determine which business day to use
- If current time is before EOD threshold, uses previous business day
- If current time is at or after EOD threshold, uses current business day
- Weekday templates skip Saturday and Sunday by default
- Example: Running on Monday at 9am, `{{.WYYYYMMDD}}` returns Friday's date (skipping weekend)

Templates can be passed in command line or crontab file and will be evaluated and replaced at the moment 
cronn executes the command. For example `cronn "0 0 * * 1-5" echo {{.YYYYMMDD}}` will print the current date every 
weekday on midnight.

### Alternative Template Delimiters

In some situations, templates can conflict with application-specific templates that also use `{{` and `}}` syntax.
To avoid conflicts, cronn supports alternative template delimiters using `[[` and `]]` by passing the `--alt-template` 
flag (or setting the `CRONN_ALT_TEMPLATE` environment variable).

For example:
```bash
# Normal template syntax
cronn -c "0 0 * * *" echo {{.YYYYMMDD}}

# Alternative template syntax (useful when command uses {{ }} for its own templates)
cronn --alt-template -c "0 0 * * *" echo [[.YYYYMMDD]]

# In crontab file with alternative templates enabled
cronn --alt-template -f crontab
# where crontab contains: 0 0 * * * backup.sh --date=[[.YYYYMMDD]]
```

This is particularly useful when running commands that use Go templates, Helm charts, or other templating systems
that conflict with cronn's default `{{` and `}}` delimiters.

### Business Day Template Examples

Weekday and EOD templates are useful for financial systems, reporting, and backup jobs that need to align with business days:

```bash
# Backup with previous business day date (skips weekends)
cronn -c "0 1 * * 1-5" backup.sh --date={{.WYYYYMMDD}}

# Report for business day based on EOD logic
# If run before 5pm, uses previous business day; after 5pm uses current day
cronn -c "0 18 * * *" generate-report.sh {{.YYYYMMDDEOD}}

# Example behavior:
# Monday 2025-01-06 at 9am:
#   {{.YYYYMMDD}}     → 20250106 (current day)
#   {{.WYYYYMMDD}}    → 20250103 (Friday, skipped weekend)
#   {{.YYYYMMDDEOD}}  → 20250103 (before 5pm EOD, uses previous business day)

# Monday 2025-01-06 at 6pm:
#   {{.YYYYMMDD}}     → 20250106 (current day)
#   {{.WYYYYMMDD}}    → 20250103 (Friday, skipped weekend)
#   {{.YYYYMMDDEOD}}  → 20250106 (after 5pm EOD, uses current day)
```

### Configuration file formats

Cronn supports two configuration file formats, automatically detected by file extension:

#### Traditional crontab format (default)
Any file without `.yml` or `.yaml` extension is treated as traditional crontab:
```
# crontab format
*/5 * * * * ls -la .
*/2 1-18 * * * export
@every 1h15m something blah bad
```

#### YAML format
Files with `.yml` or `.yaml` extension are parsed as YAML:
```yaml
jobs:
  # Using traditional spec field
  - spec: "*/5 * * * *"
    command: "ls -la ."
    name: "Directory listing"  # optional descriptive name
  
  # Using structured sched field (alternative to spec)
  - sched:
      minute: "0"
      hour: "2"
    command: "backup /data"
    name: "Nightly backup"
  
  # More complex sched example
  - sched:
      minute: "0,30"
      hour: "9-17"
      weekday: "1-5"
    command: "sync files"
    name: "Business hours sync"
  
  # Job with custom retry configuration (per-job repeater)
  - spec: "0 */4 * * *"
    command: "backup.sh"
    name: "Database backup"
    repeater:
      attempts: 5        # Retry up to 5 times (overrides global setting)
      duration: 30s      # Start with 30 second delay
      factor: 2.0        # Double the delay each time
      jitter: true       # Add randomization to delays
  
  # @-descriptors work with spec field
  - spec: "@midnight"
    command: "cleanup temp"
```

The YAML format supports:

- Two ways to define scheduling:
  - `spec`: Traditional cron string or @-descriptors
  - `sched`: Structured format with separate fields (minute, hour, day, month, weekday)
- Optional `name` field for job description
- Optional `repeater` field for job-specific retry configuration
- Optional `conditions` field for conditional execution based on system resources
- JSON Schema validation for configuration correctness

Note: `spec` and `sched` are mutually exclusive - use only one per job. Empty `sched` fields default to `*`.

The YAML configuration is validated against an embedded JSON schema that ensures:

- Required fields are present
- Field values meet constraints (e.g., valid cron patterns, reasonable retry attempts)
- Configuration conflicts are detected (e.g., both spec and sched defined)
- Invalid configurations will prevent cronn from starting

Example with repeater configuration:
```yaml
jobs:
  - spec: "0 * * * *"
    command: "critical-backup.sh"
    name: "Hourly backup"
    repeater:
      attempts: 5       # Try 5 times instead of global default
      duration: 2s      # Initial delay of 2 seconds
      factor: 2.5       # Multiply delay by 2.5 on each retry
      jitter: true      # Add random jitter to delays
```

Example with conditional execution:
```yaml
jobs:
  - spec: "0 2 * * *"
    command: "backup.sh"
    name: "Nightly backup"
    conditions:
      cpu_below: 50           # Only run if CPU usage is below 50%
      disk_free_above: 20     # And disk has at least 20% free space
      max_postpone: 2h        # Wait up to 2 hours for conditions
      check_interval: 5m      # Check every 5 minutes
```

Both formats support the same template variables.

## Web Dashboard

Cronn includes a modern web dashboard for monitoring and managing cron jobs. The web UI provides:

### Features

- **Real-time job monitoring** with live updates every 30 seconds
- **Persistent job history** stored in SQLite database that survives restarts
- **Manual job execution** with advanced capabilities:
  - Edit commands before execution for one-off modifications
  - Override template variables with custom dates (YYYYMMDD format)
  - Execution history showing last 50 runs with both base and executed commands
  - Visual indicators for customized manual runs
- **Multiple view modes**: Card view and compact list view with toggle button
- **Sorting options**: Sort jobs by original order, last run time, or next run time
- **Job enable/disable toggle**: Disable individual jobs from the dashboard without editing config files
- **Status filtering**: Filter jobs by status (all, running, success, failed, idle)
- **Light, dark, and auto themes** with automatic system preference detection
- **Job statistics bar** showing total jobs with a success/failed/idle breakdown, currently running jobs, and next execution time. The total and each breakdown count are clickable to filter jobs by that status, kept in sync with the filter button
- **Detailed job information** including schedules, commands, and execution history
- **Status indicators** with color-coded job states (idle, running, success, failed)
- **Cookie-based preferences** for persistent theme, view mode, sort order, and filter settings
- **Responsive design** that works seamlessly on desktop and mobile devices
- **Modern UI** with Inter font, consistent spacing, and smooth HTMX-powered animations
- **No JavaScript required** - all interactivity powered by HTMX v2

### Usage
To enable the web dashboard:
```bash
# Basic web UI on default port 8080
cronn -f crontab --web.enabled

# Custom port and address
cronn -f crontab --web.enabled --web.address=:3000

# Bind to all interfaces
cronn -f crontab --web.enabled --web.address=0.0.0.0:8080

# Custom update interval (default: 30s)
cronn -f crontab --web.enabled --web.update-interval=10s

# Custom hostname display (defaults to os.Hostname())
cronn -f crontab --web.enabled --web.hostname=production-server

# Behind reverse proxy at subpath
cronn -f crontab --web.enabled --web.base-url=/cronn

# With basic authentication (optional)
export CRONN_WEB_PASSWORD_HASH='$2y$10$...' # bcrypt hash
cronn -f crontab --web.enabled

# With neighbor instances selector (for multi-server setups)
cronn -f crontab --web.enabled --web.neighbors-url=http://api.example.com/cronn/instances
```

### Basic Authentication (Optional)

To protect the web dashboard with a password:

1. Generate a bcrypt hash of your password:
   ```bash
   # Using htpasswd (commonly available)
   htpasswd -bnBC 10 "" yourpassword | tr -d ':\n'
   ```

2. Set the password hash:
   ```bash
   # Via environment variable
   export CRONN_WEB_PASSWORD_HASH='$2y$10$...'
   cronn -f crontab --web.enabled
   
   # Or via command line flag
   cronn -f crontab --web.enabled --web.password-hash='$2y$10$...'
   ```

3. Access the dashboard with username `cronn` and your password

The dashboard is accessible via web browser at the configured address. Job data updates automatically using HTMX for smooth, JavaScript-free interactions.

### Reverse Proxy Configuration

To run Cronn behind a reverse proxy at a subpath (e.g., `https://example.com/cronn`), use the `--web.base-url` flag:

```bash
# Run Cronn with base URL
cronn -f crontab --web.enabled --web.address=:8080 --web.base-url=/cronn
```

Example nginx configuration:
```nginx
# redirect /cronn to /cronn/ for consistency
location = /cronn {
    return 301 /cronn/;
}

location /cronn/ {
    proxy_pass http://localhost:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
```

**Note**: The base URL must start with `/` and should not end with a trailing slash (e.g., `/cronn` not `/cronn/`). The application will automatically normalize it.

### Neighbor Instances Selector

When running multiple cronn instances across different servers, you can enable a server selector dropdown in the web UI. This allows quick navigation between different cronn dashboards.

#### Configuration

Enable the neighbor selector by providing a URL that returns a JSON array of instances:

```bash
# From HTTP/HTTPS endpoint
cronn -f crontab --web.enabled --web.neighbors-url=http://api.example.com/cronn/instances

# From local JSON file
cronn -f crontab --web.enabled --web.neighbors-url=file:///etc/cronn/neighbors.json

# Via environment variable
export CRONN_WEB_NEIGHBORS_URL=http://api.example.com/cronn/instances
cronn -f crontab --web.enabled
```

#### Expected JSON Format

The URL (or file) must return a JSON array with `name` and `url` fields:

```json
[
  {"name": "prod-server-1", "url": "https://prod1.example.com:8080"},
  {"name": "prod-server-2", "url": "https://prod2.example.com:8080"},
  {"name": "staging", "url": "https://staging.example.com:8080"}
]
```

#### Features

- **Click to open**: When configured, the hostname badge becomes clickable and shows a dropdown
- **Lazy loading**: Neighbors are fetched only when the dropdown is opened
- **Caching**: Results are cached for 5 minutes to reduce API calls
- **Error handling**: Shows appropriate messages if fetch fails
- **File support**: Can read from local JSON file using `file://` URL scheme

### JSON API

Cronn provides a JSON API for programmatic access to job status, designed for CLI tools like `curl` and `jq`.

#### Endpoints

**Status** - Get all jobs with statistics:

```
GET /api/v1/status
```

**Job History** - Get execution history for a specific job (up to 50 most recent):

```
GET /api/v1/jobs/{id}/history
```

**Toggle Job** - Enable or disable a job:

```
POST /api/v1/jobs/{id}/toggle
```

**Execution Logs** - Get details and output for a specific execution:

```
GET /api/v1/jobs/{id}/executions/{exec_id}/logs
```

#### Response Examples

**Status Response:**

```json
{
  "jobs": [
    {
      "id": "abc123...",
      "command": "echo test",
      "schedule": "* * * * *",
      "next_run": "2024-01-15T02:00:00Z",
      "last_run": "2024-01-14T02:00:00Z",
      "last_status": "success",
      "is_running": false,
      "enabled": true
    }
  ],
  "stats": {
    "total": 10,
    "running": 1,
    "success": 7,
    "failed": 1,
    "idle": 1
  },
  "timestamp": "2024-01-14T15:30:00Z"
}
```

#### Authentication

When password authentication is enabled, use HTTP Basic Auth with username `cronn`:

```bash
curl -u cronn:yourpassword localhost:8080/api/v1/status | jq
```

#### Usage Examples

```bash
# get all jobs
curl -s localhost:8080/api/v1/status | jq '.jobs'

# get failed jobs only
curl -s localhost:8080/api/v1/status | jq '.jobs[] | select(.last_status == "failed")'

# get next job to run
curl -s localhost:8080/api/v1/status | jq '.jobs | sort_by(.next_run) | first'

# get stats summary
curl -s localhost:8080/api/v1/status | jq '.stats'

# count running jobs
curl -s localhost:8080/api/v1/status | jq '.stats.running'

# list job commands with status
curl -s localhost:8080/api/v1/status | jq '.jobs[] | {command, status: .last_status}'

# get job execution history (replace JOB_ID with actual job ID)
curl -s localhost:8080/api/v1/jobs/JOB_ID/history | jq '.executions'

# get execution logs (replace JOB_ID and EXEC_ID with actual IDs)
curl -s localhost:8080/api/v1/jobs/JOB_ID/executions/EXEC_ID/logs | jq '.output'
```

**History Response:**

```json
{
  "job": {
    "id": "abc123...",
    "command": "echo test",
    "schedule": "* * * * *",
    "next_run": "2024-01-15T02:00:00Z",
    "last_run": "2024-01-14T02:00:00Z",
    "last_status": "success",
    "is_running": false,
    "enabled": true
  },
  "executions": [
    {
      "id": 42,
      "started_at": "2024-01-14T02:00:00Z",
      "finished_at": "2024-01-14T02:00:01Z",
      "status": "success",
      "exit_code": 0,
      "executed_command": "echo test"
    }
  ]
}
```

**Logs Response:**

```json
{
  "id": 42,
  "job_id": "abc123...",
  "started_at": "2024-01-14T02:00:00Z",
  "finished_at": "2024-01-14T02:00:01Z",
  "status": "success",
  "exit_code": 0,
  "executed_command": "echo test",
  "output": "test\n"
}
```

<details markdown>
  <summary>Screenshots</summary>

### Desktop - Dark Theme

![Dashboard Dark Desktop](https://raw.githubusercontent.com/umputun/cronn/master/site/docs/screenshots/dashboard-dark-desktop.png)

### Desktop - Light Theme

![Dashboard Light Desktop](https://raw.githubusercontent.com/umputun/cronn/master/site/docs/screenshots/dashboard-light-desktop.png)

### List View

![Dashboard List View](https://raw.githubusercontent.com/umputun/cronn/master/site/docs/screenshots/dashboard-list-view.png)

### Sort by Next Run

![Dashboard Sort Next Run](https://raw.githubusercontent.com/umputun/cronn/master/site/docs/screenshots/dashboard-sort-nextrun.png)

### Sort by Last Run

![Dashboard Sort Last Run](https://raw.githubusercontent.com/umputun/cronn/master/site/docs/screenshots/dashboard-sort-lastrun.png)

### Mobile - Dark Theme

![Dashboard Dark Mobile](https://raw.githubusercontent.com/umputun/cronn/master/site/docs/screenshots/dashboard-dark-mobile.png)

### Mobile - Light Theme

![Dashboard Light Mobile](https://raw.githubusercontent.com/umputun/cronn/master/site/docs/screenshots/dashboard-light-mobile.png)

</details>

### Authentication

The web dashboard supports optional password authentication. When enabled, users will see a custom login form instead of the browser's basic auth dialog.

#### Enabling Authentication

1. Generate a bcrypt password hash using one of these methods:

Using `htpasswd` (Apache utilities):
   ```bash
   htpasswd -nB cronn
   # Enter password when prompted, copy the hash after "cronn:"
   ```

Using Python (if available):
   ```bash
   python3 -c "import bcrypt; print(bcrypt.hashpw(b'your-password', bcrypt.gensalt()).decode())"
   ```

2. Set the password hash via command line or environment variable:
   ```bash
   cronn --web.enabled --web.password-hash='$2y$10$...your-hash-here...'
   # or
   export CRONN_WEB_PASSWORD_HASH='$2y$10$...your-hash-here...'
   cronn --web.enabled
   ```

#### Authentication Features

- Custom styled login form matching the dashboard theme
- Cookie-based authentication with configurable session TTL (default: 24 hours)
  - Configure with `--web.login-ttl` flag (e.g., `--web.login-ttl=12h` for 12 hours)
  - Or via environment variable: `CRONN_WEB_LOGIN_TTL=48h`
- Logout link available in the dashboard footer when authentication is enabled
- Fallback to HTTP Basic Auth for API clients
- Username is fixed as "cronn"
- No authentication required for static resources
- **Brute-force protection**: Login attempts are rate-limited to 5 attempts per minute per IP address
- CSRF protection using Go 1.25's built-in cross-origin protection

## Optional modes

By default, all the optional modes are disabled. This includes:

- Logging mode
- Debug mode: produces more debug info
- Auto-resume mode: executes terminated task(s) on startup.
- Auto-update mode: checks for changes in crontab file (`-f` mode only) and reloads updated jobs.
- Reload crontab on SIGHUP signal
- Notification mode: sends email, Slack, Telegram and\or Webhook notifications on failed or passed jobs
- De-duplication mode: prevents the same jobs to run in parallel
- Repeater mode: repeats failed jobs
- Rotated logs: creates rotated logs
- Jitter mode: adds a random delay prior to execution of a job

### Auto-Resume

- auto-resume mode is disabled by default. To enable it, add `--resume=<directory>` to the command line or set `$CRONN_RESUME` environment variable.
- each task creates a flag-file named as `<ts>-<seq>.cronn` in `$CRONN_RESUME` directory and removes this flag on completion.
- flag file's content is the command line for the running job.
- at the start time `cronn` will discover all flag files and will execute them sequentially in case if multiple flag files discovered. 
Note: it won't block usual, scheduled tasks and it is possible to have initial (auto-resume) task running in parallel with regular tasks.
- old resume files (>=24h) ignored 
- usually it is not necessary to map `$CRONN_RESUME` location to host's FS as we don't want it to survive container recreation. 
However, it will survive container's restart.
- by default resume jobs executed sequentially, but can be configured to run in parallel with `--resume-concur=2..N` option.

### Auto-Update

- auto-update mode is disabled by default. To enable it, add `--update` to the command line or set `$CRONN_UPDATE` environment variable.
- if enabled, `cronn` will check for changes in crontab file (`-f` mode only) and reload updated jobs.
- the check is performed every 10 seconds by default and can be changed with `--update-interval=<duration>` option.
- when auto-update is enabled, `cronn` can start even if the crontab file doesn't exist, is empty, or has no jobs - it will begin with zero jobs and automatically load them when the file is created or populated.
- user can send SIGHUP signal to `cronn` to force update check.
- if user wishes to disable aut-update check but allow SIGHUP reloads the `--update-interval` can be set to `0s`. Pls note: in order to reload crontab file on SIGHUP signal update mode has to be enabled with `--update`.

### Repeater

- Optional repeater retries failed job multiple times. It uses backoff strategy with an exponential interval. 
- Duration interval goes in steps with `last * math.Pow(factor, attempt)` increments. 
- Optional jitter randomizes intervals a little bit. Factor = 1 effectively makes this strategy fixed with `duration` delay.
- Global repeater settings can be configured via CLI flags or environment variables
- Individual jobs in YAML format can override global settings with the `repeater` field:
  - `attempts`: Number of retry attempts
  - `duration`: Initial retry delay
  - `factor`: Backoff multiplication factor
  - `jitter`: Enable/disable jitter (true/false)

### Conditional Execution

Jobs can be configured to run only when certain system conditions are met. This is useful for resource-intensive tasks that should only run when the system is idle or has sufficient resources. Conditions are only supported in YAML configuration format.

To control how many condition checks can run simultaneously, use the `--max-concurrent-checks` flag (default: 10) or set the `CRONN_MAX_CONCURRENT_CHECKS` environment variable. This prevents resource exhaustion when multiple jobs with conditions are scheduled.

Available conditions:

- `cpu_below`: Maximum CPU usage percentage (0-100)
- `memory_below`: Maximum memory usage percentage (0-100)
- `load_avg_below`: Maximum system load average
- `disk_free_above`: Minimum free disk space percentage (0-100)
- `disk_free_path`: Path to check for disk space (defaults to "/")
- `custom`: Path to custom check script (exit 0 to allow, non-zero to block)
- `custom_timeout`: Timeout for custom script execution (defaults to 30s)

Postponement options:

- `max_postpone`: Maximum duration to wait for conditions (e.g., "2h", "30m")
- `check_interval`: How often to check conditions (defaults to 30s)

When conditions are not met:

- Without `max_postpone`: Job is skipped
- With `max_postpone`: Job waits up to the specified duration, checking periodically
- If deadline is reached: Job executes regardless of conditions

Example configurations:
```yaml
jobs:
  # Skip if CPU is busy
  - spec: "0 3 * * *"
    command: "backup.sh"
    conditions:
      cpu_below: 30  # Only run if CPU < 30%

# Wait for idle system
  - spec: "0 2 * * *"
    command: "maintenance.sh"
    conditions:
      cpu_below: 40
      memory_below: 50
      max_postpone: 1h      # Wait up to 1 hour
      check_interval: 2m    # Check every 2 minutes

# Custom check script
  - spec: "*/15 * * * *"
    command: "sync.sh"
    conditions:
      custom: "/usr/local/bin/check-network.sh"
      custom_timeout: "60s"  # Give custom script more time (default: 30s)
      disk_free_above: 10
      disk_free_path: "/backup"
```

All conditions must be met for a job to execute (AND logic). System metrics are collected using instant measurements, ensuring minimal performance impact.

### Deduplication

Optional de-duplication prevents the same jobs to run in parallel. Jobs are identified by their command line and scheduling. 
By default this option is off. To enable it, add `--dedup` to the command line or set `$CRONN_DEDUP` environment variable.

### Notifications

You can enable one or more notification methods: Slack, Webhook, Telegram, and Email. Either `--notify.enabled-error` or `--notify.enabled-complete` or both should be enabled for notifications to work.

#### Email

Enabled if `--notify.to` option is set, which could be list of emails. Please set all SMTP-related options for the email notifications to work.

#### Slack

Enabled if `--notify.slack-channels` option is set, which could be list of channels, channelIDs, and userIDs. Please set `--notify.slack-token` for this method to work.

#### Webhook

Enabled if `--notify.webhook-urls` option is set, which could be list of URLs.

#### Telegram

Enabled if `--notify.telegram-destinations` option is set, which could be list of channels, userIDs, and channelIDs (a number, like -1001480738202: use [that instruction](https://remark42.com/docs/configuration/telegram/#notifications-for-administrators) to obtain it). Please set `--notify.telegram-token` obtained from [BotFather](https://core.telegram.org/bots) for this method to work.

Text of notification is expected to be in HTML, tags which are not allowed in Telegram will be automatically removed.

#### Notification text

When enabled, notifications are sent to the specified destinations on job failure or completion. User can define custom templates for notifications messages with `--notify.complete-template` and `--notify.err-template` options. Default templates are in HTML. The following variables are available:

- `{{.Command}}` - the command with arguments
- `{{.Spec}}` - the crontab specification
- `{{.Host}}` - the hostname of the machine where the job is running
- `{{.TS}}` - the time-stamp of event
- `{{.Error}}` - the error message if any

### Logging

- In order to allow logging, add `--log.enabled` to the command line or set `$CRONN_LOG_ENABLED` environment variable.
- By default logs send to stdout and errors to stderr.
- To specify log file, add `--log.filename=<path>` to the command line or set `$CRONN_LOG_FILE` environment variable.
- Files are rotated every according to `--log.max-size=<size>`, `--log.max-files=<files>` and `--log.max-age=<days>` options.
- The maximum number of rotated backup files set with `--log.max-backups=<files>`.
- To turn compression on, add `--log.enabled-compress` to the command line or set `$CRONN_LOG_ENABLED_COMPRESS` environment variable.

## Things to know

1. CTRL-C won't kill `cronn` process right away but will wait till job(s) completion
2. each job runs as `sh -c cmd args...` to allow use of env and all other shell-related goodies

## All application Options

```
  -f, --file=                     crontab file (default: crontab) [$CRONN_FILE]
  -c, --command=                  crontab single command [$CRONN_COMMAND]
  -r, --resume=                   auto-resume location [$CRONN_RESUME]
      --resume-concur=            auto-resume concurrency level (default: 1) [$CRONN_RESUME_CONCUR]
  -u, --update                    auto-update mode [$CRONN_UPDATE]
      --update-interval=          auto-update interval (default: 10s) [$CRONN_UPDATE_INTERVAL]
  -j, --jitter                    enable jitter [$CRONN_JITTER]
      --jitter-duration=          jitter duration (default: 10s) [$CRONN_JITTER_DURATION]
      --dedup                     prevent duplicated jobs [$CRONN_DEDUP]
      --alt-template              use alternative templates, i.e. [[.YYYYMMDD]] [$CRONN_ALT_TEMPLATE]

web:
      --web.enabled               enable web dashboard [$CRONN_WEB_ENABLED]
      --web.address=              web server address (default: :8080) [$CRONN_WEB_ADDRESS]
      --web.base-url=             base URL path for reverse proxy (e.g., /cronn) [$CRONN_WEB_BASE_URL]
      --web.hostname=             hostname to display in UI (defaults to os.Hostname()) [$CRONN_WEB_HOSTNAME]
      --web.update-interval=      dashboard update interval (default: 30s) [$CRONN_WEB_UPDATE_INTERVAL]
      --web.db-path=              SQLite database path (default: cronn.db) [$CRONN_WEB_DB_PATH]
      --web.password-hash=        bcrypt hash for basic auth (username: cronn) [$CRONN_WEB_PASSWORD_HASH]
      --web.login-ttl=            login session TTL (default: 24h) [$CRONN_WEB_LOGIN_TTL]
      --web.disable-manual        disable manual job execution [$CRONN_WEB_DISABLE_MANUAL]
      --web.disable-command-edit  disable command editing in manual run dialog [$CRONN_WEB_DISABLE_COMMAND_EDIT]
      --web.neighbors-url=        URL to fetch neighbor instances JSON ([{name, url}]) [$CRONN_WEB_NEIGHBORS_URL]

repeater:
      --repeater.attempts=        how many time repeat failed job (default: 1) [$CRONN_REPEATER_ATTEMPTS]
      --repeater.duration=        initial duration (default: 1s) [$CRONN_REPEATER_DURATION]
      --repeater.factor=          backoff factor (default: 3) [$CRONN_REPEATER_FACTOR]
      --repeater.jitter           jitter [$CRONN_REPEATER_JITTER]

notify:
      --notify.enabled-error          enable email notifications on errors [$CRONN_NOTIFY_ENABLED_ERROR]
      --notify.enabled-complete       enable completion notifications [$CRONN_NOTIFY_ENABLED_COMPLETE]
      --notify.err-template=          error template file [$CRONN_NOTIFY_ERR_TEMPLATE]
      --notify.complete-template=     completion template file [$CRONN_NOTIFY_COMPLET_TEMPLATE]
      --notify.smtp-host=             SMTP host [$CRONN_NOTIFY_SMTP_HOST]
      --notify.smtp-port=             SMTP port [$CRONN_NOTIFY_SMTP_PORT]
      --notify.smtp-username=         SMTP user name [$CRONN_NOTIFY_SMTP_USERNAME]
      --notify.smtp-password=         SMTP password [$CRONN_NOTIFY_SMTP_PASSWORD]
      --notify.smtp-tls               enable SMTP TLS [$CRONN_NOTIFY_SMTP_TLS]
      --notify.smtp-starttls          enable SMTP StartTLS [$CRONN_NOTIFY_SMTP_STARTTLS]
      --notify.smtp-timeout=          SMTP TCP connection timeout (default: 10s) [$CRONN_NOTIFY_SMTP_TIMEOUT]
      --notify.from=                  SMTP from email [$CRONN_NOTIFY_FROM]
      --notify.to=                    SMTP to email(s) [$CRONN_NOTIFY_TO]
      --notify.max-log=               max number of log lines name (default: 100) [$CRONN_NOTIFY_MAX_LOG]
      --notify.host=                  host name running cronn [$CRONN_NOTIFY_HOSTNAME]
      --notify.slack-token=           API token for the Slack bot [$CRONN_NOTIFY_SLACK_TOKEN]
      --notify.slack-channels=        List of Slack channels the bot will post messages to [$CRONN_NOTIFY_SLACK_CHANNELS]
      --notify.telegram-token=        API token for the Telegram bot [$CRONN_NOTIFY_TELEGRAM_TOKEN]
      --notify.telegram-destinations= List of Telegram chat IDs the bot will post messages to [$CRONN_NOTIFY_TELEGRAM_DESTINATIONS]
      --notify.webhook-urls=          List of webhook URLs the bot will post messages to [$CRONN_NOTIFY_WEBHOOK_URLS]
      --notify.timeout=                timeout for notifications (default: 10s) [$TIMEOUT]
log:
      --log.enabled               enable logging [$CRONN_LOG_ENABLED]
      --log.debug                 debug mode [$CRONN_LOG_DEBUG]
      --log.prefix                enable log prefix with current command [$CRONN_LOG_PREFIX]
      --log.filename=             file to write logs to. Log to stdout if not specified [$CRONN_LOG_FILENAME]
      --log.max-size=             maximum size in megabytes of the log file before it gets rotated (default: 100) [$CRONN_LOG_MAX_SIZE]
      --log.max-age=              maximum number of days to retain old log files (default: 0) [$CRONN_LOG_MAX_AGE]
      --log.max-backups=          maximum number of old log files to retain (default: 7) [$CRONN_LOG_MAX_BACKUPS]
      --log.enabled-compress      determines if the rotated log files should be compressed using gzip [$CRONN_LOG_ENABLED_COMPRESS]

Help Options:
  -h, --help                      Show this help message

```

## Credits

- [robfig/cron](https://github.com/robfig/cron) for parsing and scheduling.
- [jessevdk/go-flags](https://github.com/jessevdk/go-flags) for cli parameters parser.
- [lumberjack](https://gopkg.in/natefinch/lumberjack.v2) for rotated logs
- [jmoiron/sqlx](https://github.com/jmoiron/sqlx) for database operations
- [modernc.org/sqlite](https://modernc.org/sqlite) for pure Go SQLite driver
- [go-pkgz/routegroup](https://github.com/go-pkgz/routegroup) for HTTP routing
- [go-pkgz/rest](https://github.com/go-pkgz/rest) for REST utilities

cronn

cronn Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

cronn

cronn Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README