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/index.html   |  6 +++---
 doc/s6-rc.html   | 40 ++++++++++++++++++++++++++++++++++++++++
 doc/upgrade.html | 15 +++++++++++++++
 3 files changed, 58 insertions(+), 3 deletions(-)

(limited to 'doc')

diff --git a/doc/index.html b/doc/index.html
index 39d0208..aec93ff 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -48,11 +48,11 @@ scripts are also run in a controlled environment.
  <li> A POSIX-compliant system with a standard C development environment </li>
  <li> GNU make, version 3.81 or later </li>
  <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version
-2.5.1.0 or later </li>
+2.5.1.1 or later </li>
  <li> <a href="//skarnet.org/software/execline/">execline</a> version
 2.3.0.1 or later </li>
  <li> <a href="//skarnet.org/software/s6/">s6</a> version
-2.5.1.0 or later </li>
+2.6.0.0 or later </li>
 </ul>
 
 <h3> Licensing </h3>
@@ -66,7 +66,7 @@ scripts are also run in a controlled environment.
 
 <ul>
  <li> The current released version of s6-rc is
-<a href="s6-rc-0.2.0.1.tar.gz">0.2.0.1</a>. </li>
+<a href="s6-rc-0.2.1.0.tar.gz">0.2.1.0</a>. </li>
  <li> Alternatively, you can checkout a copy of the
 <a href="//git.skarnet.org/cgi-bin/cgit.cgi/s6-rc/">s6-rc
 git repository</a>:
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>
diff --git a/doc/upgrade.html b/doc/upgrade.html
index 3db2fd0..2e4bd72 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -18,6 +18,21 @@
 
 <h1> What has changed in s6-rc </h1>
 
+<h2> in 0.2.1.0 </h2>
+
+<ul>
+ <li> <a href="//skarnet.org/software/skalibs/">skalibs</a>
+dependency bumped to 2.5.1.1. </li>
+ <li> <a href="//skarnet.org/software/execline/">execline</a>
+dependency bumped to 2.3.0.1. </li>
+ <li> <a href="//skarnet.org/software/s6/">s6</a>
+dependency bumped to 2.6.0.0. </li>
+ <li> <a href="s6-rc.html">s6-rc change</a> now ensures that a
+longrun is down when its up transition fails. </li>
+ <li> <a href="s6-rc.html">s6-rc change</a> now kills subprocesses
+waiting on a longrun transition when it receives a SIGINT or a SIGTERM. </li>
+</ul>
+
 <h2> in 0.2.0.1 </h2>
 
 <ul>
-- 
cgit v1.3.1