From 3d42e4b42964f4cec4e8d9f06ddf80c956dbfbb2 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sun, 20 Aug 2017 10:10:19 +0000
Subject:  Doc updates

---
 doc/notifywhenup.html | 12 ++++++++++++
 doc/overview.html     | 30 ++++++++++++++++++++++--------
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/doc/notifywhenup.html b/doc/notifywhenup.html
index 363438b..d788938 100644
--- a/doc/notifywhenup.html
+++ b/doc/notifywhenup.html
@@ -79,5 +79,17 @@ to provide reliable startup notifications, and subscribers should then
 be content with the unreliable <tt>'u'</tt> events provided by s6-supervise.
 </p>
 
+<p>
+Unfortunately, a lot of long-running programs do not offer that
+functionality; instead, they provide a way to poll them, an external
+program that runs and checks whether the service is ready. This is a
+<a href="//skarnet.org/software/s6/ftrig.html">bad</a> mechanism, for
+<a href="//skarnet.org/cgi-bin/archive.cgi?2:mss:1607:dfblejammjllfkggpcph">several</a>
+reasons. Nevertheless, until all daemons are patched to notify their
+own readiness, s6 provides a way to run such a check program to poll
+for readiness, and route its result into the s6 notification system:
+<a href="s6-notifyoncheck.html">s6-notifyoncheck</a>.
+</p>
+
 </body>
 </html>
diff --git a/doc/overview.html b/doc/overview.html
index 2be2ca5..9fb82fc 100644
--- a/doc/overview.html
+++ b/doc/overview.html
@@ -41,12 +41,13 @@ close cousin
 
 <ul>
  <li> Unix systems, even minimalistic ones, need to run
-<em>long-lived processes</em>, aka <em>daemons</em>. Sometimes, they
-need to run <em>a lot</em> of them.</li>
+<em>long-lived processes</em>, aka <em>daemons</em>. That is one of the
+core design principles of Unix: one service &rarr; one daemon. </li>
  <li> Daemons can die unexpectedly. Maybe they are missing a vital
 resource and cannot handle a certain failure; maybe they tripped on a bug;
 maybe a misconfigured administration program killed them; maybe the
-kernel killed them. </li>
+kernel killed them. Processes are fragile, but daemons are vital to a
+Unix system: a fundamental discrepancy that needs to be solved. </li>
  <li> Automatically restarting daemons when they die is generally a good
 thing. In any case, sysadmin intervention is necessary, but at least the
 daemon is providing service, or trying to, until the sysadmin can log in
@@ -141,10 +142,12 @@ run and
 <a href="//skarnet.org/software/s6/s6-svscan-not-1.html">supervised
 by your regular init process</a>, or it can
 <a href="//skarnet.org/software/s6/s6-svscan-1.html">run as
-process 1 itself</a>. Running s6-svscan as process 1 currently requires
-some manual effort from the user, because of the inherent non-portability
-of init processes; future versions of s6 will automate that effort and
-provide users with ready-to-run "init" commands. </li>
+process 1 itself</a>. Running s6-svscan as process 1 requires
+some effort from the user, because of the inherent non-portability of
+init processes; the
+<a href="//skarnet.org/software/s6-linux-init/">s6-linux-init</a>
+package automates that effort and allows users to run s6 as an init
+replacement. </li>
   <li> The configuration of a daemon to be supervised by
 <a href="s6-supervise.html">s6-supervise</a> is done via a
 <a href="servicedir.html">service directory</a>. </li>
@@ -267,7 +270,12 @@ need to replicate in your run script.
 invocation: start-stop-daemon and its friends are hideous and kludgy
 attempts to work around the lack of proper supervision mechanisms. Now
 that you have s6, you should remove them from your system, throw them
-into a bonfire, and dance and laugh while they burn.)
+into a bonfire, and dance and laugh while they burn. Generally speaking,
+as a system administrator you want daemons that have been designed
+following the principles described
+<a href="https://jdebp.eu/FGA/unix-daemon-design-mistakes-to-avoid.html">here</a>,
+or at least you want to use the command-line options that make them
+behave in such a way.) 
 </p>
 
 <p>
@@ -356,6 +364,12 @@ supports a simple mechanism: when a daemon wants to signal that it is
 choice, and <a href="s6-supervise.html">s6-supervise</a> will pick that
 notification up and broadcast the information to processes waiting for
 it. </li>
+ <li> s6 also has a legacy mechanism for daemons that do not
+notify their own readiness but provide a way for an external program
+to check whether they're ready or not:
+<a href="s6-notifyoncheck.html">s6-notifyoncheck</a>.
+ This is polling, which is bad, but unfortunately necessary for
+many daemons as of 2017. </li>
 </ul>
 
 <p>
-- 
cgit v1.2.3