You can easily add Framasoft cron’s health checks monitoring to a shell script. All you have to do is make an HTTP request at an appropriate place in the script. curl and wget are two common command-line HTTP clients you can use.
# Sends an HTTP GET request with curl:
curl -m 10 --retry 5 https://hc.framasoft.org/ping/your-uuid-here
# Silent version (no stdout/stderr output unless curl hits an error):
curl -fsS -m 10 --retry 5 -o /dev/null https://hc.framasoft.org/ping/your-uuid-here
Here's what each curl parameter does:
--retry
parameter, then the time counter is reset
at the start of each retry.You can append /fail
or /{exit-status}
to any ping URL and use the resulting URL
to actively signal a failure. The exit status should be a 0-255 integer.
Framasoft cron’s health checks will interpret exit status 0 as success and all non-zero values as failures.
The following example runs /usr/bin/certbot renew
, and uses the $?
variable to
look up its exit status:
#!/bin/sh
# Payload here:
/usr/bin/certbot renew
# Ping Framasoft cron’s health checks
curl -m 10 --retry 5 https://hc.framasoft.org/ping/your-uuid-here/$?
Note on pipelines (command1 | command2 | command3
) in Bash scripts: by default, a
pipeline's exit status is the exit status of the rightmost command in the pipeline.
Use set -o pipefail
if you need the pipeline to return non-zero exit status if any
part of the pipeline fails:
#!/bin/sh
set -o pipefail
pg_dump somedb | gpg --encrypt --recipient alice@example.org --output somedb.sql.gpg
# Without pipefail, if pg_dump command fails, but gpg succeeds, $? will be 0,
# and the script will report success.
# With pipefail, if pg_dump fails, the script will report the exit code returned by pg_dump.
curl -m 10 --retry 5 https://hc.framasoft.org/ping/your-uuid-here/$?
When pinging with HTTP POST, you can put extra diagnostic information in the request body. If the request body looks like a valid UTF-8 string, Framasoft cron’s health checks will accept and store the first 10 kB of the request body.
In the below example, certbot's output is captured and submitted via HTTP POST:
#!/bin/sh
m=$(/usr/bin/certbot renew 2>&1)
curl -fsS -m 10 --retry 5 --data-raw "$m" https://hc.framasoft.org/ping/your-uuid-here
This example uses Framasoft cron’s health checks auto provisioning feature to create a check "on the fly" if it does not already exist. Using this technique, you can write services that automatically register with Framasoft cron’s health checks the first time they run.
#!/bin/bash
PING_KEY=fixme-your-ping-key-here
# Use system's hostname as check's slug
SLUG=$(hostname)
# Construct a ping URL and append "?create=1" at the end:
URL=https://hc.framasoft.org/ping/$PING_KEY/$SLUG?create=1
# Send a ping:
curl -m 10 --retry 5 $URL