From 5a318ce649a7a5f754892518a4452a519b41dac8 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Fri, 4 Dec 2020 07:25:12 +0000
Subject:  Big signal/command semantics change to svscan/supervise; add
 s6-svperms.

---
 doc/s6-svscanctl.html | 75 +++++++++++++++++----------------------------------
 1 file changed, 25 insertions(+), 50 deletions(-)

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

diff --git a/doc/s6-svscanctl.html b/doc/s6-svscanctl.html
index ae0f8ee..6340c14 100644
--- a/doc/s6-svscanctl.html
+++ b/doc/s6-svscanctl.html
@@ -26,82 +26,57 @@ process.
 <h2> Interface </h2>
 
 <pre>
-     s6-svscanctl [ -phratszbnNiq0678 ] <em>svscandir</em>
+     s6-svscanctl [ -zabhitqnN ] <em>scandir</em>
 </pre>
 
 <p>
 s6-svscanctl sends the given series of commands to the
 <a href="s6-svscan.html">s6-svscan</a> process monitoring the
-<em>svscandir</em> directory, then exits 0. It exits 111 if it cannot send
-a command, or 100 if no s6-svscan process is running on <em>svscandir</em>.
+<em>scandir</em> directory, then exits 0. It exits 111 if it cannot send
+a command, or 100 if no s6-svscan process is running on <em>scandir</em>.
 </p>
 
 <h2> Options </h2>
 
 <ul>
- <li> <tt>-p</tt>&nbsp;: poweroff mode. s6-svscan will exec into
- <tt>./.s6-svscan/finish poweroff</tt> when it is told to terminate. </li>
- <li> <tt>-h</tt>&nbsp;: Hangup. s6-svscan will send a SIGHUP to all the
-maintained s6-supervise processes, then run its finish procedure. </li>
- <li> <tt>-r</tt>&nbsp;: reboot mode. s6-svscan will exec into
- <tt>./.s6-svscan/finish reboot</tt> when it is told to terminate. This
-is s6-svscan's default mode.</li>
- <li> <tt>-a</tt>&nbsp;: Alarm. s6-svscan will immediately perform a scan
-of <em>svscandir</em> to check for services. </li>
- <li> <tt>-t</tt>&nbsp;: Terminate. s6-svscan will send a
-SIGTERM to all the s6-supervise processes supervising a service and a
-SIGHUP to all the s6-supervise processes supervising a logger, then run its
-finish procedure. </li>
- <li> <tt>-s</tt>&nbsp;: halt mode. s6-svscan will exec into
- <tt>./.s6-svscan/finish halt</tt> when it is told to terminate. </li>
  <li> <tt>-z</tt>&nbsp;: destroy zombies. Immediately triggers s6-svscan's
 reaper mechanism. </li>
+ <li> <tt>-a</tt>&nbsp;: Alarm. s6-svscan will immediately perform a scan
+of <em>scandir</em> to check for services. </li>
  <li> <tt>-b</tt>&nbsp;: abort. s6-svscan will exec into its finishing
 procedure. It will not kill any of the maintained s6-supervise processes. </li>
+ <li> <tt>-h</tt>&nbsp;: Reload configuration. s6-svscan will perform a scan,
+and destroy inactive services. Equivalent to <tt>-an</tt>. </li>
+ <li> <tt>-i</tt>&nbsp;: equivalent to <tt>-t</tt> below. </li>
+ <li> <tt>-t</tt>&nbsp;: Terminate. s6-svscan will send a
+SIGTERM to all the s6-supervise processes supervising a service and a
+SIGHUP to all the s6-supervise processes supervising a logger, then exec into
+its finish procedure. This means that services will be brought down but
+loggers will exit naturally on EOF, and s6-svscan will wait for them to exit
+before exec'ing into <tt>.s6-svscan/finish</tt> or exiting itself: it's a
+clean shutdown with no loss of logs. </li>
+ <li> <tt>-q</tt>&nbsp;: Quit. s6-svscan will send all its s6-supervise processes
+a SIGTERM, then exec into its finish procedure. This is different from <tt>-t</tt>
+in that services <em>and</em> loggers will be forcibly killed, so the quit
+procedure may be faster but in-flight logs may be lost. </li>
  <li> <tt>-n</tt>&nbsp;: nuke. s6-svscan will kill all the
 s6-supervise processes it has launched but that did not match a service
-directory last time <em>svscandir</em> was scanned, i.e. it prunes the
-supervision tree so that it matches exactly what was in <em>svscandir</em>
+directory last time <em>scandir</em> was scanned, i.e. it prunes the
+supervision tree so that it matches exactly what was in <em>scandir</em>
 at the time of the last scan. A SIGTERM is sent to the s6-supervise processes
 supervising services and a SIGHUP is sent to the s6-supervise processes
 supervising loggers. </li>
  <li> <tt>-N</tt>&nbsp;: Really nuke. Does the same thing as <tt>-n</tt>,
 except that SIGTERM is sent to all the relevant s6-supervise processes, even
-if they are supervising loggers. That means that the logger processes will
-be killed with a SIGTERM instead of being allowed to exit at their own pace. </li>
- <li> <tt>-i</tt>&nbsp;: Interrupt. Equivalent to <tt>-rt</tt>&nbsp;: s6-svscan
-will terminate in reboot mode. </li>
- <li> <tt>-q</tt>&nbsp;: Quit. s6-svscan will send all its s6-supervise processes
-a SIGTERM, then exec into its finish procedure. </li>
- <li> <tt>-0</tt>&nbsp;: Halt. Equivalent to <tt>-st</tt>&nbsp;: s6-svscan will
-terminate in halt mode. </li>
- <li> <tt>-6</tt>&nbsp;: Reboot. Equivalent to <tt>-i</tt>. </li>
- <li> <tt>-7</tt>&nbsp;: Poweroff. Equivalent to <tt>-pt</tt>: s6-svscan will
-terminate in poweroff mode. </li>
- <li> <tt>-8</tt>&nbsp;: Other. s6-svscan will terminate in "other" mode. </li>
+if they are supervising loggers. This is not recommended in a situation where
+you do not need to tear down the supervision tree. </li>
 </ul>
 
-<h2> Usage examples </h2>
-
-<pre> s6-svscanctl -an /service </pre>
-<p>
- Updates the process supervision tree
-to exactly match the services listed in <tt>/service</tt>.
-</p>
-
-<pre> s6-svscanctl -6 /service </pre>
-<p>
- Orders the s6-svscan process monitoring <tt>/service</tt> to exit in
-reboot mode: all the supervision tree at <tt>/service</tt> will be terminated,
-and s6-svscan will execute into the <tt>/service/.s6-svscan/finish</tt>
-script with the <tt>reboot</tt> argument.
-</p>
-
 <h2> Internals </h2>
 
 <p>
-s6-svscanctl writes control commands into the <tt><em>svscandir</em>/.s6-svscan/control</tt>
-FIFO. An s6-svscan process running on <em>svscandir</em> will be listening to this FIFO,
+s6-svscanctl writes control commands into the <tt><em>scandir</em>/.s6-svscan/control</tt>
+FIFO. An s6-svscan process running on <em>scandir</em> will be listening to this FIFO,
 and will read and interpret those commands.
 </p>
 
-- 
cgit v1.3.1