http-tunnel #
The upstream nginx **Tunnel HTTP module** (`ngx_http_tunnel_module`, new in nginx mainline 1.31.2), which Angie inherits verbatim. It proxies `CONNECT`-style TCP tunnels through the HTTP layer: a request that reaches a `tunnel_pass` location has its body relayed byte-for-byte to an upstream, giving you a forward/reverse TCP tunnel with full nginx upstream semantics (load balancing, `tunnel_next_upstream` failover, per-tunnel timeouts). This is a **core built-in module**, compiled in by default (`--with-http_tunnel_module`, no `--without-` in our build) — there is no separate `libnginx-mod-*` / `angie-module-*` package to install; it ships inside the `nginx` and `angie` binaries already. Our nginx build additionally carries two directives Angie's current snapshot lacks: `tunnel_socket_rcvbuf` and `tunnel_socket_sndbuf`.
Source: upstream source
Directives
tunnel_pass #
syntax: tunnel_pass [address]; · default: — · context: server, location, if in location
Sets the upstream the tunnel connects to. With no argument the destination is taken from the request; with an address (name, IP:port, or upstream block) it is fixed. This directive is what turns a location into a CONNECT tunnel endpoint.
tunnel_bind #
syntax: tunnel_bind address [transparent] | off; · context: http, server, location
Makes the outgoing tunnel connection originate from the given local address; transparent allows binding to a non-local IP.
tunnel_socket_keepalive #
syntax: tunnel_socket_keepalive on | off; · default: tunnel_socket_keepalive off · context: http, server, location
Enables SO_KEEPALIVE on the outgoing tunnel socket.
tunnel_connect_timeout #
syntax: tunnel_connect_timeout time; · default: tunnel_connect_timeout 60s · context: http, server, location
Timeout for establishing the connection to the upstream.
tunnel_send_timeout #
syntax: tunnel_send_timeout time; · default: tunnel_send_timeout 60s · context: http, server, location
Timeout between two successive write operations to the upstream; the connection is closed if the upstream does not accept data within this time.
tunnel_send_lowat #
syntax: tunnel_send_lowat size; · default: tunnel_send_lowat 0 · context: http, server, location
Sets the SO_SNDLOWAT socket option on the tunnel connection (FreeBSD/kqueue only). 0 disables it.
tunnel_buffer_size #
syntax: tunnel_buffer_size size; · default: tunnel_buffer_size 4k|8k (one page) · context: http, server, location
Size of the buffer used to relay data in each direction of the tunnel. Defaults to one memory page.
tunnel_read_timeout #
syntax: tunnel_read_timeout time; · default: tunnel_read_timeout 60s · context: http, server, location
Timeout between two successive read operations from the upstream. Idle tunnels are torn down after this interval.
tunnel_next_upstream #
syntax: tunnel_next_upstream error | timeout | off ...; · default: tunnel_next_upstream error timeout · context: http, server, location
Specifies which failure conditions cause the request to be retried against the next upstream server; off disables retrying.
tunnel_next_upstream_tries #
syntax: tunnel_next_upstream_tries number; · default: tunnel_next_upstream_tries 0 · context: http, server, location
Caps the number of upstream servers tried per tunnel. 0 means no limit.
tunnel_next_upstream_timeout #
syntax: tunnel_next_upstream_timeout time; · default: tunnel_next_upstream_timeout 0 · context: http, server, location
Caps the total time spent trying upstream servers per tunnel. 0 means no limit.
tunnel_socket_rcvbuf #
syntax: tunnel_socket_rcvbuf size; · default: tunnel_socket_rcvbuf 0 · context: http, server, location
Sets the SO_RCVBUF socket option (receive buffer) on the tunnel connection. nginx-only; not present in Angie's current snapshot. 0 leaves the kernel default.
tunnel_socket_sndbuf #
syntax: tunnel_socket_sndbuf size; · default: tunnel_socket_sndbuf 0 · context: http, server, location
Sets the SO_SNDBUF socket option (send buffer) on the tunnel connection. nginx-only; not present in Angie's current snapshot. 0 leaves the kernel default.
Example
upstream tunnel_backend {
server 10.0.0.10:9000;
server 10.0.0.11:9000 backup;
}
server {
listen 8443;
location / {
tunnel_pass tunnel_backend;
tunnel_connect_timeout 5s;
tunnel_read_timeout 1h;
tunnel_next_upstream error timeout;
}
}