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
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>s6-networking: the proxy-server program</title>
<meta name="Description" content="s6-networking: the proxy-server program" />
<meta name="Keywords" content="s6-networking proxy-server PROXY protocol pp pp2 haproxy" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">s6-networking</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>proxy-server</tt> program </h1>
<p>
<tt>proxy-server</tt> reads a line of text, or a block of binary data, following
the <a href="https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">PROXY
protocol</a>, on its stdin. It sets some environment variables to
data provided by the protocol, then executes a program.
</p>
<p>
The objective is to make servers running under the
<a href="s6-tcpserver.html">s6-tcpserver</a> superserver work behind a proxy
with client connection data provided by the proxy via the PROXY protocol.
The environment variables reflect what the s6-networking super-servers set
for a direct connection.
</p>
<h2> Interface </h2>
<pre>
proxy-server [ -1|--only-v1 | -2|--only-v2 ] [ -t <em>timeout</em> ] [ -v <em>verbosity</em> ] <em>prog...</em>
</pre>
<ul>
<li> proxy-server reads its stdin, expecting to see a block of data
following the PROXY protocol. </li>
<li> It parses the block of data to get information on the original
client connection, normally encoded in that data by a proxy. </li>
<li> If at any point it finds invalid data, it exits immediately
with an error message. </li>
<li> It puts the provided client connection information into suitable
environment variables. </li>
<li> It execs into <em>prog...</em>. </li>
</ul>
<h2> Exit codes </h2>
<dl>
<dt> 1 </dt> <dd> invalid PROXY syntax </dd>
<dt> 2 </dt> <dd> unsupported protocol </dd>
<dt> 100 </dt> <dd> wrong usage </dd>
<dt> 111 </dt> <dd> system call failed </dd>
</dl>
<p>
proxy-server never exits 0: on success, it chainloads into the next program.
</p>
<h2> Options </h2>
<dl>
<dt> -t <em>timeout</em> </dt>
<dd> If no data is received after <em>timeout</em> milliseconds, exit 111.
By default, <em>timeout</em> is 0, meaning infinite: proxy-server will wait
forever for data. </dd>
<dt> -v <em>verbosity</em> </dt>
<dd> Be more or less verbose. The default is 1. Changing it does not
have much effect at the moment, leave it alone. </dd>
<dt> -1 or --only-v1 </dt>
<dd> Disable version 2 of the PROXY protocol, only expect v1, i.e. a line of text. </dd>
<dt> -2 or --only-v2 </dt>
<dd> Disable version 1 of the PROXY protocol, only expect v2, i.e. a binary structure. </dd>
</dl>
<p>
If neither <tt>-1</tt> or <tt>-2</tt> is selected, proxy-server will default
to supporting both versions of the protocol, at a tiny speed cost.
</p>
<h2> Common usage </h2>
<p>
proxy-server is a chainloading program that you can interpose on the command
line between a super-server and a server, if the server does not follow the
PROXY protocol but you are running it behind a proxy that does.
</p>
<p>
For instance, if you are running the
<a href="//skarnet.org/software/tipidee/">tipidee</a> web server behind a proxy
transmitting real client connection information via the PROXY protocol,
instead of running <code>s6-tlsserver 0.0.0.0 443 tipideed</code>, you would run
<code>s6-tlsserver 0.0.0.0 443 proxy-server tipideed</code>, and
<a href="//skarnet.org/software/tipidee/tipideed.html">tipideed</a> would log
the IPs from the clients rather than from the proxy.
</p>
<p>
proxy-server has no utility if you are not running a server behind a proxy.
</p>
<h2> Environment variables </h2>
<p>
proxy-server sets client information into environment variables the same
way that <a href="s6-tcpserver.html">s6-tcpserver</a> and similar programs do.
It tries to map the information provided by the proxy to the same variables, as
closely as possible. It never deletes variables, it only adds or overrides
them.
</p>
<p>
Depending on the version of the protocol and the information transmitted by
the proxy, proxy-server may modify the following variables:
</p>
<ul>
<li> PROTO </li>
<li> IPCREMOTEPATH </li>
<li> IPCLOCALPATH </li>
<li> TCPREMOTEIP </li>
<li> TCPLOCALIP </li>
<li> TCPREMOTEPORT </li>
<li> TCPLOCALPORT </li>
<li> SSL_PROTOCOL </li>
<li> SSL_CIPHER </li>
<li> SSL_PEER_CERT_CN </li>
<li> SSL_TLS_SNI_SERVERNAME </li>
</ul>
<h2> Notes </h2>
<ul>
<li> proxy-server operates by writing UCSPI variables such as <tt>TCPREMOTEIP</tt>.
These variables are normally set by programs dealing with the TCP connection such as
<a href="s6-tcpserver.html">s6-tcpserver</a> or
<a href="s6-tcpserver-access.html">s6-tcpserver-access</a>. To take effect, it needs
to run <em>after</em> these programs, to override the TCP-provided values with the
proxy-provided values. </li>
<li> When used on a <a href="s6-tlsserver.html">s6-tlsserver</a>, command line,
proxy-server runs <em>after</em> the TLS connection has been established, i.e. it
expects the proxy header to be sent in the TLS tunnel. </li>
<li> If this is not the case and the proxy header is sent before the TLS connection
is established, 1. it is probably an insecure setup (if you have a good reason to
set up a TLS tunnel between your proxy and your server, then the PROXY information
is worth protecting just as much as the rest of the data), 2. proxy-server needs
to be run between <a href="s6-tcpserver.html">s6-tcpserver</a> and
<a href="s6-tlsd.html">s6-tlsd</a>, which you can do by using the -L option
to <a href="s6-tlsserver.html">s6-tlsserver</a> rather than explicitly calling
proxy-server on the command line. </li>
</ul>
</body>
</html>
|
