From bb9a68add4feef7c53ba3994256745ea99cffef8 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Mon, 20 Mar 2017 20:34:12 +0000
Subject:  Implement permanent failure for services via ./finish exiting 125

---
 doc/s6-supervise.html |  4 ++++
 doc/servicedir.html   | 12 +++++++++---
 2 files changed, 13 insertions(+), 3 deletions(-)

(limited to 'doc')

diff --git a/doc/s6-supervise.html b/doc/s6-supervise.html
index 081aeae..55cba6f 100644
--- a/doc/s6-supervise.html
+++ b/doc/s6-supervise.html
@@ -56,6 +56,10 @@ s6-supervise kills it with a SIGKILL. This can be configured via the
  <li> When <tt>./finish</tt> dies (or is killed),
 s6-supervise sends a <tt>'D'</tt> event to <tt>./event</tt>. Then
 it restarts <tt>./run</tt> unless it has been told not to. </li>
+ <li> If <tt>./finish</tt> exits 125, then s6-supervise sends a <tt>'O'</tt> event
+to <tt>./event</tt> <em>before</em> the <tt>'D'</tt>, and it
+<strong>does not restart the service</strong>, as if <tt>s6-svc -O</tt> had
+been called. This can be used to signify permanent failure to start the service. </li>
  <li> There is a minimum 1-second delay between two <tt>./run</tt> spawns, to avoid busylooping
 if <tt>./run</tt> exits too quickly. </li>
  <li> When killed or asked to exit, it waits for the service to go down one last time, then
diff --git a/doc/servicedir.html b/doc/servicedir.html
index 98929bb..a0d98f0 100644
--- a/doc/servicedir.html
+++ b/doc/servicedir.html
@@ -87,15 +87,21 @@ is executed everytime the <tt>run</tt> script dies. Generally, its main
 purpose is to clean up non-volatile data such as the filesystem after the supervised
 process has been killed. If the <em>foo</em> service is supposed to be up,
 <em>foo</em><tt>/run</tt> is restarted
-after <em>foo</em><tt>/finish</tt> dies. By default, a finish script must do
-its work and exit in less than                              
+after <em>foo</em><tt>/finish</tt> dies.
+ <ul>
+  <li> By default, a finish script must do its work and exit in less than                              
 5 seconds; if it takes more than that, it is killed. (The point is that the run
 script, not the finish script, should be running; the finish script should really
 be short-lived.) The maximum duration of a <tt>finish</tt> execution can be
-configured via the <tt>timeout-finish</tt> file, see below. The finish script is
+configured via the <tt>timeout-finish</tt> file, see below. </li>
+  <li> The finish script is
 executed with two arguments: the exit code from the run script (resp. 256 if the
 run script was killed by a signal), and an undefined number (resp. the number of
 the signal that killed the run script). </li>
+  <li> If the finish script exits 125, then <a href="s6-supervise.html">s6-supervise</a>
+interprets this as a permanent failure for the service, and does not restart it,
+as if an <a href="s6-svc.html">s6-svc -O</a> command had been sent. </li>
+ </ul> </li>
  <li> A directory named <tt>supervise</tt>. It is automatically created by
 <a href="s6-supervise.html">s6-supervise</a> if it does not exist. This is where
 <a href="s6-supervise.html">s6-supervise</a> stores its information. The directory
-- 
cgit v1.2.3