runitor

Runitor can act as a long-running process that executes a command at specified intervals, serving as a lightweight alternative to cron or systemd.timer.

• Interval-based: Use the -every <duration> flag (e.g., -every 2h24m).
• Cron-based: Use the -at <cron> flag (e.g., -at "00 02,14 * * *").

Triggering an immediate run

If runitor is running in periodic mode, you can force it to execute the command immediately and reset its interval timer by sending a SIGALRM signal to the process:

pkill -ALRM runitor

runitor -slug db-backup -at "00 02,14 * * *" -- /script/db-backup

The basic usage pattern for runitor is to wrap a command. Runitor executes the command, captures its output, and reports the result to a Healthchecks.io instance (or your private instance).

Syntax: runitor [flags] -- command [args...]

Note that the -- separator is used to distinguish runitor's own flags from the command you wish to execute.

runitor -- ls -la

To sign a series of commits that have not yet been pushed to a public remote, you can use an interactive rebase with the --exec flag to amend each commit with a signature.

Warning: This rewrites git history. Only perform this on commits that have not been pushed.

Steps:

1. Identify the SHA1 of the last signed commit using git log --show-signature.
2. Add your SSH key to the agent.
3. Run git rebase using the --exec flag to automate the git commit --amend --no-edit -S command for every commit in the range.

ssh-add -K
git rebase --exec 'git commit --amend --no-edit -S' -i 0cafe42

Runitor identifies which check to report to using one of two methods:

1. UUID: Provide a unique check ID via -uuid or CHECK_UUID.
2. Slug + Ping Key: Provide a check slug via -slug or CHECK_SLUG AND a project ping key via -ping-key or PING_KEY.

If you use a slug, you must also provide a ping key. If you use the -create flag, you must use the Slug + Ping Key method.

Runitor can be configured using the following environment variables:

• HC_API_URL: The URL of the Healthchecks API (defaults to https://hc-ping.com).
• PING_KEY: The ping key used for authentication. You can use the file: prefix to point to a file containing the key (e.g., file:/path/to/key).
• CHECK_SLUG: The slug of the check to use.
• CHECK_UUID: The UUID of the check to use.

The RunConfig struct defines the operational parameters for a single run. Key behaviors include:

• Output Capture: Controlled by Quiet (no stdout) and Silent (no stdout or stderr).
• Ping Customization: NoStartPing prevents the initial 'start' signal. NoOutputInPing prevents command output from being sent in the success/failure pings. NoRunId prevents generating a unique UUID for each run.
• Error Handling: OnSuccess, OnNonzeroExit, and OnExecFail allow you to map different command outcomes to specific PingType values (e.g., PingTypeSuccess, PingTypeFail, PingTypeLog).
• Payload Limits: PingBodyLimit determines the maximum size of the command output sent to the API. If the output exceeds this, it is truncated, and a notice is added to the body.

To avoid passing sensitive information like PING_KEY or CHECK_UUID directly in the command line or environment variables, you can use the file: prefix. When a value starts with file:, runitor reads the content of the file at the specified path and uses it as the value, trimming any whitespace.

# Instead of passing the key directly:
runitor -ping-key "my-secret-key" "ls"

# Pass a path to a file containing the key:
runitor -ping-key "file:/run/secrets/ping_key" "ls"

This example demonstrates running a maintenance script every 2 hours and 24 minutes using a check slug and a ping key loaded from a file.

export PING_KEY=file:/run/secrets/hc_prod_pingkey
runitor -slug git-repo-maintenance \
    -every 2h24m -- \
    /script/git-maint

# (Using per-project ping key, and check slugs.)
export PING_KEY=file:/run/secrets/hc_prod_pingkey
runitor -slug git-repo-maintenance \
    -every 2h24m -- \
    /script/git-maint

This example shows how to use a specific check UUID to run a dehydrated certificate renewal command.

export CHECK_UUID=8116e449-d71c-4112-8f5d-a66f60902091
runitor -- dehydrated --cron --config example.com.conf

# (Using per check UUIDs.)
export CHECK_UUID=8116e449-d71c-4112-8f5d-a66f60902091
runitor -- dehydrated --cron --config example.com.conf