Tunnel

Added in version 1.12.0.

The Tunnel module (ngx_http_tunnel_module) handles HTTP/1.1 CONNECT requests and establishes an end-to-end virtual connection between the client and a backend server, allowing Angie to act as a forwarding proxy.

Access to the tunnel is controlled with the standard access directives: auth_basic, satisfy, and auth_delay.

Configuration Example

http {

    map $host $allow_host {
        hostnames;

        example.org    1;
        *.example.org  1;
    }

    server {
        listen 8000;

        resolver 127.0.0.53;

        if ($allow_host != 1) {
            return 502;
        }

        tunnel_pass;
    }
}

Directives

tunnel_bind

Syntax	tunnel_bind address [transparent] | off;
Default	—
Context	http, server, location

Makes outgoing connections to a backend server originate from the specified local IP address with an optional port. The parameter value can contain variables. The special value off cancels the effect of the tunnel_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

The transparent parameter allows outgoing connections to a backend server to originate from a non-local IP address, for example, from a real IP address of a client:

tunnel_bind $remote_addr transparent;

In order for this parameter to work, it is usually necessary to run Angie worker processes with the superuser privileges. On Linux it is not required as if the transparent parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process.

tunnel_buffer_size

Syntax	tunnel_buffer_size size;
Default	tunnel_buffer_size 4k|8k;
Context	http, server, location

Sets the size of the buffer used for reading data from the backend server. It also sets the size of the buffer used for reading data from the client.

tunnel_connect_timeout

Syntax	tunnel_connect_timeout time;
Default	tunnel_connect_timeout 60s;
Context	http, server, location

Defines a timeout for establishing a connection with a backend server. It should be noted that this timeout cannot usually exceed 75 seconds.

tunnel_next_upstream

Syntax	tunnel_next_upstream error | timeout | off ...;
Default	tunnel_next_upstream error timeout;
Context	http, server, location

Specifies in which cases a request should be passed to the next server:

error	an error occurred while establishing a connection with the server or reading data from it;
timeout	a timeout has occurred while establishing a connection with the server, passing a request to it, or reading data from it;
off	disables passing a request to the next server.

Passing a request to the next server is only possible if nothing has been sent to a client yet. If an error or timeout occurs in the middle of transferring a response, fixing it is impossible.

The directive also defines what is considered an unsuccessful attempt of communication with a server. The cases of error and timeout are always considered unsuccessful attempts, even if they are not specified in the directive.

Passing a request to the next server can be limited by the number of tries and by time.

tunnel_next_upstream_timeout

Syntax	tunnel_next_upstream_timeout time;
Default	tunnel_next_upstream_timeout 0;
Context	http, server, location

Limits the time during which a request can be passed to the next server. The 0 value turns off this limitation.

tunnel_next_upstream_tries

Syntax	tunnel_next_upstream_tries number;
Default	tunnel_next_upstream_tries 0;
Context	http, server, location

Limits the number of possible tries for passing a request to the next server. The 0 value turns off this limitation.

tunnel_pass

Syntax	tunnel_pass [address];
Default	—
Context	server, location, if in location

Enables handling of CONNECT requests and sets the address of a backend server. By default, the address is $host:$request_port and is taken from the client request. In most cases, tunnel_pass does not require configuring any arguments.

The address can be specified as a domain name or IP address, and a port:

tunnel_pass localhost:9000;

or as a UNIX-domain socket path:

tunnel_pass unix:/tmp/backend.socket;

If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a server group.

The parameter value can contain variables. In this case, if an address is specified as a domain name, the name is searched among the described server groups, and, if not found, is determined using a resolver.

tunnel_read_timeout

Syntax	tunnel_read_timeout time;
Default	tunnel_read_timeout 60s;
Context	http, server, location

Sets the timeout between two successive read or write operations on client or backend server connections. If no data is transmitted within this time, the connection is closed.

tunnel_send_lowat

Syntax	tunnel_send_lowat size;
Default	tunnel_send_lowat 0;
Context	http, server, location

If the directive is set to a non-zero value, Angie will try to minimize the number of send operations on outgoing connections to a backend server by using either the NOTE_LOWAT flag of the kqueue method, or the SO_SNDLOWAT socket option, with the specified size.

This directive is ignored on Linux, Solaris, and Windows.

tunnel_send_timeout

Syntax	tunnel_send_timeout time;
Default	tunnel_send_timeout 60s;
Context	http, server, location

Sets a timeout for transmitting data to the backend server. The timeout is set only between two successive write operations, not for the whole transmission. If the backend server does not receive anything within this time, the connection is closed.

tunnel_socket_keepalive

Syntax	tunnel_socket_keepalive on | off;
Default	tunnel_socket_keepalive off;
Context	http, server, location

Configures the "TCP keepalive" behavior for outgoing connections to a backend server. By default, the operating system's settings are in effect for the socket. If the directive is set to the value on, the SO_KEEPALIVE socket option is turned on for the socket.