3 files changed, 121 insertions, 6 deletions
diff --git a/doc/index.html b/doc/index.html
index 7fcf79a..b830cb9 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -67,6 +67,8 @@ supervision that might help you understand the basics.
 <a href="libs6/ftrigr.html">ftrigr library</a> do exactly?</li>
 <li> How to run a s6-svscan-based supervision tree <a href="s6-svscan-not-1.html">without replacing init</a> </li>
 <li> How to <a href="s6-svscan-1.html">replace init</a> </li>
+<li> How to perform <a href="socket-activation.html">socket activation
+with s6</a> </li>
 </ul>
 
 <hr />
@@ -332,8 +334,7 @@ traditional init system for Linux. </li>
  <li> <a href="http://upstart.ubuntu.com/">Upstart</a> is a well-known init system
 for Linux, with complete service management, that comes with the Ubuntu
 distribution. It includes a coffee machine and the kitchen sink.</li>
- <li> Because Upstart wasn't complex enough, someone came up with
-<a href="systemd.html">systemd</a>, which is a problem in its own category. </li>
+ <li> <a href="systemd.html">systemd</a> is a problem in its own category. </li>
  <li> The various BSD flavors have their own style of
 <a href="http://www.freebsd.org/doc/handbook/boot-init.html">init</a>. </li>
  <li> MacOS X has its own init spaghetti monster called
diff --git a/doc/s6-fdholder-transferdumpc.html b/doc/s6-fdholder-transferdumpc.html
index 7bd6aa0..aea7181 100644
--- a/doc/s6-fdholder-transferdumpc.html
+++ b/doc/s6-fdholder-transferdumpc.html
@@ -71,11 +71,12 @@ takes care of all the plumbing. </li>
 requires special authorizations. Make sure the s6-fdholderd instances are
 <a href="s6-fdholderd.html#configuration">configured</a> to accept
 dump-getting and dump-setting requests from your client. </li>
- <li> The point of the
+ <li> A typical use case of
 <a href="s6-fdholder-transferdump.html">s6-fdholder-transferdump</a> and
-s6-fdholder-transferdumpc programs is to move a set of fds from one
-daemon to another, for instance in the event that the first one has to
-to shut down for an upgrade. </li>
+s6-fdholder-transferdumpc is when the main fd-holding daemon needs to
+upgrade, or restart for some reason. Transferring the file descriptors
+into another, temporary fd-holding daemon instance allows it to
+restart without losing the descriptors. </li>
 </ul>
 
 </body>
diff --git a/doc/socket-activation.html b/doc/socket-activation.html
new file mode 100644
index 0000000..b2e726a
--- /dev/null
+++ b/doc/socket-activation.html
@@ -0,0 +1,113 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6: socket activation</title>
+    <meta name="Description" content="s6: socket activation" />
+    <meta name="Keywords" content="s6 socket activation fd-holding client server socket fd passing" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">s6</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> How do I perform socket activation with s6&nbsp;? </h1>
+
+<p>
+ First, it's important to realize that you don't <em>need</em>
+socket activation. It's a marketing word used by systemd
+advocates that mixes a couple useful architecture concepts and several
+horrible ideas, for a very minor speed benefit. Read
+<a href="http://skarnet.org/cgi-bin/archive.cgi?2:mss:423:oanakciaccabjicoagef">this mail</a>
+and
+<a href="http://forums.gentoo.org/viewtopic-t-994548-postdays-0-postorder-asc-start-25.html#7581522">this
+post</a> for details.
+</p>
+
+<ul>
+ <li> s6 <em>will not</em> help you implement super-servers in process 1,
+because doing so is bad engineering.
+However, it <em>will</em> help you set up super-servers. The
+<a href="s6-ipcserver.html">s6-ipcserver</a>
+program, for Unix domain sockets, as well as the
+<a href="http://skarnet.org/software/s6-networking/s6-tcpserver4.html">s6-tcpserver4</a> and
+<a href="http://skarnet.org/software/s6-networking/s6-tcpserver6.html">s6-tcpserver6</a>
+programs, for TCP INET domain sockets (available in the
+<a href="http://skarnet.org/software/s6-networking/">s6-networking</a>
+package) are super-servers you can use to
+your heart's content. They are even wrappers around simpler programs,
+and you can use their components in the way you choose: bind sockets,
+drop privileges, accept connections from clients, it's all about what you
+write in your command line. Super-servers are a good thing; using process 1
+to act as a super-server is not. s6 provides you with the tools to get
+the good without the bad. </li>
+ <li> s6 <em>will not</em> help you run all your services before their
+dependencies are met, because doing so is <em>very</em> bad engineering.
+However, it <em>will</em> provide you with:
+ <ul>
+  <li> a reliable logging infrastructure, that makes sure your services
+never lose logs:
+<a href="s6-log.html">s6-log</a>, in conjunction with
+<a href="s6-supervise.html">s6-supervise</a> and
+<a href="s6-svscan.html">s6-svscan</a>. </li>
+  <li> ways to open your sockets and bind them as early as you want in
+your boot process, and make them accept client connections later:
+<a href="s6-ipcserver-socketbinder.html">s6-ipcserver-socketbinder</a>,
+<a href="http://skarnet.org/software/s6-networking/s6-tcpserver4-socketbinder.html">s6-tcpserver4-socketbinder</a> and
+<a href="http://skarnet.org/software/s6-networking/s6-tcpserver6-socketbinder.html">s6-tcpserver4-socketbinder</a>.
+ </li>
+ <li> A supervision infrastructure that can start as many services in parallel
+as you want:
+<a href="s6-supervise.html">s6-supervise</a> and
+<a href="s6-svscan.html">s6-svscan</a>. </li>
+ </ul> </li>
+ <li> s6 <em>will not</em> help you centralize all your socket information
+in process 1, because doing so is contrary to modularity and independence
+of services. However, s6
+<em>will</em> provide you with a way to store your open sockets and
+retrieve them when you want, which it calls "fd holding":
+<a href="s6-fdholder-daemon.html">s6-fdholder-daemon</a>. </li>
+</ul>
+
+<h2> So, how do I open all my sockets first, store them, and dispatch them
+to daemons later&nbsp;? </h2>
+
+<p>
+ Again, it's not necessary to do that: you'll be fine, and quite speedy,
+just starting your
+daemons in their good time. You <em>will not</em> reap any noticeable
+benefit from performing "socket activation". But if you really want to:
+</p>
+
+<ol>
+ <li> Make sure you have an early supervision infrastructure running.
+Ideally, you would <a href="s6-svscan-1.html">make s6-svscan your
+process 1</a>. </li>
+ <li> Start an early <a href="s6-fdholder-daemon.html">fd-holding
+service</a>. Let's say the fd-holding daemon is listening on socket
+<tt>/service/fdholder/s</tt>. </li>
+ <li> For every Unix domain socket <em>/my/socket</em> you need to open, run
+<tt>s6-ipcserver-socketbinder /my/socket s6-fdholder-store /service/fdholder/s
+unix:/my/socket</tt>. You can do the same with INET domain sockets. </li>
+ <li> Proceed to your initialization. </li>
+ <li> When you want to run a daemon <em>myserverd</em> that accepts clients
+connecting to <em>/my/socket</em>, run <tt>s6-fdholder-retrieve
+/service/fdholder/s unix:/my/socket myserverd</tt>. <em>myserverd</em>
+will be executed with <em>/my/socket</em> as its standard input. </li>
+ <li> The descriptors remain safely stored in the fd-holding daemon and you
+can retrieve them again whenever you want, for instance when your service
+crashes and is restarted. </li>
+</ol>
+
+<p>
+ That is all there is to it. You don't have to use specific libraries
+or write complex unit files, you just need to understand how a command
+line works. This is Unix.
+</p>
+
+</body>
+</html>