Advanced Options
Advanced HTTP tunnel options and related TLS settings.
Most HTTP tunnels work well with the defaults: the engine exposes an HTTP endpoint and forwards upstream requests to a local HTTP server over http/1.1. Advanced options become relevant when the upstream service requires a specific HTTP version or when upstream TLS is required.
Upstream HTTP version
The upstream HTTP version can be set to http/1.1, h2c, or h3. When no upstream version is set and upstream TLS is disabled, the engine defaults to http/1.1.
h2c uses cleartext HTTP/2 to the upstream service. h3 uses HTTP/3 and requires the tunnel type to be set to datagram; this is the upstream version used for WebTransport tunnels.
In the CLI, the upstream version is configured with --http-version.
Examples:
rstream forward 8080 --http --http-version http/1.1
rstream forward 8080 --http --http-version h2c
rstream forward 8443 --http --http-version h3 --upstream-tlsHosted projects use http/1.1 upstream by default unless the tunnel explicitly requests another supported upstream version.
Upstream TLS
Upstream TLS enables TLS between the engine and the upstream service. This is configured with --upstream-tls.
When upstream TLS is enabled, the engine establishes a TLS connection to the upstream service and lets the HTTP client stack negotiate HTTP/1.1 or HTTP/2 over that connection. Setting an explicit upstream HTTP version together with upstream TLS is not supported except for h3, which requires upstream TLS.
The tls_alpns tunnel property is not used for HTTP tunnels. HTTP ALPN is derived from the HTTP mode: HTTPS accepts HTTP/2 and HTTP/1.1 at the edge, while HTTP/3 uses h3.
Edge authentication and challenge
HTTP tunnels expose --token-auth, --rstream-auth, and --challenge-mode. These options are described in the Authentication and Challenge Mode pages.
Tunnel policy can allow more than one published authentication method. Each incoming request still has to authenticate with one unambiguous method; requests that combine multiple authentication proofs are rejected.
Cross-origin browser access (CORS)
CORS allows browser applications on another origin to access a published HTTP tunnel. Without a CORS configuration, the upstream application's CORS behavior is preserved. A configured policy applies to upstream responses and tunnel errors, including authentication failures. Responses preserve existing Vary values and add Vary: Origin.
| Option | Meaning |
|---|---|
--cors-allow-origin <origin> | Enable CORS for an explicit HTTP(S) origin; repeat for each origin. No wildcard, path, credentials, query or fragment. |
--cors-allow-method <method> | Repeatable allowed method. Default: GET, HEAD, POST. |
--cors-allow-header <header> | Repeatable allowed request header. Default: Authorization, Content-Type. |
--cors-expose-header <header> | Repeatable response header made readable by browser scripts. Default: none beyond browser defaults. |
--cors-allow-credentials | Allow browser-managed credentials for the listed origins. Default: false. |
--cors-max-age <seconds> | Preflight cache lifetime, 0–86400 seconds. Default: 0. |
rstream forward 8080 --http --token-auth \
--cors-allow-origin https://dashboard.example \
--cors-allow-method GET --cors-allow-method PUT \
--cors-expose-header ETagEach list option replaces that list's defaults. Origins must be explicit, such as https://dashboard.example or http://localhost:3000; * and opaque null origins are rejected. Configuration is limited to 128 entries per list and 16 KiB of strings in total. Same-origin requests continue to work. Cross-origin requests outside the configured policy are rejected; requests without an Origin header still follow the existing authentication rules.
Valid browser preflights are answered without a token and cannot access the upstream application. Actual requests, including ordinary OPTIONS requests, still follow the tunnel's authentication and authorization rules. CORS does not make an authenticated tunnel public.
A browser can send a delegated tunnel token using Authorization: Bearer … with credentials: "omit"; the preflight does not need a token. The token can also be passed in the rstream.token query parameter. --cors-allow-credentials is not needed for either of these token forms with credentials: "omit". It is required when intentionally using browser-managed credentials and credentials: "include".
Related TLS options
The CLI also exposes TLS options such as --tls-min-version, --tls-ciphers, and mTLS Tunnel access. Edge TLS policy is part of the broader security model and is documented in Security Model, mTLS, and Tunnel Protocols.