From ce49b0504c523820be6ba33ac370da19bf75d9eb Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sun, 18 Jun 2017 15:35:40 +0000
Subject:  Usability changes for transition failures in s6-rc change

 - Add explicit s6-svc -d call for longrun transition failure
 - Add SIGTERM and SIGINT handling: kill all longrun transitions
 - Doc update
 - Credit Lionel
 - Prepare for 0.2.1.0
---
 doc/s6-rc.html | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

(limited to 'doc/s6-rc.html')

diff --git a/doc/s6-rc.html b/doc/s6-rc.html
index 957c108..7052b45 100644
--- a/doc/s6-rc.html
+++ b/doc/s6-rc.html
@@ -252,6 +252,31 @@ s6-rc will wait forever on an "up" transition for the notification
 to arrive. The transition will fail if a timeout occurs.
 </p>
 
+<p>
+ If a <em>down</em> transition fails, s6-rc does nothing with it. The service
+has already received a SIGTERM, and may be stuck in the process of exiting;
+or it may already have died but is stuck in a bad <tt>finish</tt> script
+that is not timing out. In any case, it is not a situation that s6-rc
+can recover from; the service is most likely down, but the administrator
+should manually check their process list. And fix their scripts, or
+timeout values, because a <em>down</em> transition failure is always a
+programmer or sysadmin error.
+</p>
+
+<p>
+ If an <em>up</em> transition fails, s6-rc sends an explicit
+<a href="//skarnet.org/software/s6/s6-svc.html">s6-svc -d</a> command to
+the longrun. This ensures the service is in a known <em>down</em> state
+when failing to go up, instead of (for instance) being stuck in a not-ready
+limbo state.
+</p>
+
+<p>
+ Note that proper usage of the <tt>timeout-kill</tt> and <tt>timeout-finish</tt>
+values in the longrun's definition directory can considerably reduce the
+number of cases where the service is left in an unknown state.
+</p>
+
 <p>
  Transitions are supposed to be idempotent, but it is a general
 rule of supervision that <tt>run</tt> and <tt>finish</tt> scripts
@@ -310,6 +335,21 @@ each simulated transition will take <em>dryrunthrottle</em>
 milliseconds to complete successfully.
 </p>
 
+<h2> Signals </h2>
+
+<p>
+ <tt>s6-rc change</tt> reacts to the following signals:
+</p>
+
+<ul>
+ <li> SIGTERM: s6-rc immediately aborts all its longrun transitions with
+a failure, and the impacted longruns will most likely be in a <em>down</em>
+state. Oneshot transitions are untouched, because killing the
+oneshot subprocess would make it impossible to determine what state the
+oneshot service is in. </li>
+ <li> SIGINT: same as SIGTERM. </li>
+</ul>
+
 <h2> Usage examples </h2>
 
 <pre> s6-rc change <em>myservicebundle</em> </pre>
-- 
cgit v1.2.3