healthchecks_healthchecks/templates/docs/bash.html-fragment

<h1>Shell Scripts</h1>
<p>You can easily add SITE_NAME monitoring to a shell script. All you
have to do is make an HTTP request at an appropriate place in the script.
<a href="https://curl.haxx.se/docs/manpage.html">curl</a> and
<a href="https://www.gnu.org/software/wget/manual/wget.html">wget</a>
are two common command-line HTTP clients you can use.</p>
<div class="highlight"><pre><span></span><code><span class="c1"># Sends an HTTP GET request with curl:</span>
curl<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>PING_URL

<span class="c1"># Silent version (no stdout/stderr output unless curl hits an error):</span>
curl<span class="w"> </span>-fsS<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>-o<span class="w"> </span>/dev/null<span class="w"> </span>PING_URL
</code></pre></div>

<p>Here's what each curl parameter does:</p>
<dl>
<dt><strong>-m &lt;seconds&gt;</strong></dt>
<dd>Maximum time in seconds that you allow the HTTP request to take.
If you use the <code>--retry</code> parameter, then the time counter is reset
at the start of each retry.</dd>
<dt><strong>--retry &lt;num&gt;</strong></dt>
<dd>On transient errors, retry up to this many times. By default, curl
uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...).
See also <a href="https://curl.haxx.se/docs/manpage.html#--retry-delay">--retry-delay</a>.
Transient errors are: timeouts, HTTP status codes 408, 429, 500, 502, 503, 504.</dd>
<dt><strong>-f, --fail</strong></dt>
<dd>Makes curl treat non-200 responses as errors, and
<a href="https://curl.se/docs/manpage.html#-f">return error 22</a>.</dd>
<dt><strong>-s, --silent</strong></dt>
<dd>Silent or quiet mode. Hides the progress meter, but also
hides error messages.</dd>
<dt><strong>-S, --show-error</strong></dt>
<dd>Re-enables error messages when -s is used.</dd>
<dt><strong>-o /dev/null</strong></dt>
<dd>Redirects curl's stdout to /dev/null (error messages still go to stderr).</dd>
</dl>
<h2>Signaling Failure from Shell Scripts</h2>
<p>You can append <code>/fail</code> or <code>/{exit-status}</code> to any ping URL and use the resulting URL
to actively signal a failure. The exit status should be a 0-255 integer.
SITE_NAME will interpret exit status 0 as success and all non-zero values as failures.</p>
<p>The following example runs <code>/usr/bin/certbot renew</code>, and uses the <code>$?</code> variable to
look up its exit status:</p>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/sh</span>

<span class="c1"># Payload here:</span>
/usr/bin/certbot<span class="w"> </span>renew
<span class="c1"># Ping SITE_NAME</span>
curl<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>PING_URL/<span class="nv">$?</span>
</code></pre></div>

<p>Note on pipelines (<code>command1 | command2 | command3</code>) in Bash scripts: by default, a
pipeline's exit status is the exit status of the rightmost command in the pipeline.
Use <code>set -o pipefail</code> if you need the pipeline to return non-zero exit status if <em>any</em>
part of the pipeline fails:</p>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/sh</span>

<span class="nb">set</span><span class="w"> </span>-o<span class="w"> </span>pipefail
pg_dump<span class="w"> </span>somedb<span class="w"> </span><span class="p">|</span><span class="w"> </span>gpg<span class="w"> </span>--encrypt<span class="w"> </span>--recipient<span class="w"> </span>alice@example.org<span class="w"> </span>--output<span class="w"> </span>somedb.sql.gpg
<span class="c1"># Without pipefail, if pg_dump command fails, but gpg succeeds, $? will be 0,</span>
<span class="c1"># and the script will report success.</span>
<span class="c1"># With pipefail, if pg_dump fails, the script will report the exit code returned by pg_dump.</span>
curl<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>PING_URL/<span class="nv">$?</span>
</code></pre></div>

<h2>Logging Command Output</h2>
<p>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, SITE_NAME
will accept and store the first PING_BODY_LIMIT_FORMATTED of the request body.</p>
<p>In the below example, certbot's output is captured and submitted via HTTP POST:</p>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/sh</span>

<span class="nv">m</span><span class="o">=</span><span class="k">$(</span>/usr/bin/certbot<span class="w"> </span>renew<span class="w"> </span><span class="m">2</span>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="k">)</span>
curl<span class="w"> </span>-fsS<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span>--data-raw<span class="w"> </span><span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span><span class="w"> </span>PING_URL
</code></pre></div>

<h2>Auto Provisioning New Checks</h2>
<p>This example uses SITE_NAME <a href="../autoprovisioning/">auto provisioning feature</a> to
create a check "on the fly" if it does not already exist. Using this technique, you can
write services that automatically register with SITE_NAME the first time they run.</p>
<div class="highlight"><pre><span></span><code><span class="ch">#!/bin/bash</span>

<span class="nv">PING_KEY</span><span class="o">=</span>fixme-your-ping-key-here

<span class="c1"># Use system&#39;s hostname as check&#39;s slug</span>
<span class="nv">SLUG</span><span class="o">=</span><span class="k">$(</span>hostname<span class="k">)</span>

<span class="c1"># Construct a ping URL and append &quot;?create=1&quot; at the end:</span>
<span class="nv">URL</span><span class="o">=</span>PING_ENDPOINT<span class="nv">$PING_KEY</span>/<span class="nv">$SLUG</span>?create<span class="o">=</span><span class="m">1</span>

<span class="c1"># Send a ping:</span>
curl<span class="w"> </span>-m<span class="w"> </span><span class="m">10</span><span class="w"> </span>--retry<span class="w"> </span><span class="m">5</span><span class="w"> </span><span class="nv">$URL</span>
</code></pre></div>