Configure > Proxy Directives
Proxy module is the reverse proxy implementation for H2O - it implements a HTTP client that forwards a HTTP request to an upstream server.
When forwarding the requests, the module sets following request headers:
The HTTP client only supports HTTP/1. Support for HTTPS has been introduced in version 2.0.
Following sections describe the configuration directives defined for the module.
- Description:
-
Forwards the requests to the specified URL, and proxies the response.
Example. Forwarding the requests to application server running on127.0.0.1:8080
proxy.reverse.url: "http://127.0.0.1:8080/"
If you want load balancing multiple backends, replace 127.0.0.1 with hostname witch returns IP addresses via DNS or /etc/hosts.
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
unix:
(e.g.http://[unix:/path/to/socket]/path
). - Level:
- path
- Description:
-
A boolean flag (
ON
orOFF
) designating whether or not to passHost
header from incoming request to upstream. - Level:
- global, host, path
- Default:
proxy.preserve-host: OFF
"proxy.preserve-x-forwarded-proto"
- Description:
-
A boolean flag(
ON
orOFF
) indicating if the server preserve the receivedx-forwarded-proto
request header.By default, when transmitting a HTTP request to an upstream HTTP server, H2O removes the received
x-forwarded-proto
request header and sends its own, as a precautios 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. - Level:
- global
- Default:
proxy.preserve-x-forwarded-proto: OFF
"proxy.ssl.cafile"
- Description:
-
Specifies the file storing the list of trusted root certificates.
By default, H2O uses
share/h2o/ca-bundle.crt
. The file contains a set of trusted root certificates maintained by Mozilla, downloaded and converted using mk-ca-bundle.pl. - Level:
- global, host, path
- See also:
proxy.ssl.verify-peer
"proxy.ssl.verify-peer"
- Description:
-
A boolean flag (
ON
orOFF
) indicating if the server certificate and hostname should be verified.If set to
ON
, 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. - Level:
- global, host, path
- Default:
proxy.ssl.verify-peer: ON
- See also:
proxy.ssl.cafile
- Description:
-
Sets the upstream I/O timeout in milliseconds.
- Level:
- global, host, path
- Default:
proxy.timeout.io: 30000
- Description:
-
Sets the upstream timeout for idle connections in milliseconds.
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.
- Level:
- global, host, path
- Default:
proxy.timeout.keepalive: 2000
- Description:
-
A boolean flag (
ON
orOFF
) indicating whether or not to allow upgrading the proxied connection to the WebSocket protocol.When set to
ON
, 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 with101
status code).Support for WebSocket is considered experimental for the time being and therefore is not yet turned on by default.
- Level:
- global, host, path
- Default:
proxy.websocket: OFF
- Description:
-
Sets idle timeout of a WebSocket connection being proxied.
- Level:
- global, host, path
- Default:
proxy.websocket.timeout: 300000