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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" />
<base href="../" />
<!-- oktavia -->
<link rel="stylesheet" href="assets/searchstyle.css" type="text/css" />
<script src="search/jquery-1.9.1.min.js"></script>
<script src="search/oktavia-jquery-ui.js"></script>
<script src="search/oktavia-english-search.js"></script>
<!-- /oktavia -->
<link rel="stylesheet" href="assets/style.css" type="text/css" />
<title>Proxy Directives - Configure - H2O - the optimized HTTP/2 server</title>
</head>
<body>
<div id="body">
<div id="top">
<h1>
<a href="index.html">H2O</a>
</h1>
<p class="description">the optimized HTTP/1.x, HTTP/2 server</p>
<!-- oktavia -->
<form id="searchform">
<input class="search" type="search" name="search" id="search" results="5" value="" placeholder="Search" />
<div id="searchresult_box">
<div id="close_search_box">×</div>
<div id="searchresult_summary"></div>
<div id="searchresult"></div>
<div id="searchresult_nav"></div>
<span class="pr">Powered by <a href="https://github.com/shibukawa/oktavia">Oktavia</a></span>
</div>
</form>
<!-- /oktavia -->
</div>
<table id="menu">
<tr>
<td><a href="index.html">Top</a></td>
<td><a href="install.html">Install</a></td>
<td class="selected">Configure</td>
<td><a href="faq.html">FAQ</a></td>
<td><a href="http://blog.kazuhooku.com/search/label/H2O" target="_blank">Blog</a></td>
<td><a href="http://github.com/h2o/h2o/" target="_blank">Source</a></td>
</tr>
</table>
<div id="main">
<h2>
<a href="configure.html">Configure</a> >
Proxy Directives
</h2>
<p>
Proxy module is the reverse proxy implementation for H2O - it implements a HTTP client that forwards a HTTP request to an upstream server.
</p>
<p>
When forwarding the requests, the module sets following request headers:
<ul>
<li><a href="https://tools.ietf.org/html/rfc7230#section-5.7.1">via</a></li>
<li><a href="http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/x-forwarded-headers.html#x-forwarded-for">x-forwarded-for</a></li>
<li><a href="http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/x-forwarded-headers.html#x-forwarded-proto">x-forwarded-proto</a></li>
</ul>
</p>
<p>
The HTTP client only supports HTTP/1.
Support for HTTPS has been introduced in version 2.0.
</p>
<p>
Following sections describe the configuration directives defined for the module.
</p>
<div id="proxy.reverse.url" class="directive-head">
<h3><a href="configure/proxy_directives.html#proxy.reverse.url"><code>"proxy.reverse.url"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Forwards the requests to the specified URL, and proxies the response.
</p>
<div class="example">
<div class="caption">Example. Forwarding the requests to application server running on <code>127.0.0.1:8080</code></div>
<pre><code>proxy.reverse.url: "http://127.0.0.1:8080/"
</code></pre>
</div>
<p>
If you want load balancing multiple backends, replace 127.0.0.1 with hostname which returns IP addresses via DNS or /etc/hosts.
</p>
<p>
In addition to TCP/IP over IPv4 and IPv6, the proxy handler can also connect to an HTTP server listening to a Unix socket.
Path to the unix socket should be surrounded by square brackets, and prefixed with <code>unix:</code> (e.g. <code>http://[unix:/path/to/socket]/path</code>).
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>path</dd>
</dl>
<div id="proxy.preserve-host" class="directive-head">
<h3><a href="configure/proxy_directives.html#proxy.preserve-host"><code>"proxy.preserve-host"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag (<code>ON</code> or <code>OFF</code>) designating whether or not to pass <code>Host</code> header from incoming request to upstream.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.preserve-host: OFF</pre></code>
</dl>
<div id="proxy.preserve-x-forwarded-proto" class="directive-head">
<div class="directive-since">since v2.0</div>
<h3><a href="configure/proxy_directives.html#proxy.preserve-x-forwarded-proto"><code>"proxy.preserve-x-forwarded-proto"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag(<code>ON</code> or <code>OFF</code>) indicating if the server preserve the received <code>x-forwarded-proto</code> request header.
</p>
<p>
By default, when transmitting a HTTP request to an upstream HTTP server, H2O removes the received <code>x-forwarded-proto</code> request header and sends its own, as a precaution measure to prevent an attacker connecting through HTTP to lie that they are connected via HTTPS.
However in case H2O is run behind a trusted HTTPS proxy, such protection might not be desirable, and this configuration directive can be used to modify the behaviour.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.preserve-x-forwarded-proto: OFF</pre></code>
</dl>
<div id="proxy.proxy-protocol" class="directive-head">
<div class="directive-since">since v2.1</div>
<h3><a href="configure/proxy_directives.html#proxy.proxy-protocol"><code>"proxy.proxy-protocol"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if <a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt" target="_blank">PROXY protocol</a> should be used when connecting to the application server.
</p>
<p>
When using the PROXY protocol, connections to the application server cannot be persistent (i.e. <a href="configure/proxy_directives.html#proxy.timeout.keepalive"><code>proxy.timeout.keepalive</code></a> must be set to zero).
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.proxy-protocol: OFF</pre></code>
<dt>See also:</dt>
<dd><a href="configure/proxy_directives.html#proxy.timeout.keepalive"><code>proxy.timeout.keepalive</code></a>
</dd>
</dl>
<div id="proxy.emit-x-forwarded-headers" class="directive-head">
<div class="directive-since">since v2.1</div>
<h3><a href="configure/proxy_directives.html#proxy.emit-x-forwarded-headers"><code>"proxy.emit-x-forwarded-headers"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag(<code>ON</code> or <code>OFF</code>) indicating if the server will append or add the <code>x-forwarded-proto</code> and <code>x-forwarded-for</code> request headers.
</p>
<p>
By default, when forwarding an HTTP request H2O sends its own <code>x-forwarded-proto</code> and <code>x-forwarded-for</code> request headers (or might append its value in the <code>x-forwarded-proto</code> case, see <code>proxy.preserve-x-forwarded-proto</code>). This might not be always desirable. Please keep in mind security implications when setting this of <code>OFF</code>, since it might allow an attacker to spoof the originator or the protocol of a request.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.emit-x-forwarded-headers: ON</pre></code>
<dt>See also:</dt>
<dd><a href="configure/proxy_directives.html#proxy.emit-via-header"><code>proxy.emit-via-header</code></a>
</dd>
</dl>
<div id="proxy.emit-via-header" class="directive-head">
<div class="directive-since">since v2.2</div>
<h3><a href="configure/proxy_directives.html#proxy.emit-via-header"><code>"proxy.emit-via-header"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if the server adds or appends an entry to the <code>via</code> request header.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.emit-via-header: ON</pre></code>
<dt>See also:</dt>
<dd><a href="configure/proxy_directives.html#proxy.emit-x-forwarded-headers"><code>proxy.emit-x-forwarded-headers</code></a>
</dd>
</dl>
<div id="proxy.header.add" class="directive-head">
<div class="directive-since">since v2.2</div>
<h3><a href="configure/proxy_directives.html#proxy.header.add"><code>"proxy.header.add"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Modifies the request headers sent to the application server.
</p>
<p>
The behavior is identical to <a href="configure/headers_directives.html#header.add"><code>header.add</code></a> except for the fact that it affects the request sent to the application server.
Please refer to the documentation of the <a href="configure/headers_directives.html">headers handler</a> to see how the directives can be used to mangle the headers.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extensions</dd>
</dl>
<div id="proxy.header.append" class="directive-head">
<div class="directive-since">since v2.2</div>
<h3><a href="configure/proxy_directives.html#proxy.header.append"><code>"proxy.header.append"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Modifies the request headers sent to the application server.
</p>
<p>
The behavior is identical to <a href="configure/headers_directives.html#header.append"><code>header.append</code></a> except for the fact that it affects the request sent to the application server.
Please refer to the documentation of the <a href="configure/headers_directives.html">headers handler</a> to see how the directives can be used to mangle the headers.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extensions</dd>
</dl>
<div id="proxy.header.merge" class="directive-head">
<div class="directive-since">since v2.2</div>
<h3><a href="configure/proxy_directives.html#proxy.header.merge"><code>"proxy.header.merge"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Modifies the request headers sent to the application server.
</p>
<p>
The behavior is identical to <a href="configure/headers_directives.html#header.merge"><code>header.merge</code></a> except for the fact that it affects the request sent to the application server.
Please refer to the documentation of the <a href="configure/headers_directives.html">headers handler</a> to see how the directives can be used to mangle the headers.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extensions</dd>
</dl>
<div id="proxy.header.set" class="directive-head">
<div class="directive-since">since v2.2</div>
<h3><a href="configure/proxy_directives.html#proxy.header.set"><code>"proxy.header.set"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Modifies the request headers sent to the application server.
</p>
<p>
The behavior is identical to <a href="configure/headers_directives.html#header.set"><code>header.set</code></a> except for the fact that it affects the request sent to the application server.
Please refer to the documentation of the <a href="configure/headers_directives.html">headers handler</a> to see how the directives can be used to mangle the headers.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extensions</dd>
</dl>
<div id="proxy.header.setifempty" class="directive-head">
<div class="directive-since">since v2.2</div>
<h3><a href="configure/proxy_directives.html#proxy.header.setifempty"><code>"proxy.header.setifempty"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Modifies the request headers sent to the application server.
</p>
<p>
The behavior is identical to <a href="configure/headers_directives.html#header.setifempty"><code>header.setifempty</code></a> except for the fact that it affects the request sent to the application server.
Please refer to the documentation of the <a href="configure/headers_directives.html">headers handler</a> to see how the directives can be used to mangle the headers.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extensions</dd>
</dl>
<div id="proxy.header.unset" class="directive-head">
<div class="directive-since">since v2.2</div>
<h3><a href="configure/proxy_directives.html#proxy.header.unset"><code>"proxy.header.unset"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Modifies the request headers sent to the application server.
</p>
<p>
The behavior is identical to <a href="configure/headers_directives.html#header.unset"><code>header.unset</code></a> except for the fact that it affects the request sent to the application server.
Please refer to the documentation of the <a href="configure/headers_directives.html">headers handler</a> to see how the directives can be used to mangle the headers.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extensions</dd>
</dl>
<div id="proxy.ssl.cafile" class="directive-head">
<div class="directive-since">since v2.0</div>
<h3><a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>"proxy.ssl.cafile"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Specifies the file storing the list of trusted root certificates.
</p>
<p>
By default, H2O uses <code>share/h2o/ca-bundle.crt</code>. The file contains a set of trusted root certificates maintained by Mozilla, downloaded and converted using <a href="https://curl.haxx.se/docs/mk-ca-bundle.html">mk-ca-bundle.pl</a>.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>See also:</dt>
<dd><a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>proxy.ssl.verify-peer</code></a>
</dd>
</dl>
<div id="proxy.ssl.session-cache" class="directive-head">
<div class="directive-since">since v2.1</div>
<h3><a href="configure/proxy_directives.html#proxy.ssl.session-cache"><code>"proxy.ssl.session-cache"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Specifies whether if and how a session cache should be used for TLS connections to the application server.
</p>
<p>
Since version 2.1, result of the TLS handshakes to the application server is memoized and later used to resume the connection, unless set to <code>OFF</code> using this directive.
If the value is a mapping, then the following two attributes must be specified:
<dl>
<dt>lifetime:</dt>
<dd>validity of session cache entries in seconds</dd>
<dt>capacity:</dt>
<dd>maxmum number of entries to be kept in the session cache</dd>
</dl>
If set to <code>ON</code>, <code>lifetime</code> and <code>capacity</code> will be set to 86,400 (one day) and 4,096.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.ssl.session-cache: ON</pre></code>
</dl>
<div id="proxy.ssl.verify-peer" class="directive-head">
<div class="directive-since">since v2.0</div>
<h3><a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>"proxy.ssl.verify-peer"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if the server certificate and hostname should be verified.
</p>
<p>
If set to <code>ON</code>, the HTTP client implementation of H2O verifies the peer's certificate using the list of trusted certificates as well as compares the hostname presented in the certificate against the connecting hostname.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.ssl.verify-peer: ON</pre></code>
<dt>See also:</dt>
<dd><a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>proxy.ssl.cafile</code></a>
</dd>
</dl>
<div id="proxy.timeout.io" class="directive-head">
<h3><a href="configure/proxy_directives.html#proxy.timeout.io"><code>"proxy.timeout.io"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Sets the upstream I/O timeout in milliseconds.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.timeout.io: 30000</pre></code>
</dl>
<div id="proxy.timeout.keepalive" class="directive-head">
<h3><a href="configure/proxy_directives.html#proxy.timeout.keepalive"><code>"proxy.timeout.keepalive"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Sets the upstream timeout for idle connections in milliseconds.
</p>
<p>
Upstream connection becomes non-persistent if the value is set to zero.
The value should be set to something smaller than that being set at the upstream server.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.timeout.keepalive: 2000</pre></code>
</dl>
<div id="proxy.websocket" class="directive-head">
<h3><a href="configure/proxy_directives.html#proxy.websocket"><code>"proxy.websocket"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
A boolean flag (<code>ON</code> or <code>OFF</code>) indicating whether or not to allow upgrading the proxied connection to <a href="https://tools.ietf.org/html/rfc6455">the WebSocket protocol</a>.
</p>
<p>
When set to <code>ON</code>, the proxied connection will be upgraded to a bi-directional tunnel stream if upgrading to WebSocket connection is permitted by the backend server (i.e. if the backend server responds to a WebSocket handshake with <code>101</code> status code).
</p>
<p>
Support for WebSocket is considered experimental for the time being and therefore is not yet turned on by default.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.websocket: OFF</pre></code>
</dl>
<div id="proxy.websocket.timeout" class="directive-head">
<h3><a href="configure/proxy_directives.html#proxy.websocket.timeout"><code>"proxy.websocket.timeout"</code></a></h3>
</div>
<dl class="directive-desc">
<dt>Description:</dt>
<dd>
<p>
Sets idle timeout of a WebSocket connection being proxied.
</p>
</dd>
<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
<dd>global, host, path, extension</dd>
<dt>Default:</dt>
<dd><code><pre>proxy.websocket.timeout: 300000</pre></code>
</dl>
</div>
<div id="footer">
<p>
Copyright © 2015 <a href="http://dena.com/intl/">DeNA Co., Ltd.</a> et al.
</p>
</div>
</body>
</html>
|
