From c21c3b0befeb46a51b6bf3758ffa30813bea0ff0 Mon Sep 17 00:00:00 2001
From: Daniel Baumann
+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. +
+ + +$ctx->{directive}->( + name => "proxy.reverse.url", + levels => [ qw(path) ], + desc => q{Forwards the requests to the specified URL, and proxies the response.}, +)->(sub { +?> += $ctx->{example}->(q{Forwarding the requests to application server running on127.0.0.1:8080
}, <<'EOT')
+proxy.reverse.url: "http://127.0.0.1:8080/"
+EOT
+?>
++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
).
+
ON
or OFF
) designating whether or not to pass Host
header from incoming request to upstream.},
+)->(sub {});
+?>
+
+
+$ctx->{directive}->(
+ name => "proxy.preserve-x-forwarded-proto",
+ levels => [ qw(global) ],
+ since => "2.0",
+ default => q{proxy.preserve-x-forwarded-proto: OFF},
+ desc => "A boolean flag(ON
or OFF
) indicating if the server preserve the received x-forwarded-proto
request header.",
+)->(sub {
+?>
+
+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.
+
proxy.timeout.keepalive
+EOT
+ default => q{proxy.proxy-protocol: OFF},
+ desc => q{A boolean flag (ON
or OFF
) indicating if PROXY protocol should be used when connecting to the application server.},
+)->(sub {
+?>
+
+When using the PROXY protocol, connections to the application server cannot be persistent (i.e. proxy.timeout.keepalive
must be set to zero).
+
ON
or OFF
) indicating if the server will append or add the x-forwarded-proto
and x-forwarded-for
request headers.",
+ see_also => render_mt(<<'EOT'),
+proxy.emit-via-header
+EOT
+)->(sub {
+?>
+
+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.
+
ON
or OFF
) indicating if the server adds or appends an entry to the via
request header.",
+ see_also => render_mt(<<'EOT'),
+proxy.emit-x-forwarded-headers
+EOT
+)->(sub {})
+?>
+
+
+for my $action (qw(add append merge set setifempty unset)) {
+ $ctx->{directive}->(
+ name => "proxy.header.$action",
+ levels => [ qw(global host path extensions) ],
+ since => "2.2",
+ desc => "Modifies the request headers sent to the application server.",
+ )->(sub {
+?>
+
+The behavior is identical to header.= $action ?>
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.
+
proxy.ssl.verify-peer
+EOT
+)->(sub {
+?>
+
+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.
+
+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:
+
ON
, lifetime
and capacity
will be set to 86,400 (one day) and 4,096.
+
+? })
+
+
+$ctx->{directive}->(
+ name => "proxy.ssl.verify-peer",
+ levels => [ qw(global host path extension) ],
+ since => "2.0",
+ desc => "A boolean flag (ON
or OFF
) indicating if the server certificate and hostname should be verified.",
+ default => q{proxy.ssl.verify-peer: ON},
+ see_also => render_mt(<<'EOT'),
+proxy.ssl.cafile
+EOT
+)->(sub {
+?>
+
+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.
+
+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. +
+? }) + + +$ctx->{directive}->( + name => "proxy.websocket", + levels => [ qw(global host path extension) ], + default => q{proxy.websocket: OFF}, + desc => q{A boolean flag (ON
or OFF
) indicating whether or not to allow upgrading the proxied connection to the WebSocket protocol.},
+)->(sub {
+?>
+
+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. +
+? }) + + +$ctx->{directive}->( + name => "proxy.websocket.timeout", + levels => [ qw(global host path extension) ], + default => q{proxy.websocket.timeout: 300000}, + desc => q{Sets idle timeout of a WebSocket connection being proxied.}, +)->(sub {}) +?> + +? }) -- cgit v1.2.3