TLS passthrough
ngstone portends TLS at the edge with the edge's wildcard certificate, then forwards plain HTTP to your app. ngstone tlsdoes the opposite: the edge never decrypts traffic for a passthrough connection. It reads only the hostname the client asked for, then hands the encrypted connection to your local service, which runs the TLS handshake with its own certificate. An HTTPS request that reaches the edge's own TLS for that hostname (for example on a reused or domain-fronted connection) gets 421 and is never forwarded.
When to use it#
- The service needs mutual TLS and must see the client certificate.
- Clients pin your certificate, or you need a specific CA or EV certificate.
- The protocol inside TLS isn't HTTP (IMAPS, LDAPS, a custom TLS protocol).
- The edge must never see the plaintext.
Basic usage#
$ ngstone tls 8443 --subdomain securetls://secure.example.com -> 127.0.0.1:8443Clients connect to the edge on port 443 as usual:
$ openssl s_client -connect secure.example.com:443 -servername secure.example.com$ curl https://secure.example.com/The positional argument is a bare port, forwarded to 127.0.0.1:<port>, or a host:port target used as-is. Without --subdomain the edge picks a random name.
--ttl 2h.--server, --transport, --token, --insecure, --server-name, and --pin work as they do for ngstone tcp.
How routing works#
Every connection to the edge's public port starts with a peek at the TLS ClientHello. The peek is limited to 16 KiB and to the edge's read-header timeout, and it doesn't consume the bytes. A ClientHello larger than that is closed. If the SNI hostname belongs to a tls tunnel, the edge opens a stream to your agent, replays the ClientHello, and copies bytes both ways. The agent dials your local service and does the same.
Anything else (another hostname, no SNI, or a connection that isn't TLS) continues to the normal TLS-terminating path exactly as before. HTTP tunnels and the agent's WebSocket control fallback share port 443 with passthrough tunnels.
Certificates#
Your service needs a certificate for the public hostname
secure.example.com, not localhost. The edge's wildcard certificate is never used for a tls tunnel, so the local service must present a certificate for the tunnel hostname that your clients trust.What applies and what doesn't#
Because the edge can't read the HTTP inside, it rejects --basic-auth, --host-header, --policy-file, --http2, and --multi-connector for tls tunnels. The request inspector shows no requests for them. Source-IP allowlists, per-IP rate and in-flight limits, PROXY protocol client addresses, and the TCP idle timeout all apply.
Project files#
In ngstone.json for ngstone up:
{ "tunnels": { "secure": { "kind": "tls", "target": "8443", "subdomain": "secure", "allow_cidr": "203.0.113.0/24" } }}In ngstone.yml for ngstone start:
tunnels: secure: kind: tls port: 8443 subdomain: securengstone ps, JSON status output, and the inspector's tunnel list show the kind as tls.
Hostname conflicts#
A hostname is either an HTTP tunnel or a tls tunnel at a time. Binding one over a live tunnel of the other kind fails with kind_conflict, and the agent stops instead of retrying. Stop the other tunnel or choose another subdomain.