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 which 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, extension
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 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.

Level:
global
Default:
proxy.preserve-x-forwarded-proto: OFF
Description:

A boolean flag (ON or OFF) indicating if PROXY protocol should be used when connecting to the application server.

When using the PROXY protocol, connections to the application server cannot be persistent (i.e. proxy.timeout.keepalive must be set to zero).

Level:
global, host, path, extension
Default:
proxy.proxy-protocol: OFF
See also:
proxy.timeout.keepalive
Description:

A boolean flag(ON or OFF) indicating if the server will append or add the x-forwarded-proto and x-forwarded-for request headers.

By default, when forwarding an HTTP request H2O sends its own x-forwarded-proto and x-forwarded-for request headers (or might append its value in the x-forwarded-proto case, see proxy.preserve-x-forwarded-proto). This might not be always desirable. Please keep in mind security implications when setting this of OFF, since it might allow an attacker to spoof the originator or the protocol of a request.

Level:
global
Default:
proxy.emit-x-forwarded-headers: ON
See also:
proxy.emit-via-header
Description:

A boolean flag (ON or OFF) indicating if the server adds or appends an entry to the via request header.

Level:
global
Default:
proxy.emit-via-header: ON
See also:
proxy.emit-x-forwarded-headers
since v2.2

"proxy.header.add"

Description:

Modifies the request headers sent to the application server.

The behavior is identical to header.add except for the fact that it affects the request sent to the application server. Please refer to the documentation of the headers handler to see how the directives can be used to mangle the headers.

Level:
global, host, path, extensions
Description:

Modifies the request headers sent to the application server.

The behavior is identical to header.append except for the fact that it affects the request sent to the application server. Please refer to the documentation of the headers handler to see how the directives can be used to mangle the headers.

Level:
global, host, path, extensions
Description:

Modifies the request headers sent to the application server.

The behavior is identical to header.merge except for the fact that it affects the request sent to the application server. Please refer to the documentation of the headers handler to see how the directives can be used to mangle the headers.

Level:
global, host, path, extensions
since v2.2

"proxy.header.set"

Description:

Modifies the request headers sent to the application server.

The behavior is identical to header.set except for the fact that it affects the request sent to the application server. Please refer to the documentation of the headers handler to see how the directives can be used to mangle the headers.

Level:
global, host, path, extensions
Description:

Modifies the request headers sent to the application server.

The behavior is identical to header.setifempty except for the fact that it affects the request sent to the application server. Please refer to the documentation of the headers handler to see how the directives can be used to mangle the headers.

Level:
global, host, path, extensions
Description:

Modifies the request headers sent to the application server.

The behavior is identical to header.unset except for the fact that it affects the request sent to the application server. Please refer to the documentation of the headers handler to see how the directives can be used to mangle the headers.

Level:
global, host, path, extensions
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, extension
See also:
proxy.ssl.verify-peer
Description:

Specifies whether if and how a session cache should be used for TLS connections to the application server.

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 OFF using this directive. If the value is a mapping, then the following two attributes must be specified:

lifetime:
validity of session cache entries in seconds
capacity:
maxmum number of entries to be kept in the session cache
If set to ON, lifetime and capacity will be set to 86,400 (one day) and 4,096.

Level:
global, host, path, extension
Default:
proxy.ssl.session-cache: ON
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, extension
Default:
proxy.ssl.verify-peer: ON
See also:
proxy.ssl.cafile
Description:

Sets the upstream I/O timeout in milliseconds.

Level:
global, host, path, extension
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, extension
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, extension
Default:
proxy.websocket: OFF
Description:

Sets idle timeout of a WebSocket connection being proxied.

Level:
global, host, path, extension
Default:
proxy.websocket.timeout: 300000