updating rendered manpage for github docs

1 files changed, 75 insertions, 26 deletions

diff --git a/index.html b/index.html
index 1113746..10f54ff 100644
--- a/index.html
+++ b/index.html
@@ -62,6 +62,8 @@
     <a href="#NAME">NAME</a>
     <a href="#SYNOPSIS">SYNOPSIS</a>
     <a href="#DESCRIPTION">DESCRIPTION</a>
+    <a href="#CHILD-API">CHILD API</a>
+    <a href="#HISTORY">HISTORY</a>
     <a href="#STATUS">STATUS</a>
     <a href="#COPYRIGHT">COPYRIGHT</a>
     <a href="#SEE-ALSO">SEE ALSO</a>
@@ -80,43 +82,90 @@
 
 <h2 id="SYNOPSIS">SYNOPSIS</h2>
 
-<p><code>einhyrningsins</code> [OPTIONS] -- PROGRAM [PROGRAM_ARGS]</p>
+<p><code>einhyrningsins</code> [<var>OPTIONS</var>] [--] <var>PROGRAM</var> [<var>PROGRAM_ARGS</var>]</p>
 
 <h2 id="DESCRIPTION">DESCRIPTION</h2>
 
-<p>This is a socket multiplexer featuring graceful restarts. It runs multiple
-copies of the child program that are passed a shared socket (or more than one)
-to bind to and accept connections from. Graceful rolling restarts enable
-updates of the child program with zero downtime and no dropped connections.</p>
+<p><code>Einhyrningsins</code> is a socket multiplexer featuring graceful restarts. It runs
+multiple copies of a child program, each of which are passed a shared socket
+(or multiple shared sockets) to <span class="man-ref">bind<span class="s">(2)</span></span> to and <span class="man-ref">accept<span class="s">(2)</span></span> connections from.
+Graceful, rolling restarts enable updates of the child program with zero
+downtime and no dropped connections.</p>
 
 <p>This program requires special support in the child program to achive the
-graceful restarts and bind to inherited file descriptors indicated by
-environment variables.</p>
-
-<p><a class="man-ref" href="einhyrningsins.1.html">einhyrningsins<span class="s">(1)</span></a> is a partially-comparible re-implementation of <span class="man-ref">einhorn<span class="s">(1)</span></span> (a
-Ruby program) in Rust.  Einhorn itself derived from Unicorn.</p>
+graceful restarts (aka, exiting only after all connection close) and to be able
+to bind to inherited file descriptors (as indicated by environment variables).
+Child programs must also be able to run in parallel: for example, each copy
+must not try to write to the same output file without some form of locking.</p>
 
 <ul>
-<li><code>-n</code>, <code>--number</code>=COUNT
-How many child processes to spawn.</li>
-<li><code>-b</code>, <code>--bind</code> ADDR
-Socket(s) to bind to. This argument can be repeated.</li>
-<li><code>-4</code>, <code>--ipv4-only</code>:
-Only accept IPv4 connections</li>
-<li><code>-6</code>, <code>--ipv6-only</code>
-Only accept IPv6 connections</li>
-<li><code>-h</code>, <code>--help</code>
-Print a help menu</li>
-<li><code>--version</code>
-Print program version</li>
-<li><code>-v</code>, <code>--verbose</code>
-More verbose logging and output</li>
+<li><p><code>-n</code>, <code>--number</code> <var>COUNT</var>:
+How many child processes to spawn.</p></li>
+<li><p><code>-b</code>, <code>--bind</code> <var>ADDR</var>:<var>PORT</var>[,<var>OPT</var>...]:
+Socket(s) to bind to. <var>OPT</var> specifies flags to be set on the socket. Options
+are <code>n</code> for non-blocking (<code>O_NONBLOCK</code>) and <code>r</code> for re-using addresses
+(<code>SO_REUSEADDR</code>). Eg, for both options, could pass <code>-b 127.0.0.1:1234,r,n</code>.
+This argument can be repeated.</p></li>
+<li><p><code>-4</code>, <code>--ipv4-only</code>:
+Only accept IPv4 connections</p></li>
+<li><p><code>-6</code>, <code>--ipv6-only</code>:
+Only accept IPv6 connections</p></li>
+<li><p><code>-h</code>, <code>--help</code>:
+Print a help menu</p></li>
+<li><p><code>--version</code>:
+Print program version</p></li>
+<li><p><code>-v</code>, <code>--verbose</code>:
+More verbose logging and output</p></li>
+<li><p><code>--syslog</code>:
+Enables logging via <span class="man-ref">syslog<span class="s">(2)</span></span> (for WARN and above).</p></li>
+<li><p><code>-m</code>, <code>--manual</code>:
+Enable manual (explicit) acknowledge mode, in which each child program must
+connect to the master's control socket and "ACK" within a graceperiod, or it
+will be considered unhealthy and get restarted.</p></li>
+<li><p><code>--drop-env-var</code> <var>VAR</var>:
+Clears the given variable from the child's environment. All other variables
+are passed through by default. This argument can be repeated.</p></li>
+<li><p><code>-d</code>, <code>--socket-path</code> <var>PATH</var>:
+Where to create the control socket (default: <code>/tmp/einhorn.sock</code>).</p></li>
+<li><p><code>-r</code>, <code>--retries</code> <var>COUNT</var>
+How many times to attempt re-spawning before giving up.</p></li>
 </ul>
 
 
+<h2 id="CHILD-API">CHILD API</h2>
+
+<p><code>Einhyrningsins</code> creates children by <span class="man-ref">fork<span class="s">(1)</span></span>-ing a new process and
+<span class="man-ref">execve<span class="s">(1)</span></span>-ing to run the proces itself. For every socket specified by a <code>-b</code>
+flag, a socket is bound in the main <code>einhyrningsins</code> process and then
+explicitly flagged to be passed on to the child processes. This means the child
+process will already have a valid file descriptor bound to each of the shared
+sockets. The file descriptor numbers are passed via the following environment
+variables:</p>
+
+<dl>
+<dt><code>EINHORN_FD_COUNT</code></dt><dd>How many sockets have been passed.</dd>
+<dt><code>EINHORN_FD_&lt;NUM></code></dt><dd>One evironment for each socket with <var>NUM</var> from 0 to <code>EINHORN_FD_COUNT-1</code>.</dd>
+</dl>
+
+
+<p>When <code>einhyrningsins</code> is run in manual mode, each child process should connect
+to the control socket (at the UNIX path given by the <code>EINHORN_SOCK_PATH</code>
+variable) and <span class="man-ref">write<span class="s">(2)</span></span> a newline-terminated string like the following,
+containing the child's PID number:</p>
+
+<p>  <code>{"command":"worker:ack", "pid":&lt;PID>}</code></p>
+
+<h2 id="HISTORY">HISTORY</h2>
+
+<p><code>Einhyrningsins</code> is a partially-comparible re-implementation of <a class="man-ref" href="https://github.com/stripe/einhorn">einhorn<span class="s">(1)</span></a> (a
+Ruby program) in Rust. Einhorn itself derived from Unicorn.</p>
+
+<p>The word "Einhyrningsins" is Icelandic for unicorn.</p>
+
 <h2 id="STATUS">STATUS</h2>
 
-<p>This is a fun fun hobby project. Still in progress, and notably untested.</p>
+<p><code>Einhyrningsins</code> is a for-fun hobby project. It is not feature complete, fully
+documented, or tested.</p>
 
 <h2 id="COPYRIGHT">COPYRIGHT</h2>
 
@@ -127,7 +176,7 @@ WARRANTY, to the extent permitted by law.</p>
 
 <h2 id="SEE-ALSO">SEE ALSO</h2>
 
-<p><code>einhorn (1)</code>, <code>einhyrningsinsctl(1)</code></p>
+<p><a class="man-ref" href="https://github.com/stripe/einhorn">einhorn<span class="s">(1)</span></a>, <a class="man-ref" href="einhyrningsinsctl.1.html">einhyrningsinsctl<span class="s">(1)</span></a>, <span class="man-ref">socket<span class="s">(7)</span></span></p>
 
 
   <ol class='man-decor man-foot man foot'>