# 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:

- via
- x-forwarded-for
- x-forwarded-proto

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.

### `"proxy.reverse.url"`

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

### `"proxy.preserve-host"`

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

  `

since v2.0

### `"proxy.preserve-x-forwarded-proto"`

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

  `

since v2.1

### `"proxy.proxy-protocol"`

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`

since v2.1

### `"proxy.emit-x-forwarded-headers"`

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`

since v2.2

### `"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

since v2.2

### `"proxy.header.append"`

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

since v2.2

### `"proxy.header.merge"`

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

since v2.2

### `"proxy.header.setifempty"`

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

since v2.2

### `"proxy.header.unset"`

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`

since v2.1

### `"proxy.ssl.session-cache"`

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

  `

since v2.0

### `"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, extension
Default:
  `

      proxy.ssl.verify-peer: ON

  `
See also:
  `proxy.ssl.cafile`

### `"proxy.timeout.io"`

Description:

  Sets the upstream I/O timeout in milliseconds.

Level:
  global, host, path, extension
Default:
  `

      proxy.timeout.io: 30000

  `

### `"proxy.timeout.keepalive"`

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

  `

### `"proxy.websocket"`

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

  `

### `"proxy.websocket.timeout"`

Description:

  Sets idle timeout of a WebSocket connection being proxied.

Level:
  global, host, path, extension
Default:
  `

      proxy.websocket.timeout: 300000

  `