Update bash examples with the "-m" parameter.

static/css/docs.css

@@ -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;
 }

templates/docs/bash.html

@@ -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>
+<div class="highlight"><pre><span></span><code><span class="c1"># Sends a HTTP GET request with curl:</span>
-curl --retry <span class="m">3</span> PING_URL
+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
+curl -fsS -m <span class="m">10</span> --retry <span class="m">5</span> -o /dev/null PING_URL
-
-<span class="c1"># Sending a HTTP GET request with wget:</span>
-wget PING_URL -O /dev/null
 </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 whole operation to take.</dd>
+<dt><strong>--retry &lt;num&gt;</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>if the certbot command is successful (exit code 0), sends HTTP GET to <code>PING_URL</code></li>
-<li>otherwise, send HTTP GET to <code>PING_URL/fail</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">&quot;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">&amp;&amp;</span> <span class="nb">echo</span> -n /fail<span class="k">)</span><span class="s2">&quot;</span>
+curl -m <span class="m">10</span> --retry <span class="m">5</span> <span class="s2">&quot;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">&amp;&amp;</span> <span class="nb">echo</span> -n /fail<span class="k">)</span><span class="s2">&quot;</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>&gt;<span class="p">&amp;</span><span class="m">1</span><span class="k">)</span>
-curl -fsS --retry <span class="m">3</span> --data-raw <span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span> PING_URL
+curl -fsS -m <span class="m">10</span> --retry <span class="m">5</span> --data-raw <span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</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">&quot;X-Api-Key: </span><span class="nv">$API_KEY</span><span class="s2">&quot;</span> -d <span class="s2">&quot;</span><span class="nv">$PAYLOAD</span><span class="s2">&quot;</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>

templates/docs/bash.md

@@ -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:
+# Sends a HTTP GET request with curl:
-curl --retry 3 PING_URL
+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`
+* if the certbot command is successful (exit code 0), sends HTTP GET to `PING_URL`
-* otherwise, send HTTP GET to `PING_URL/fail`
+* 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
 ```

templates/docs/monitoring_cron_jobs.html

@@ -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">&amp;&amp;</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">&amp;&amp;</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
+<p>The extra options in the above example tells curl to retry failed HTTP requests, and
-there is an error. Feel free to adjust the curl options to suit your needs.</p>
+to silence output unless there is an error. Feel free to adjust the curl options to
-<table class="table curl-opts">
+suit your needs.</p>
-    <tr>
+<dl>
-        <th>&amp;&amp;</th>
+<dt><strong>&amp;&amp;</strong></dt>
-        <td>Run curl only if <code>/home/user/backup.sh</code> exits with an exit code 0</td>
+<dd>Run curl only if <code>/home/user/backup.sh</code> exits with an exit code 0.</dd>
-    </tr>
+<dt><strong>-f, --fail</strong></dt>
-    <tr>
+<dd>Makes curl treat non-200 responses as errors.</dd>
-        <th>
+<dt><strong>-s, --silent</strong></dt>
-            -f,  --fail
+<dd>Silent or quiet mode. Hides the progress meter, but also hides error messages.</dd>
-        </th>
+<dt><strong>-S, --show-error</strong></dt>
-        <td>Makes curl treat non-200 responses as errors</td>
+<dd>Re-enables error messages when -s is used.</dd>
-    </tr>
+<dt><strong>--retry &lt;num&gt;</strong></dt>
-    <tr>
+<dd>If a transient error is returned when curl tries to perform a
-        <th>-s, --silent</th>
+transfer, it will retry this number of times before  giving  up.
-        <td>Silent or quiet mode. Use it to hide progress meter,
+Setting  the number to  0 makes curl do no retries (which is the default).
-            but it also hides error messages.</td>
+Transient error is a timeout or an HTTP 5xx response code.</dd>
-    </tr>
+<dt><strong>-o /dev/null</strong></dt>
-    <tr>
+<dd>Redirect curl's stdout to /dev/null (error messages still go to stderr).</dd>
-        <th>-S, --show-error</th>
+</dl>
-        <td>Re-enables error messages when -s is used.</td>
-    </tr>
-    <tr>
-        <th>--retry &lt;num&gt;</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>
-
 <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>

templates/docs/monitoring_cron_jobs.md

@@ -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
+The extra options in the above example tells curl to retry failed HTTP requests, and
-there is an error. Feel free to adjust the curl options to suit your needs.
+to silence output unless there is an error. Feel free to adjust the curl options to
+suit your needs.
 
-<table class="table curl-opts">
+**&amp;&amp;**
-    <tr>
+:   Run curl only if `/home/user/backup.sh` exits with an exit code 0.
-        <th>&amp;&amp;</th>
+
-        <td>Run curl only if <code>/home/user/backup.sh</code> exits with an exit code 0</td>
+**-f, --fail**
-    </tr>
+:   Makes curl treat non-200 responses as errors.
-    <tr>
+
-        <th>
+**-s, --silent**
-            -f,  --fail
+:   Silent or quiet mode. Hides the progress meter, but also hides error messages.
-        </th>
+
-        <td>Makes curl treat non-200 responses as errors</td>
+**-S, --show-error**
-    </tr>
+:   Re-enables error messages when -s is used.
-    <tr>
+
-        <th>-s, --silent</th>
+**--retry &lt;num&gt;**
-        <td>Silent or quiet mode. Use it to hide progress meter,
+:   If a transient error is returned when curl tries to perform a
-            but it also hides error messages.</td>
+    transfer, it will retry this number of times before  giving  up.
-    </tr>
+    Setting  the number to  0 makes curl do no retries (which is the default).
-    <tr>
+    Transient error is a timeout or an HTTP 5xx response code.
-        <th>-S, --show-error</th>
+
-        <td>Re-enables error messages when -s is used.</td>
+**-o /dev/null**
-    </tr>
+:   Redirect curl's stdout to /dev/null (error messages still go to stderr).
-    <tr>
-        <th>--retry &lt;num&gt;</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>
 
 ## Looking up Your Machine's Time Zone
 

templates/docs/php.html

@@ -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>

templates/docs/php.md

@@ -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.