forked from GithubBackups/healthchecks
Update bash examples with the "-m" parameter.
This commit is contained in:
Pēteris Caune
parent
911293e1d2
commit
d34854f838
@ -104,17 +104,17 @@ h2.rule {
|
||||
}
|
||||
|
||||
|
||||
.docs-api dl {
|
||||
.page-docs dl {
|
||||
display: grid;
|
||||
grid-template-columns: 150px auto;
|
||||
}
|
||||
|
||||
.docs-api dt {
|
||||
.page-docs dt {
|
||||
font-weight: normal;
|
||||
font-family: "Lucida Console", Monaco, monospace;
|
||||
}
|
||||
|
||||
.docs-api dt, .docs-api dd {
|
||||
.page-docs dt, .page-docs dd {
|
||||
border-top: 1px solid #DDD;
|
||||
padding: 8px 0;
|
||||
}
|
||||
|
||||
@ -1,34 +1,49 @@
|
||||
<h1>Shell Scripts</h1>
|
||||
<p>You can easily add SITE_NAME monitoring to a shell script. All you
|
||||
have to do is make a HTTP request at the end of the script.
|
||||
have to do is make a 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"># Sending a HTTP GET request with curl:</span>
|
||||
curl --retry <span class="m">3</span> PING_URL
|
||||
<div class="highlight"><pre><span></span><code><span class="c1"># Sends a 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 --retry <span class="m">3</span> PING_URL
|
||||
|
||||
<span class="c1"># Sending a HTTP GET request with wget:</span>
|
||||
wget PING_URL -O /dev/null
|
||||
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 a 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>Signalling Failure from Shell Scripts</h2>
|
||||
<p>You can append <code>/fail</code> to any ping URL and use the resulting URL to actively
|
||||
signal a failure. The below example:</p>
|
||||
signal a failure. The following example:</p>
|
||||
<ul>
|
||||
<li>runs <code>/usr/bin/certbot renew</code></li>
|
||||
<li>if the certbot command is successful (exit code 0), send HTTP GET to <code>PING_URL</code></li>
|
||||
<li>otherwise, send HTTP GET to <code>PING_URL/fail</code></li>
|
||||
<li>if the certbot command is successful (exit code 0), sends HTTP GET to <code>PING_URL</code></li>
|
||||
<li>otherwise, sends HTTP GET to <code>PING_URL/fail</code></li>
|
||||
</ul>
|
||||
<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 --retry <span class="m">3</span> <span class="s2">"PING_URL</span><span class="k">$(</span><span class="o">[</span> <span class="nv">$?</span> -ne <span class="m">0</span> <span class="o">]</span> <span class="o">&&</span> <span class="nb">echo</span> -n /fail<span class="k">)</span><span class="s2">"</span>
|
||||
curl -m <span class="m">10</span> --retry <span class="m">5</span> <span class="s2">"PING_URL</span><span class="k">$(</span><span class="o">[</span> <span class="nv">$?</span> -ne <span class="m">0</span> <span class="o">]</span> <span class="o">&&</span> <span class="nb">echo</span> -n /fail<span class="k">)</span><span class="s2">"</span>
|
||||
</code></pre></div>
|
||||
|
||||
|
||||
@ -40,7 +55,7 @@ will accept and store first 10KB of the request body.</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 --retry <span class="m">3</span> --data-raw <span class="s2">"</span><span class="nv">$m</span><span class="s2">"</span> PING_URL
|
||||
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>
|
||||
|
||||
|
||||
@ -61,5 +76,5 @@ register with SITE_NAME the first time they run.</p>
|
||||
<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 --retry <span class="m">3</span> <span class="nv">$URL</span>
|
||||
curl -m <span class="m">10</span> --retry <span class="m">5</span> <span class="nv">$URL</span>
|
||||
</code></pre></div>
|
||||
@ -1,30 +1,51 @@
|
||||
# Shell Scripts
|
||||
|
||||
You can easily add SITE_NAME monitoring to a shell script. All you
|
||||
have to do is make a HTTP request at the end of the script.
|
||||
have to do is make a HTTP request at an appropriate place in the script.
|
||||
[curl](https://curl.haxx.se/docs/manpage.html) and
|
||||
[wget](https://www.gnu.org/software/wget/manual/wget.html)
|
||||
are two common command line HTTP clients you can use.
|
||||
|
||||
```bash
|
||||
# Sending a HTTP GET request with curl:
|
||||
curl --retry 3 PING_URL
|
||||
# Sends a HTTP GET request with curl:
|
||||
curl -m 10 --retry 5 PING_URL
|
||||
|
||||
# Silent version (no stdout/stderr output unless curl hits an error):
|
||||
curl -fsS --retry 3 PING_URL
|
||||
curl -fsS -m 10 --retry 5 -o /dev/null PING_URL
|
||||
|
||||
# Sending a HTTP GET request with wget:
|
||||
wget PING_URL -O /dev/null
|
||||
```
|
||||
|
||||
Here's what each curl parameter does:
|
||||
|
||||
**-m <seconds>**
|
||||
: Maximum time in seconds that you allow the whole operation to take.
|
||||
|
||||
**--retry <num>**
|
||||
: If a 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 [--retry-delay](https://curl.haxx.se/docs/manpage.html#--retry-delay).
|
||||
|
||||
**-f, --fail**
|
||||
: Makes curl treat non-200 responses as errors.
|
||||
|
||||
**-s, --silent**
|
||||
: Silent or quiet mode. Hides the progress meter, but also
|
||||
hides error messages.
|
||||
|
||||
**-S, --show-error**
|
||||
: Re-enables error messages when -s is used.
|
||||
|
||||
**-o /dev/null**
|
||||
: Redirect curl's stdout to /dev/null (error messages still go to stderr).
|
||||
|
||||
## Signalling Failure from Shell Scripts
|
||||
|
||||
You can append `/fail` to any ping URL and use the resulting URL to actively
|
||||
signal a failure. The below example:
|
||||
signal a failure. The following example:
|
||||
|
||||
* runs `/usr/bin/certbot renew`
|
||||
* if the certbot command is successful (exit code 0), send HTTP GET to `PING_URL`
|
||||
* otherwise, send HTTP GET to `PING_URL/fail`
|
||||
* if the certbot command is successful (exit code 0), sends HTTP GET to `PING_URL`
|
||||
* otherwise, sends HTTP GET to `PING_URL/fail`
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
@ -32,7 +53,7 @@ signal a failure. The below example:
|
||||
# Payload here:
|
||||
/usr/bin/certbot renew
|
||||
# Ping SITE_NAME
|
||||
curl --retry 3 "PING_URL$([ $? -ne 0 ] && echo -n /fail)"
|
||||
curl -m 10 --retry 5 "PING_URL$([ $? -ne 0 ] && echo -n /fail)"
|
||||
```
|
||||
|
||||
## Logging Command Output
|
||||
@ -47,7 +68,7 @@ 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 --retry 3 --data-raw "$m" PING_URL
|
||||
curl -fsS -m 10 --retry 5 --data-raw "$m" PING_URL
|
||||
```
|
||||
|
||||
## Auto-provisioning New Checks
|
||||
@ -71,5 +92,5 @@ PAYLOAD='{"name": "'`hostname`'", "timeout": 60, "grace": 60, "unique": ["name"]
|
||||
URL=`curl -s SITE_ROOT/api/v1/checks/ -H "X-Api-Key: $API_KEY" -d "$PAYLOAD" | jq -r .ping_url`
|
||||
|
||||
# Finally, send a ping:
|
||||
curl --retry 3 $URL
|
||||
curl -m 10 --retry 5 $URL
|
||||
```
|
||||
|
||||
@ -30,19 +30,19 @@ increasingly important as you add more checks to your account.</p>
|
||||
<p>Edit the check's <strong>schedule</strong>:</p>
|
||||
<ul>
|
||||
<li>change its type from "Simple" to "Cron"</li>
|
||||
<li>enter <code>8 6 * * *</code> in the cron epression field</li>
|
||||
<li>enter <code>8 6 * * *</code> in the cron expression field</li>
|
||||
<li>set the timezone to match your machine's timezone</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
<p>Take note of your check's unique <strong>ping URL</strong></p>
|
||||
<p>Take note of your check's unique <strong>ping URL</strong>.</p>
|
||||
</li>
|
||||
</ol>
|
||||
<p>Finally, edit your cron job definition and append a curl or wget call
|
||||
after the command:</p>
|
||||
<div class="highlight"><pre><span></span><code>$ crontab -e
|
||||
<span class="c1"># m h dom mon dow command</span>
|
||||
<span class="m">8</span> <span class="m">6</span> * * * /home/user/backup.sh <span class="o">&&</span> curl -fsS --retry <span class="m">3</span> -o /dev/null PING_URL
|
||||
<span class="m">8</span> <span class="m">6</span> * * * /home/user/backup.sh <span class="o">&&</span> curl -fsS --retry <span class="m">5</span> -o /dev/null PING_URL
|
||||
</code></pre></div>
|
||||
|
||||
|
||||
@ -58,46 +58,26 @@ potentially go unnoticed otherwise:</p>
|
||||
<li>cron does start your task, but the task exits with non-zero exit code</li>
|
||||
</ul>
|
||||
<h2>Curl Options</h2>
|
||||
<p>The extra options tells curl to not print anything to standard output unless
|
||||
there is an error. Feel free to adjust the curl options to suit your needs.</p>
|
||||
<table class="table curl-opts">
|
||||
<tr>
|
||||
<th>&&</th>
|
||||
<td>Run curl only if <code>/home/user/backup.sh</code> exits with an exit code 0</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>
|
||||
-f, --fail
|
||||
</th>
|
||||
<td>Makes curl treat non-200 responses as errors</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>-s, --silent</th>
|
||||
<td>Silent or quiet mode. Use it to hide progress meter,
|
||||
but it also hides error messages.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>-S, --show-error</th>
|
||||
<td>Re-enables error messages when -s is used.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>--retry <num></th>
|
||||
<td>
|
||||
If a transient error is returned when curl tries to perform a
|
||||
transfer, it will retry this number of times before giving up.
|
||||
Setting the number to 0 makes curl do no retries
|
||||
(which is the default). Transient error is a timeout or an HTTP 5xx
|
||||
response code.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>-o /dev/null</th>
|
||||
<td>
|
||||
Redirect curl's stdout to /dev/null (error messages still go to stderr)
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>The extra options in the above example tells curl to retry failed HTTP requests, and
|
||||
to silence output unless there is an error. Feel free to adjust the curl options to
|
||||
suit your needs.</p>
|
||||
<dl>
|
||||
<dt><strong>&&</strong></dt>
|
||||
<dd>Run curl only if <code>/home/user/backup.sh</code> exits with an exit code 0.</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>--retry <num></strong></dt>
|
||||
<dd>If a transient error is returned when curl tries to perform a
|
||||
transfer, it will retry this number of times before giving up.
|
||||
Setting the number to 0 makes curl do no retries (which is the default).
|
||||
Transient error is a timeout or an HTTP 5xx response code.</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>Looking up Your Machine's Time Zone</h2>
|
||||
<p>On modern GNU/Linux systems, you can look up the time zone using the
|
||||
<code>timedatectl status</code> command and looking for "Time zone" in its output:</p>
|
||||
|
||||
@ -30,10 +30,10 @@ increasingly important as you add more checks to your account.
|
||||
1. Edit the check's **schedule**:
|
||||
|
||||
* change its type from "Simple" to "Cron"
|
||||
* enter `8 6 * * *` in the cron epression field
|
||||
* enter `8 6 * * *` in the cron expression field
|
||||
* set the timezone to match your machine's timezone
|
||||
|
||||
1. Take note of your check's unique **ping URL**
|
||||
1. Take note of your check's unique **ping URL**.
|
||||
|
||||
Finally, edit your cron job definition and append a curl or wget call
|
||||
after the command:
|
||||
@ -41,7 +41,7 @@ after the command:
|
||||
```bash
|
||||
$ crontab -e
|
||||
# m h dom mon dow command
|
||||
8 6 * * * /home/user/backup.sh && curl -fsS --retry 3 -o /dev/null PING_URL
|
||||
8 6 * * * /home/user/backup.sh && curl -fsS --retry 5 -o /dev/null PING_URL
|
||||
```
|
||||
|
||||
Now, each time your cron job runs, it will send a HTTP request to the ping URL.
|
||||
@ -58,46 +58,30 @@ potentially go unnoticed otherwise:
|
||||
|
||||
## Curl Options
|
||||
|
||||
The extra options tells curl to not print anything to standard output unless
|
||||
there is an error. Feel free to adjust the curl options to suit your needs.
|
||||
The extra options in the above example tells curl to retry failed HTTP requests, and
|
||||
to silence output unless there is an error. Feel free to adjust the curl options to
|
||||
suit your needs.
|
||||
|
||||
<table class="table curl-opts">
|
||||
<tr>
|
||||
<th>&&</th>
|
||||
<td>Run curl only if <code>/home/user/backup.sh</code> exits with an exit code 0</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>
|
||||
-f, --fail
|
||||
</th>
|
||||
<td>Makes curl treat non-200 responses as errors</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>-s, --silent</th>
|
||||
<td>Silent or quiet mode. Use it to hide progress meter,
|
||||
but it also hides error messages.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>-S, --show-error</th>
|
||||
<td>Re-enables error messages when -s is used.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>--retry <num></th>
|
||||
<td>
|
||||
If a transient error is returned when curl tries to perform a
|
||||
transfer, it will retry this number of times before giving up.
|
||||
Setting the number to 0 makes curl do no retries
|
||||
(which is the default). Transient error is a timeout or an HTTP 5xx
|
||||
response code.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>-o /dev/null</th>
|
||||
<td>
|
||||
Redirect curl's stdout to /dev/null (error messages still go to stderr)
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
**&&**
|
||||
: Run curl only if `/home/user/backup.sh` exits with an exit code 0.
|
||||
|
||||
**-f, --fail**
|
||||
: Makes curl treat non-200 responses as errors.
|
||||
|
||||
**-s, --silent**
|
||||
: Silent or quiet mode. Hides the progress meter, but also hides error messages.
|
||||
|
||||
**-S, --show-error**
|
||||
: Re-enables error messages when -s is used.
|
||||
|
||||
**--retry <num>**
|
||||
: If a transient error is returned when curl tries to perform a
|
||||
transfer, it will retry this number of times before giving up.
|
||||
Setting the number to 0 makes curl do no retries (which is the default).
|
||||
Transient error is a timeout or an HTTP 5xx response code.
|
||||
|
||||
**-o /dev/null**
|
||||
: Redirect curl's stdout to /dev/null (error messages still go to stderr).
|
||||
|
||||
## Looking up Your Machine's Time Zone
|
||||
|
||||
|
||||
@ -16,4 +16,4 @@
|
||||
</code></pre></div>
|
||||
|
||||
|
||||
<p>Note: this code never throws any exception.</p>
|
||||
<p>Note: this code does not throw any exceptions.</p>
|
||||
@ -19,4 +19,4 @@ $curl->setTimeout(5);
|
||||
$curl->get('PING_URL');
|
||||
```
|
||||
|
||||
Note: this code never throws any exception.
|
||||
Note: this code does not throw any exceptions.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user