Tweaking shell script examples

templates/docs/bash.html

@@ -1,34 +1,44 @@
-<h1>Shell scripts</h1>
+<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. curl and wget
-are two common command line HTTP clients for that.</p>
-<h2>Using curl</h2>
+have to do is make a HTTP request at the end of 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><span class="c1"># Sending a HTTP GET request with curl:</span>
+curl --retry <span class="m">3</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
+</pre></div>
+
+
+<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>
+<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>
+</ul>
 <div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span>
 
-<span class="c1"># Exit immediately if any command exits with a non-zero status:</span>
-<span class="nb">set</span> -e
+<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>
+</pre></div>
 
-<span class="c1"># Do the work here</span>
-<span class="nb">echo</span> <span class="s2">&quot;Pretending to to make backups...&quot;</span>
-sleep <span class="m">5</span>
-<span class="nb">echo</span> <span class="s2">&quot;Backup complete!&quot;</span>
 
-<span class="c1"># As the last thing, ping SITE_NAME using curl:</span>
-<span class="hll">curl --retry <span class="m">3</span> PING_URL
-</span></pre></div>
-
-
-<h2>Using wget</h2>
+<h2>Logging Command Output</h2>
+<p>When pinging with HTTP POST, you can put extra diagnostic information in request
+body. If the request body looks like a valid UTF-8 string, SITE_NAME
+will accept and store 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><span class="ch">#!/bin/sh</span>
 
-<span class="c1"># Exit immediately if any command exits with a non-zero status:</span>
-<span class="nb">set</span> -e
-
-<span class="c1"># Do the work here</span>
-<span class="nb">echo</span> <span class="s2">&quot;Pretending to to generate reports...&quot;</span>
-sleep <span class="m">5</span>
-<span class="nb">echo</span> <span class="s2">&quot;Report generation complete!&quot;</span>
-
-<span class="c1"># As the last thing, ping SITE_NAME using wget:</span>
-<span class="hll">wget PING_URL -O /dev/null
-</span></pre></div>
+<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> -X POST --data-raw <span class="s2">&quot;</span><span class="nv">$m</span><span class="s2">&quot;</span> PING_URL
+</pre></div>

templates/docs/bash.md

@@ -1,39 +1,51 @@
-# Shell scripts
+# 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. curl and wget
-are two common command line HTTP clients for that.
+have to do is make a HTTP request at the end of 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.
 
-## Using curl
+```bash
+# Sending a HTTP GET request with curl:
+curl --retry 3 PING_URL
 
-```bash hl_lines="12"
-#!/bin/sh
+# Silent version (no stdout/stderr output unless curl hits an error):
+curl -fsS --retry 3 PING_URL
 
-# Exit immediately if any command exits with a non-zero status:
-set -e
+# Sending a HTTP GET request with wget:
+wget PING_URL -O /dev/null
+```
 
-# Do the work here
-echo "Pretending to to make backups..."
-sleep 5
-echo "Backup complete!"
+## Signalling Failure from Shell Scripts
 
-# As the last thing, ping SITE_NAME using curl:
-curl --retry 3 PING_URL
-```
+You can append `/fail` to any ping URL and  use the resulting URL to actively
+signal a failure. The below example:
 
-## Using wget
+* 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`
 
-```bash hl_lines="12"
+```bash
 #!/bin/sh
 
-# Exit immediately if any command exits with a non-zero status:
-set -e
+# Payload here:
+/usr/bin/certbot renew
+# Ping SITE_NAME
+curl --retry 3 "PING_URL$([ $? -ne 0 ] && echo -n /fail)"
+```
 
-# Do the work here
-echo "Pretending to to generate reports..."
-sleep 5
-echo "Report generation complete!"
+## Logging Command Output
 
-# As the last thing, ping SITE_NAME using wget:
-wget PING_URL -O /dev/null
-```
+When pinging with HTTP POST, you can put extra diagnostic information in request
+body. If the request body looks like a valid UTF-8 string, SITE_NAME
+will accept and store first 10KB of the request body.
+
+In the below example, certbot's output is captured and submitted via HTTP POST:
+
+```bash
+#!/bin/sh
+
+m=$(/usr/bin/certbot renew 2>&1)
+curl -fsS --retry 3 -X POST --data-raw "$m" PING_URL
+```

templates/docs/configuring_checks.html

@@ -25,7 +25,7 @@ what to do in case of failures, where to look for additional information.</li>
 for monitoring processes that are expected to run at relatively regular time
 intervals: once an hour, once a day, once a week.</p>
 <p><img alt="Editing the period and grace time" src="IMG_URL/edit_simple_schedule.png" /></p>
-<p>For simple schedules you configure two time durations, <strong>Period</strong> and <strong>Grace Time</strong>.</p>
+<p>For simple schedules you configure two time durations, Period and Grace Time.</p>
 <ul>
 <li><strong>Period</strong>: the expected time between pings</li>
 <li><strong>Grace Time</strong>: when a check is late, how long to wait before sending an alert.
@@ -33,7 +33,7 @@ Use this variable to account for small, expected deviations in job execution tim
 </ul>
 <h2>Cron Schedules</h2>
 <p>Use "cron" for monitoring processes with more complex schedules, and to ensure
-jobs run <strong>at the correct time</strong> (not just at correct intervals).</p>
+jobs run <strong>at the correct time</strong> (not just at correct time intervals).</p>
 <p><img alt="Editing cron schedule" src="IMG_URL/edit_cron_schedule.png" /></p>
 <p>You will need to specify Cron Expression, Server's Time Zone and Grace Time.</p>
 <ul>

templates/docs/configuring_checks.md

@@ -32,7 +32,7 @@ intervals: once an hour, once a day, once a week.
 
 ![Editing the period and grace time](IMG_URL/edit_simple_schedule.png)
 
-For simple schedules you configure two time durations, **Period** and **Grace Time**.
+For simple schedules you configure two time durations, Period and Grace Time.
 
 * **Period**: the expected time between pings
 * **Grace Time**: when a check is late, how long to wait before sending an alert.
@@ -41,7 +41,7 @@ Use this variable to account for small, expected deviations in job execution tim
 ## Cron Schedules
 
 Use "cron" for monitoring processes with more complex schedules, and to ensure
-jobs run **at the correct time** (not just at correct intervals).
+jobs run **at the correct time** (not just at correct time intervals).
 
 ![Editing cron schedule](IMG_URL/edit_cron_schedule.png)
 

templates/docs/python.html

@@ -19,14 +19,8 @@
 </pre></div>
 
 
-<p>You can include additional diagnostic information in the in the request body (for POST requests), or in the "User-Agent" request header:</p>
+<p>You can include additional diagnostic information in the in the request body (for POST requests):</p>
 <div class="highlight"><pre><span></span><span class="c1"># Passing diagnostic information in the POST body:</span>
 <span class="kn">import</span> <span class="nn">requests</span>
 <span class="n">requests</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;PING_URL&quot;</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="s2">&quot;temperature=-7&quot;</span><span class="p">)</span>
-</pre></div>
-
-
-<div class="highlight"><pre><span></span><span class="c1"># Passing diagnostic information in the User-Agent header:</span>
-<span class="kn">import</span> <span class="nn">requests</span>
-<span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;PING_URL&quot;</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;User-Agent&quot;</span><span class="p">:</span> <span class="s2">&quot;temperature=-7&quot;</span><span class="p">})</span>
 </pre></div>

templates/docs/python.md

@@ -22,16 +22,10 @@ import urllib
 urllib.urlopen("PING_URL")
 ```
 
-You can include additional diagnostic information in the in the request body (for POST requests), or in the "User-Agent" request header:
+You can include additional diagnostic information in the in the request body (for POST requests):
 
 ```python
 # Passing diagnostic information in the POST body:
 import requests
 requests.post("PING_URL", data="temperature=-7")
-```
-
-```python
-# Passing diagnostic information in the User-Agent header:
-import requests
-requests.get("PING_URL", headers={"User-Agent": "temperature=-7"})
-```
+```

templates/front/base_docs.html

@@ -17,8 +17,8 @@
         {% include "front/docs_nav_item.html" with slug="measuring_script_run_time" title="Measuring script run time" %}
         {% include "front/docs_nav_item.html" with slug="attaching_logs" title="Attaching logs" %}
 
-        <li class="nav-header">Platforms</li>
-        {% include "front/docs_nav_item.html" with slug="bash" title="Bash" %}
+        <li class="nav-header">Pinging Examples</li>
+        {% include "front/docs_nav_item.html" with slug="bash" title="Shell Scripts" %}
         {% include "front/docs_nav_item.html" with slug="python" title="Python" %}
         {% include "front/docs_nav_item.html" with slug="ruby" title="Ruby" %}
         {% include "front/docs_nav_item.html" with slug="php" title="PHP" %}