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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6-networking: the s6-tcpserver4 program</title>
<meta name="Description" content="s6-networking: the s6-tcpserver4 program" />
<meta name="Keywords" content="s6-networking s6-tcpserver4 tcpserver ucspi tcp server super-server ipv4" />
<!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">s6-networking</a><br />
<a href="http://skarnet.org/software/">Software</a><br />
<a href="http://skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>s6-tcpserver4</tt> program </h1>
<p>
<tt>s6-tcpserver4</tt> is a super-server for IPv4 TCP
connections. It accepts connections from clients, and forks a
program to handle each connection.
</p>
<h2> Interface </h2>
<pre>
s6-tcpserver4 [ -1 ] [ -v <em>verbosity</em> ] [ -c <em>maxconn</em> ] [ -C <em>localmaxconn</em> ] [ -b <em>backlog</em> ] [ -G <em>gidlist</em> ] [ -g <em>gid</em> ] [ -u <em>uid</em> ] [ -U ] <em>ip</em> <em>port</em> <em>prog...</em>
</pre>
<ul>
<li> s6-tcpserver4 binds to local IPv4 address <em>ip</em>,
port <em>port</em>. </li>
<li> It closes its stdin and stdout. </li>
<li> For every TCP connection to this address and port, it
forks. The child sets some environment variables, then
executes <em>prog...</em> with stdin reading from the network
socket and stdout writing to it. </li>
<li> Depending on the verbosity level, it logs what it does to stderr. </li>
<li> It runs until killed by a signal. Depending on the received
signal, it may kill its children before exiting. </li>
</ul>
<h2> Environment variables </h2>
<p>
For each connection, an instance of <em>prog...</em> is spawned with
the following variables set:
</p>
<ul>
<li> PROTO: always set to TCP </li>
<li> TCPREMOTEIP: set to the originating address </li>
<li> TCPREMOTEPORT: set to the originating port </li>
<li> TCPCONNNUM: set to the number of connections originating from
the same IP address </li>
</ul>
<h2> Options </h2>
<ul>
<li> <tt>-1</tt> : write <em>port</em> to stdout, before
closing it, right after binding and listening to the network socket.
If stdout is suitably redirected, this can be used by monitoring
programs to check when the server is ready to accept connections. </li>
<li> <tt>-v <em>verbosity</em></tt> : be more or less verbose.
By default, <em>verbosity</em> is 1: print warning messages to stderr.
0 means only print fatal error messages ; 2 means print status and
connection information for every client. </li>
<li> <tt>-c <em>maxconn</em></tt> : accept at most
<em>maxconn</em> concurrent connections. Default is 40. It is
impossible to set it higher than 1000. </li>
<li> <tt>-C <em>localmaxconn</em></tt> : accept at most
<em>localmaxconn</em> connections from the same IP address.
Default is 40. It is impossible to set it higher than <em>maxconn</em>. </li>
<li> <tt>-b <em>backlog</em></tt> : set a maximum of
<em>backlog</em> backlog connections on the socket. Extra
connection attempts will rejected by the kernel. </li>
<li> <tt>-G <em>gidlist</em></tt> : change s6-tcpserver4's
supplementary group list to <em>gidlist</em> after binding the socket.
This is only valid when run as root. <em>gidlist</em> must be a
comma-separated list of numerical group IDs. </li>
<li> <tt>-g <em>gid</em></tt> : change s6-tcpserver4's groupid
to <em>gid</em> after binding the socket. This is only valid when run
as root. </li>
<li> <tt>-u <em>uid</em></tt> : change s6-tcpserver4's userid
to <em>uid</em> after binding the socket. This is only valid when run
as root. </li>
<li> <tt>-U</tt> : change s6-tcpserver4's user id, group id and
supplementary group list
according to the values of the UID, GID and GIDLIST environment variables
after binding the socket. This is only valid when run as root.
This can be used with the
<a href="http://skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a>
program to easily script a service that binds to a privileged socket
then drops its privileges to those of a named non-root account. </li>
</ul>
<h2> Signals </h2>
<ul>
<li> SIGTERM: exit. </li>
<li> SIGHUP: send a SIGTERM and a SIGCONT to all children. </li>
<li> SIGQUIT: send a SIGTERM and a SIGCONT to all children, then exit. </li>
<li> SIGABRT: send a SIGKILL to all children, then exit. </li>
</ul>
<h2> Notes </h2>
<ul>
<li> Unlike its ancestor
<a href="http://cr.yp.to/ucspi-tcp/tcpserver.html">tcpserver</a>,
s6-tcpserver4 performs just the bare minimum: the point is to have a
very small and very fast process to serve connections with the least
possible overhead. Features such as additional environment variables,
access control and DNS resolution are provided
via the <a href="s6-tcpserver-access.html">s6-tcpserver-access</a>
program. </li>
</ul>
</body>
</html>
|
