H2O

the optimized HTTP/1.x, HTTP/2 server
Powered by Oktavia

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 on 127.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 or OFF) designating whether or not to pass Host header from incoming request to upstream.

Level:
global, host, path
Default:
proxy.preserve-host: OFF
Description:

A boolean flag(ON or OFF) indicating if the server preserve the received x-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
since v2.0

"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
Description:

A boolean flag (ON or OFF) 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 or OFF) 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 with 101 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