You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
75 lines
4.7 KiB
75 lines
4.7 KiB
<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 -m <span class="m">10</span> --retry <span class="m">5</span> PING_URL
|
|
|
|
<span class="c1"># Silent version (no stdout/stderr output unless curl hits an error):</span>
|
|
curl -fsS -m <span class="m">10</span> --retry <span class="m">5</span> -o /dev/null PING_URL
|
|
</code></pre></div>
|
|
|
|
<p>Here's what each curl parameter does:</p>
|
|
<dl>
|
|
<dt><strong>-m <seconds></strong></dt>
|
|
<dd>Maximum time in seconds that you allow the whole operation to take.</dd>
|
|
<dt><strong>--retry <num></strong></dt>
|
|
<dd>If an HTTP request fails, 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>.</dd>
|
|
<dt><strong>-f, --fail</strong></dt>
|
|
<dd>Makes curl treat non-200 responses as errors.</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>Redirect 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 renew
|
|
<span class="c1"># Ping SITE_NAME</span>
|
|
curl -m <span class="m">10</span> --retry <span class="m">5</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 10KB 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 renew <span class="m">2</span>><span class="p">&</span><span class="m">1</span><span class="k">)</span>
|
|
curl -fsS -m <span class="m">10</span> --retry <span class="m">5</span> --data-raw <span class="s2">"</span><span class="nv">$m</span><span class="s2">"</span> PING_URL
|
|
</code></pre></div>
|
|
|
|
<h2>Auto-provisioning New Checks</h2>
|
|
<p>This example uses SITE_NAME <a href="../api/">Management API</a> to create a check "on the fly"
|
|
(if it does not already exist) and retrieve its ping URL.
|
|
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">API_KEY</span><span class="o">=</span>your-api-key-here
|
|
|
|
<span class="c1"># Check's parameters. This example uses system's hostname for check's name.</span>
|
|
<span class="nv">PAYLOAD</span><span class="o">=</span><span class="s1">'{"name": "'</span><span class="sb">`</span>hostname<span class="sb">`</span><span class="s1">'", "timeout": 60, "grace": 60, "unique": ["name"]}'</span>
|
|
|
|
<span class="c1"># Create the check if it does not exist.</span>
|
|
<span class="c1"># Grab the ping_url from JSON response using the jq utility:</span>
|
|
<span class="nv">URL</span><span class="o">=</span><span class="sb">`</span>curl -s SITE_ROOT/api/v1/checks/ -H <span class="s2">"X-Api-Key: </span><span class="nv">$API_KEY</span><span class="s2">"</span> -d <span class="s2">"</span><span class="nv">$PAYLOAD</span><span class="s2">"</span> <span class="p">|</span> jq -r .ping_url<span class="sb">`</span>
|
|
|
|
<span class="c1"># Finally, send a ping:</span>
|
|
curl -m <span class="m">10</span> --retry <span class="m">5</span> <span class="nv">$URL</span>
|
|
</code></pre></div>
|