This guide provides more in-depth details for running Teleport in Production.
- Read the Architecture Overview
- Read through the Installation Guide to see the available packages and binaries available.
- Read the CLI Docs for
Before installing anything there are a few things you should think about.
- Where will you host Teleport?
- Cloud VMs such as AWS EC2 or GCE
- An existing Kubernetes Cluster
- What does your existing network configuration look like?
- Are you able to administer the network firewall rules yourself or do you need to work with a network admin?
- Are these nodes accessible to the public Internet or behind NAT?
- Which users, (Roles or ClusterRoles on k8s) are set up on the existing system?
- Can you add new users or Roles yourself or do you need to work with a system administrator?
Teleport services listen on several ports. This table shows the default port numbers.
|Proxy||HTTPS port clients connect to. Used to authenticate ||Allow inbound connections from HTTP and SSH clients.||Allow outbound connections to HTTP and SSH clients.|
|Proxy||SSH port clients connect to after authentication. A proxy will forward this connection to port ||Allow inbound traffic from SSH clients.||Allow outbound traffic to SSH clients.|
|Node||SSH port to the Node Service. This is Teleport's equivalent of port ||Allow inbound traffic from the proxy host.||Allow outbound traffic to the proxy host.|
|Auth||SSH port used by the Auth Service to serve its Auth API to other nodes in a cluster.||Allow inbound connections from all cluster nodes.||Allow outbound traffic to cluster nodes.|
|Proxy||SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server.|
|Kubernetes||Port used for |
We have a detailed installation guide which shows how to install all available binaries or install from source. Reference that guide to learn the best way to install Teleport for your system, then return to finish your production install.
The examples below may include the use of the
sudo keyword, token UUIDs, and users with
admin privileges to make following each step easier when creating resources from scratch.
- We discourage using
sudoin production environments unless it's needed.
- We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
- We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the
adminrole when giving them the more restrictive
access,editorroles will do instead.
- Saving tokens into a file rather than sharing tokens directly as strings.
Learn more about Teleport Role-Based Access Control best practices.
By default, a Teleport node has the following files present. The location of all of them is configurable.
|Teleport configuration file.|
|Teleport daemon binary.|
|Teleport admin tool. It is only needed for auth servers.|
|Teleport CLI client tool. It is needed on any node that needs to connect to the cluster.|
|Teleport data directory. Nodes keep their keys and certificates there. Auth servers store the audit log and the cluster keys there, but the audit log storage can be further configured via |
In production, we recommend starting teleport daemon via an init system like
systemd and unit files are new to you, check out this helpful guide. Here's an example systemd unit file for the Teleport Proxy, Node, and Auth Service.
There are a couple of important things to notice about this file:
- The start command in the unit file specifies
--configas a file and there are very few flags passed to the
teleportbinary. Most of the configuration for Teleport should be done in the configuration file.
- The ExecReload command allows admins to run
systemctl reload teleport. This will attempt to perform a graceful restart of Teleport but it only works if network-based backend storage like DynamoDB or etcd is configured. Graceful Restarts will fork a new process to handle new incoming requests and leave the old daemon process running until existing clients disconnect.
You can start Teleport via systemd unit by enabling the
sudo cp teleport/examples/systemd/teleport.service /etc/systemd/systemcd /etc/systemd/system
Use your text editor of choice to create the .service file
Here we use vimvi teleport.service
Use the file linked above as is or customize as needed
save the filesystemctl enable teleportsystemctl start teleport
Show the status of the unitsystemctl status teleport
Follow the tail of service logsjournalctl -fu teleport
If you modify teleport.service later you will need to
reload the systemctl daemon and reload teleport
to apply your changessystemctl daemon-reloadsystemctl reload teleport
You can also perform restarts or upgrades by sending
to a Teleport daemon manually.
|Signal||Teleport Daemon Behavior|
|Dumps diagnostics/debugging information into syslog.|
|Immediate non-graceful shutdown. All existing connections will be dropped.|
|Forks a new Teleport daemon to serve new connections.|
|Forks a new Teleport daemon to serve new connections and initiates the graceful shutdown of the existing process when there are no more clients connected to it. This is the signal sent to trigger a graceful restart.|
We've written a dedicated guide on Adding Nodes to your Cluster which shows how to generate or set join tokens and use them to add nodes.
TLS stands for Transport Layer Security (TLS), and its now-deprecated predecessor, Secure Sockets Layer (SSL). Teleport requires TLS authentication to ensure that communication between nodes, clients and web proxy remains secure and comes from a trusted source.
If you use certbot, you get this list of files provided:
README cert.pem chain.pem fullchain.pem privkey.pem
The files that are needed for Teleport are these:
# proxy service # ... https_keypairs: - key_file: /var/lib/teleport/webproxy_key.pem cert_file: /var/lib/teleport/webproxy_cert.pem
If you already have a certificate these should be uploaded to the Teleport Proxy and
can be set via
https_cert_file. Make sure any certificates
files uploaded contain a full certificate chain, complete with any intermediate
# This section configures the 'proxy service' proxy_service: # Turns 'proxy' role on. Default is 'yes' enabled: yes # The DNS names the proxy HTTPS endpoint as accessible by cluster users. # Defaults to the proxy's hostname if not specified. If running multiple # proxies behind a load balancer, this name must point to the load balancer # (see public_addr section below) public_addr: proxy.example.com:3080 # TLS certificate for the HTTPS connection. Configuring these properly is # critical for Teleport security. https_keypairs: - key_file: /var/lib/teleport/webproxy_key.pem cert_file: /var/lib/teleport/webproxy_cert.pem
When setting up on Teleport on AWS or GCP, we recommend leveraging their certificate managers.
When setting up Teleport with a Cloud Provider, it can be common to terminate TLS at the load balancer, then use an autoscaling group for the proxy nodes. When setting up the proxy nodes start Teleport with:
teleport start --insecure --roles=proxy --config=/etc/teleport.yaml
Teleport nodes use the HTTPS protocol to offer the join tokens to the auth server. In a zero-trust environment, you must assume that an attacker can hijack the IP address of the auth server.
To prevent this from happening, you need to supply every new node with an additional bit of information about the auth server. This technique is called CA pinning. It works by asking the auth server to produce a CA pin, which is a hashed value of its private key, i.e. it cannot be forged by an attacker.
To get the current CA pin run the following code on the auth server:
User CA never updated
Host CA never updated
CA pin sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1
The CA pin at the bottom needs to be passed to the new nodes when they're starting for the first time, i.e. when they join a cluster:
sudo teleport start \ --roles=node \ --token=/path/to/token.file \ --ca-pin=sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1 \ --auth-server=10.12.0.6:3025
/etc/teleport.yaml on a node:
teleport: auth_token: "1ac590d36493acdaa2387bc1c492db1a" ca_pin: "sha256:7e12c17c20d9cb504bbcb3f0236be3f446861f1396dcbb44425fe28ec1c108f1" auth_servers: - "10.12.0.6:3025"
WARNmessage (warning) into its standard error output.
tctl auth rotate.
By default, the
teleport daemon uses the local directory
store its data. This applies to any role or service including
auth node hosts the most sensitive data you will want to prevent
unauthorized access to this directory. Make sure that regular/non-admin users
do not have access to this folder, particularly on the
auth server. Change
the ownership of the directory with
sudo teleport start
If you are logged in as
root you may want to create a new OS-level user first.
On Linux, create a new user called
<username> with the following commands:
adduser <username>su <username>