README.md

# vdcron

`vdcron` is a scheduling utility designed to replace `cron` for systems that do not run continuously, such as laptops. Unlike traditional `cron`, `vdcron` does not assume a machine is always on and instead runs scheduled tasks when triggered by an external event, such as waking up from sleep. 

## Features

- **Flexible Scheduling**: Schedule tasks based on specific dates, intervals, weekdays, or months, similar to `cron`.
- **Trigger-Based Execution**: `vdcron` isn´t a background daemon. Instead, it´s designed to be triggered by external events, such as system resume or user login.
- **Resilient Task Execution**: Ensures tasks run when the schedule is met, even if delayed by system downtime. Failed tasks remain in the schedule for retry.
- **Dynamic Rescheduling**: Tasks can be configured to re-run at intervals, making it ideal for periodic jobs.

## How to install it

You can use got or git to install it:

    got clone ssh://anon@repo.vincentdelft.be/vdcron
    got checkout vdcron.git vdcron

    (git clone ssh://anon@repo.vincentdelft.be/vdcron)

You can install it on your machine by running `make install` with your root account. 

    # make install


## How It Works

Since `vdcron` does not run continuously, it must be triggered by other means. For example:
- **Resume from Sleep**: On OpenBSD, trigger `vdcron` via the `apmd` resume script:

    obsd:~ # cat /etc/apm/resume
    #!/bin/sh
    /usr/local/bin/vdcron "/etc/apm/resume"

Ensure `apmd` is enabled:

    rcctl enable apmd
    rcctl start apmd

- **Other Triggers**: `vdcron` can also be run at startup, on user login, or even periodically with `cron` using `@reboot`.

## Command-Line Options

- `-h`: Display help information
- `-d`: Debug mode for detailed logs
- `-s value`: Set an initial sleep time (default: 10 seconds)
- `-f file`: Specify an alternative config file (default: `/etc/vdcron.conf` for root or `~/.vdcron/vdcron.conf` for other users)

## Configuration File (`vdcron.conf`)

`vdcron` uses a configuration file, `/etc/vdcron.conf` for root or `~/.vdcron/vdcron.conf` for regular users. Each line represents a task with a schedule and command. The format options include:

- **Date-Based**: Run at a specific date or time, with optional repetition. Example:

    +20240101 echo "Happy New Year!"

- **Weekday and Month-Based**: Run on specific weekdays or months, with optional intervals. Example:

    Monday/7 echo "Weekly Reminder"
    April/1 sh /etc/monthly_task

- **Always**: Run every time `vdcron` is triggered:

    Always echo "System is active"

- **Rescheduling Failed Tasks**: Tasks with a `+` prefix retry on failure, ensuring network or dependency issues do not prevent completion.

## Example Configuration

    +20240101 echo "Happy New Year!"
    Sunday sh /etc/weekly_maintenance
    Always /usr/local/bin/monitor_script
    +20240101/1 sh /etc/daily_task

## Logging

Output and errors are logged to `/var/log/vdcron.log` for root or `~/.vdcron/vdcron.log` for other users. Logging can be suppressed with the `-q` option in the configuration file.

## Author

Developed by Vincent Delft. Contact: vincent.delft@gmail.com

## Compatibility

Tested on OpenBSD 6.3+ and on debian.