1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' value='text/html;charset=utf8'>
<meta name='generator' value='Ronn/v0.7.3 (http://github.com/rtomayko/ronn/tree/0.7.3)'>
<title>einhyrningsins(1) - graceful restarts for socket-based daemons</title>
<style type='text/css' media='all'>
/* style: man */
body#manpage {margin:0}
.mp {max-width:100ex;padding:0 9ex 1ex 4ex}
.mp p,.mp pre,.mp ul,.mp ol,.mp dl {margin:0 0 20px 0}
.mp h2 {margin:10px 0 0 0}
.mp > p,.mp > pre,.mp > ul,.mp > ol,.mp > dl {margin-left:8ex}
.mp h3 {margin:0 0 0 4ex}
.mp dt {margin:0;clear:left}
.mp dt.flush {float:left;width:8ex}
.mp dd {margin:0 0 0 9ex}
.mp h1,.mp h2,.mp h3,.mp h4 {clear:left}
.mp pre {margin-bottom:20px}
.mp pre+h2,.mp pre+h3 {margin-top:22px}
.mp h2+pre,.mp h3+pre {margin-top:5px}
.mp img {display:block;margin:auto}
.mp h1.man-title {display:none}
.mp,.mp code,.mp pre,.mp tt,.mp kbd,.mp samp,.mp h3,.mp h4 {font-family:monospace;font-size:14px;line-height:1.42857142857143}
.mp h2 {font-size:16px;line-height:1.25}
.mp h1 {font-size:20px;line-height:2}
.mp {text-align:justify;background:#fff}
.mp,.mp code,.mp pre,.mp pre code,.mp tt,.mp kbd,.mp samp {color:#131211}
.mp h1,.mp h2,.mp h3,.mp h4 {color:#030201}
.mp u {text-decoration:underline}
.mp code,.mp strong,.mp b {font-weight:bold;color:#131211}
.mp em,.mp var {font-style:italic;color:#232221;text-decoration:none}
.mp a,.mp a:link,.mp a:hover,.mp a code,.mp a pre,.mp a tt,.mp a kbd,.mp a samp {color:#0000ff}
.mp b.man-ref {font-weight:normal;color:#434241}
.mp pre {padding:0 4ex}
.mp pre code {font-weight:normal;color:#434241}
.mp h2+pre,h3+pre {padding-left:0}
ol.man-decor,ol.man-decor li {margin:3px 0 10px 0;padding:0;float:left;width:33%;list-style-type:none;text-transform:uppercase;color:#999;letter-spacing:1px}
ol.man-decor {width:100%}
ol.man-decor li.tl {text-align:left}
ol.man-decor li.tc {text-align:center;letter-spacing:4px}
ol.man-decor li.tr {text-align:right;float:right}
</style>
<style type='text/css' media='all'>
/* style: toc */
.man-navigation {display:block !important;position:fixed;top:0;left:113ex;height:100%;width:100%;padding:48px 0 0 0;border-left:1px solid #dbdbdb;background:#eee}
.man-navigation a,.man-navigation a:hover,.man-navigation a:link,.man-navigation a:visited {display:block;margin:0;padding:5px 2px 5px 30px;color:#999;text-decoration:none}
.man-navigation a:hover {color:#111;text-decoration:underline}
</style>
</head>
<!--
The following styles are deprecated and will be removed at some point:
div#man, div#man ol.man, div#man ol.head, div#man ol.man.
The .man-page, .man-decor, .man-head, .man-foot, .man-title, and
.man-navigation should be used instead.
-->
<body id='manpage'>
<div class='mp' id='man'>
<div class='man-navigation' style='display:none'>
<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>
</div>
<ol class='man-decor man-head man head'>
<li class='tl'>einhyrningsins(1)</li>
<li class='tc'></li>
<li class='tr'>einhyrningsins(1)</li>
</ol>
<h2 id="NAME">NAME</h2>
<p class="man-name">
<code>einhyrningsins</code> - <span class="man-whatis">graceful restarts for socket-based daemons</span>
</p>
<h2 id="SYNOPSIS">SYNOPSIS</h2>
<p><code>einhyrningsins</code> [<var>OPTIONS</var>] [--] <var>PROGRAM</var> [<var>PROGRAM_ARGS</var>]</p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
<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 (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><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><code>Einhyrningsins</code> is a for-fun hobby project. It is not feature complete, fully
documented, or tested.</p>
<h2 id="COPYRIGHT">COPYRIGHT</h2>
<p>Copyright 2016 Bryan Newbold
License GPLv3+: GNU GPL version 3 or later <a href="http://gnu.org/licenses/gpl.html" data-bare-link="true">http://gnu.org/licenses/gpl.html</a>.
This is free software: you are free to change and redistribute it. There is NO
WARRANTY, to the extent permitted by law.</p>
<h2 id="SEE-ALSO">SEE ALSO</h2>
<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'>
<li class='tl'></li>
<li class='tc'>October 2016</li>
<li class='tr'>einhyrningsins(1)</li>
</ol>
</div>
</body>
</html>
|
