
TLS routing is available starting from Teleport 8.0
.
In TLS routing mode Teleport proxy multiplexes all client connections on a single TLS port.
With TLS routing, cluster administrators can simplify network configurations since proxy only listens on one port. All connections are authenticated with mutual TLS and users are able to tunnel protocols that may be blocked on the network such as SSH.
To implement TLS routing, Teleport uses SNI (Server Name Indication) and ALPN (Application-Level Protocol Negotiation) TLS extensions.
TLS routing will not work in environments where layer 7 load balancers or reverse proxies are used. See further information in the When to use TLS routing section below.
When to use TLS routing
Using Teleport's TLS routing mode behind a layer 7 (HTTP/HTTPS) proxy is generally not supported, due to these proxies terminating TLS themselves and then rewriting their requests to the upstream service, stripping the additional SNI/ALPN parts of the request in the process. In order for ALPN to work correctly, the Teleport proxy must terminate TLS itself.
Broadly, this means that Teleport's TLS routing functionality is incompatible with:
- AWS ALBs (Application Load Balancers)
- AWS NLBs (Network Load Balancers), when using a TLS listener and a public ACM (Amazon Certificate Manager) certificate
- Commonly used HTTP reverse proxies including nginx, Apache, Caddy, Traefik, HAProxy and many others
- Cloudflare tunnels in their default configuration
Deploying Teleport in TLS routing mode behind an HTTP proxy will result in a Teleport Web UI experience that seems
to work perfectly, but the use of tsh
, tctl
and attempting to join remote Teleport services to the cluster will fail
with errors like ssh: overflow reading version string
and EOF
. A functioning Teleport Web UI is not always an indication
of a correctly configured Teleport cluster.
If in doubt, remove all load balancers/proxies from the equation and connect Teleport clients or agent processes directly to Teleport's web port to isolate the issue.
To use Teleport behind a reverse proxy, you should either:
- use a layer 4 (TCP) proxy which forwards TCP streams directly to Teleport (which will in turn handle TLS termination itself)
- disable Teleport's TLS routing mode by adding
version: v1
to your config file and removingproxy_listener_mode: multiplex
You can get an example v1
config file using teleport configure --version=v1 --public-addr=teleport.example.com:443
(change the public address to your own domain)
If disabling TLS routing, you can find the list of default ports to use for connecting different Teleport services at ports without TLS routing
How it works
Starting from version 8.0
Teleport proxy listens for all client connections
on its web_listen_addr
by default:
proxy_service:
web_listen_addr: "0.0.0.0:443"
All Teleport clients including SSH, web browser, kubectl, database and reverse tunnel clients establish a TLS tunnel to the proxy's web port and indicate the protocol they're requesting using SNI and ALPN TLS extensions.
Upon accepting a new connection, the proxy inspects the SNI/ALPN value in the TLS handshake and forwards the connection to appropriate backend service.
Local proxy
Clients like psql
or mysql
implement TLS handshake as a part of their
protocol-specific connection negotiation phase (aka STARTTLS).
To support these clients, as well as clients that do support TLS but don't allow
setting custom ALPN values, Teleport's tsh
client includes ability to start
a local TLS routing aware proxy.
Such clients connect to the local proxy instead of Teleport proxy directly. The local proxy establishes a TLS connection to the Teleport proxy with the proper SNI/ALPN values set and tunnels the client's connection over it.
In most cases, clients handle TLS routing transparently when establishing
connection. For example, tsh
client starts local proxy and sets appropriate
SNI/ALPN values automatically. For some clients, like native/GUI database
clients instead of tsh db connect
, the user needs to start the local proxy so
these clients can connect to it.
Diagram

Let's take a look at how each protocol Teleport supports implements TLS routing.
SSH
Teleport client tsh
, when connecting to an SSH node, first dials Teleport
proxy over TLS and requests teleport-proxy-ssh
ALPN protocol.
No local proxy is started in this case as tsh
uses this TLS connection as a
transport to establish the SSH connection.
OpenSSH
To support standard OpenSSH client, Teleport provides a tsh proxy ssh
command
which can be used as a ProxyCommand
.
Similarly to tsh ssh
, tsh proxy ssh
establishes a TLS tunnel to Teleport
proxy with teleport-proxy-ssh
ALPN protocol, which ssh
then connects over.
See the OpenSSH client guide for details on how it's configured.
Reverse tunnels
Reverse tunnel workers within the Teleport Node, Application and Database
Services, as well as for Trusted Clusters, open a TLS tunnel to the cluster's
Proxy Service with the teleport-reversetunnel
ALPN protocol. The workers then
dial SSH over the tunnel, establishing a secure connection.
Kubernetes
Kubernetes client kubectl
uses HTTPS API and TLS handshake to talk to the API
server.
As such, it is not possible to request a custom ALPN protocol using kubectl
.
Instead, Teleport leverages SNI and sets a ServerName
prefixed with kube.
when generating a kubeconfig file during tsh kube login
:
apiVersion: v1
kind: Config
clusters:
- cluster:
certificate-authority-data: ...
server: https://proxy.example.com:443
tls-server-name: kube.proxy.example.com
name: example
Databases
The tsh db connect
command executes an appropriate database client for the
database you're connecting to.
In TLS routing mode, tsh
starts a local proxy which database client connection
is tunneled through. The local proxy uses one of teleport-postgres
,
teleport-mysql
or teleport-mongodb
ALPN values depending on the database.
The proxy is shut down when the database session ends.
Native and GUI clients
For the native or graphical database clients to work with TLS routing, they must be connecting to the local proxy instead of Teleport proxy directly.
Teleport provides a tsh proxy db
command to launch a local database proxy:
tsh proxy db example-db
See GUI clients guide for a usage example.
Web UI, apps and desktops
Application access, desktop access and Teleport web UI are served by the
Teleport proxy's web listener and don't require a local proxy or any special
ALPN/SNI negotiation. These web connections use standard http1.1
and h2
protocols for ALPN.
Next steps
- See migration guide to learn how to upgrade an existing cluster to use TLS routing.
- Read through TLS routing design document RFD.