HTTP endpoint

HTTP endpoint is a listening point where the Tunnelize server listens for incoming HTTP requests. It allows clients to tunnel local HTTP traffic through the Tunnelize server.

Tunnels configured to forward HTTP traffic first connect to the server where they get assigned a domain to where a client can connect to through a browser to access the local HTTP server.

The endpoint speaks HTTP/1.1 and, when encryption is enabled, HTTP/2. For every request the server uses the Host header (or the :authority of an HTTP/2 request) to decide which tunnel it belongs to, then forwards the request to the tunnel over a link and streams the response back.

Links are pooled: an idle link is kept open (for up to 90 seconds) and reused for the next request to the same tunnel, so your local server sees keep-alive connections as usual. With HTTP/2 a browser sends all of its requests over a single connection and the server fans them out over as many links as needed, so pages with many resources are not limited by the browser's six-connections-per-host rule that applies to HTTP/1.1. The number of links open at the same time is capped by the server's max_clients; requests beyond that wait for a link to free up.

WebSocket connections (and other Upgrade requests) are proxied as well. Every forwarded request carries X-Forwarded-For and X-Forwarded-Proto headers.

Configuring endpoint

Default HTTP endpoint configuration looks like this:

{
    "server":{
        // ...other fields
        "endpoints":{
            "http-endpoint": {
                "type": "http",
                "port": 3457,
                "hostname_template": "tunnel-{name}.localhost"
            }
        }
    }
    
}

Fields:

Note: The server-level max_clients setting caps how many tunnel links an HTTP endpoint keeps open at the same time. See server configuration for details.

Configuring templates

For HTTP endpoints you can set templates to define how an URL will will be generated for a tunnel. There are two templates you can set:

{
    // ...other fields
    "hostname_template": "tunnel-{name}.localhost",
    "full_url_template": "http://{hostname}:{port}",
}

Setting hostname_template is required and that template will let HTTP endpoint generate a random name for the tunnel in the {name} part or use a custom name if allow_custom_hostnames is set.

When using allow_custom_hostnames name defined, desired_name defined in the tunnel proxy configuration for HTTP tunnel will be used unless it is already taken. If its already taken, a similar name will be autogenerated.

Setting full_url_template is useful if you are using tunnelize server behind something like an nginx or Apache, where the HTTP endpoint port is not the same for client as it is the same for nginx or Apache. This will allow you to set the template you wish server to return to the tunnel after registration. Parameter {hostname} will be replaced by name generated by hostname_template and {port} with the port in HTTP endpoint (or you can omit this or set your own port if needed).

Configuring authorization

If you do not wish everyone to see your local tunnel while it is running, you can set an authorization where user needs to enter an username and password in the browser to access your tunnel.

Set this configuration for that:

{
    "require_authorization": {
        "realm": "exampleRealm",
        "username": "user123",
        "password": "pass123",
    }
}

Here is the breakdown of the parameters:

Working with existing HTTP server

If you are using a http server like Apache or nginx it is possible to make tunnelize work with it. See links below for your http server:

• Working with nginx
• Working with Apache