diff options
| -rw-r--r-- | index.html | 101 |
1 files changed, 75 insertions, 26 deletions
@@ -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_<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":<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'> |