Supercronic

The parser applies the following rules when interpreting the number of fields provided:

• 6 fields: A 0 second field is prepended. (e.g., * * * * * 2013 becomes 0 * * * * * 2013).
• 5 fields: A 0 second field is prepended and a wildcard year field is appended. (e.g., * * * * Mon becomes 0 * * * * Mon *).
• Day of week domain: Supports [0-7], where 7 is Sunday (matching 0 as Sunday) to comply with crontab standards.

Supercronic does not wipe the environment before running jobs. While you can specify variables inside the crontab using KEY=VALUE syntax for compatibility, it is not recommended.

Instead, set environment variables before starting Supercronic. Jobs will inherit these variables. For example, in Docker, jobs will inherit variables defined via ENV in the Dockerfile or via docker run -e.

You can install Supercronic by downloading a pre-built binary or building it from source.

Download

Navigate to the GitHub releases page and download the binary suitable for your system. If you are unsure, supercronic-linux-amd64 is a common choice for container environments.

Build from source

To build from source, ensure you have Go installed and run the following commands:

go get -d github.com/aptible/supercronic
cd "${GOPATH}/src/github.com/aptible/supercronic"
go mod vendor
go install

Supercronic can report errors to Sentry for real-time tracking. You can enable this by providing a Sentry Data Source Name (DSN) via the -sentry-dsn command-line flag or the SENTRY_DSN environment variable. If both are provided, the command-line flag takes priority.

$ ./supercronic -sentry-dsn DSN

You can install the cronexpr command-line utility using Go:

go get github.com/aptible/supercronic/cronexpr
go install github.com/aptible/supercronic/cronexpr

To provide more context in Sentry error reports, you can specify the environment and release tags using either command-line flags or environment variables.

• Environment: Use -sentry-environment or set SENTRY_ENVIRONMENT.
• Release: Use -sentry-release or set SENTRY_RELEASE.

Example using flags:

$ ./supercronic -sentry-dsn YOUR_SENTRY_DSN -sentry-environment YOUR_ENVIRONMENT -sentry-release YOUR_RELEASE

$ ./supercronic -sentry-dsn YOUR_SENTRY_DSN -sentry-environment YOUR_ENVIRONMENT
$ ./supercronic -sentry-dsn YOUR_SENTRY_DSN -sentry-release YOUR_RELEASE

To use the cronexpr parser in your Go project, install it using go get:

go get github.com/aptible/supercronic/cronexpr

The cronexpr library allows you to parse a cron expression and determine the next occurrence(s) relative to a given timestamp.

Key behaviors:

• MustParse(expression): Parses the expression or panics if it is malformed.
• Next(time.Time): Returns the single next time.Time that satisfies the expression. The returned time uses the same time zone as the input.
• NextN(time.Time, n): Returns a slice of the next n time.Time objects.
• IsZero(): Use this on the returned time.Time to check if no valid future time could be found (e.g., if the expression expires in the past or a specific year range is exceeded).

You can trigger a graceful shutdown and reload of the crontab configuration using one of two methods:

1. Send SIGUSR2

Send the SIGUSR2 signal to the Supercronic process.

In a Docker environment (where Supercronic is PID 1):

docker kill --signal=USR2 <container id>

In a standard shell:

kill -USR2 <pid>

2. Use -inotify flag

If you start Supercronic with the -inotify flag, it will automatically reload the crontab whenever the file is modified (detecting Write and Remove events).

Supercronic uses the system timezone from /etc/localtime by default. You can manage timezones in three ways:

1. System default: Uses /etc/localtime.
2. Environment variable: Set the TZ environment variable (e.g., TZ=Europe/Berlin) when running Supercronic. Ensure tzdata is installed in your container.
3. Crontab override: If you need the runner to operate in one timezone but schedule jobs in another, set the CRON_TZ variable inside your crontab.

Supercronic is compatible with Vixie cron but includes two key differences:

1. Second-resolution schedules: Supercronic supports schedules with second-level precision (e.g., using 7 fields instead of 5).
2. No user switching: The USER directive in a crontab is ignored. To run jobs as a specific user, set the USER in your Dockerfile or container runtime.

Example Crontab

# Run every minute
*/1 * * * * echo "hello"

# Run every 2 seconds
*/2 * * * * * * ls 2>/dev/null

# Run once every hour
@hourly echo "$SOME_HOURLY_JOB"

Below are common patterns for using cronexpr to predict future occurrences of a cron schedule.

Midnight on December 31st (any year)

cronexpr -t="2013-08-31" -n=5 "0 0 31 12 *"

2pm on February 29th (leap years)

cronexpr -t=2000 -n=10 "0 14 29 2 *"

12pm on the work day closest to the 15th of March, every 3 months

cronexpr -t=2013-09-01 -n=5 "0 12 15W 3/3 *"

Midnight on the fifth Saturday of any month

cronexpr -t=2013-09-02 -n 5 "0 0 * * 6#5"