Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

Teleport replaces traditional SSH key management with short-lived, certificate-based access. When you enroll a Linux server by running the Teleport SSH Service, the node joins your cluster through a reverse tunnel to the Teleport Proxy Service. From that point on, every SSH connection flows through Teleport’s RBAC engine, is backed by your identity provider, and is fully recorded in the audit log — no shared keys, no password sprawl, and no open inbound ports required.

​
How the Teleport SSH Service works

The Teleport SSH Service is a drop-in replacement for sshd. Instead of maintaining a registry of authorized public keys, Teleport issues short-lived SSH certificates signed by its own certificate authority. When a user runs tsh ssh, Teleport validates the certificate, checks the user’s roles, and proxies the session through an encrypted reverse tunnel that the node opened to the Proxy Service. 
  [User / tsh]  ──►  [Proxy Service]  ──►  [SSH Service (node)]  ──►  [Audit Log]
Key properties:
  • No long-lived keys — certificates expire after a configurable TTL (default 12 hours).
  • RBAC enforcement — roles control which OS logins a user may assume and which nodes they can reach.
  • Session recording — every keystroke, command, and output can be replayed from the Web UI.
  • Reverse tunnel — nodes need no inbound firewall rules; they call out to the Proxy.

​
Prerequisites

  • A running Teleport cluster (cloud or self-hosted). See Deploy a Cluster if you don’t have one yet.
  • A Linux host (Ubuntu, Debian, Amazon Linux, CentOS, RHEL, or similar) where you will run the SSH Service.
  • tctl authenticated to your cluster with at least editor privileges.

​
Enrolling a Linux server

1

Install Teleport on the node

Connect to the Linux host and install the Teleport binary. Use the same major version as your cluster.
curl https://goteleport.com/static/install.sh | bash -s (=teleport.version=)
Verify the installation:
teleport version
2

Create a join token

On your workstation (where tctl is configured), generate a short-lived token of type node. Pipe it to a file to avoid displaying it in your shell history.
tctl tokens add --type=node --format=text > /tmp/token.file
Copy token.file to the Linux node (for example, with scp).
Join tokens are single-use and expire after 30 minutes by default. Generate a new one if enrollment takes longer.
3

Generate the Teleport configuration

On the Linux node, use teleport node configure to produce a ready-to-use teleport.yaml. Replace the --proxy flag with your cluster’s address.
sudo teleport node configure \
  --output=file:///etc/teleport.yaml \
  --token=/path/to/token.file \
  --proxy=mytenant.teleport.sh:443
The resulting /etc/teleport.yaml enables only the SSH Service and disables all other services:
version: v3
teleport:
  proxy_server: teleport.example.com:443
  auth_token: /path/to/token.file

ssh_service:
  enabled: true
  # Optional: label the node for RBAC targeting
  labels:
    env: production
    team: platform

auth_service:
  enabled: false
proxy_service:
  enabled: false
4

Start the Teleport SSH Service

Enable and start Teleport via systemd so it restarts automatically on reboot:
sudo systemctl enable teleport
sudo systemctl start teleport
Check that the service is healthy:
sudo systemctl status teleport
The node will appear in the Teleport Web UI under Resources within a few seconds.
5

SSH into the enrolled node

From your workstation, log in to Teleport and then SSH into the node.
# Authenticate to your cluster
tsh login --proxy=mytenant.teleport.sh --user=alice

# List enrolled nodes
tsh ls

# Connect to the node using a permitted OS login
tsh ssh ubuntu@ip-172-31-41-144
You can also filter nodes by label:
tsh ls env=production
tsh ssh root@env=production

​
Session recording

Every tsh ssh session is recorded by the Proxy Service (or the node itself in enhanced mode) and stored in the Teleport audit log. To replay a session:
  1. Open the Teleport Web UI.
  2. Navigate to Audit → Session Recordings.
  3. Click Play next to any recorded session.
For deeper kernel-level recording — capturing all executed commands, file modifications, and network connections — enable Enhanced Session Recording with BPF. See the BPF Session Recording guide.

​
Controlling access with RBAC

Teleport roles define which OS logins a user can request and which nodes they can access via label selectors. Here is a minimal role that allows a user to SSH as ubuntu on nodes tagged env: production: 
kind: role
version: v7
metadata:
  name: prod-ssh-access
spec:
  allow:
    logins:
      - ubuntu
    node_labels:
      env: production
  deny: {}
Apply the role: 
tctl create -f prod-ssh-access.yaml
A user must have at least one allowed login that exists on the target node. Roles are additive for allow rules and subtractive for deny rules across multiple assigned roles.

​
Hardening the node

Once the SSH Service is enrolled and tested, you can close port 22 on your firewall. All SSH traffic will flow through the Teleport Proxy tunnel and you no longer need a direct inbound SSH path. 
# Example: block port 22 with ufw
sudo ufw deny 22/tcp
sudo ufw reload

​
Next steps

Access Controls & RBAC

Restrict which users can SSH into which nodes using labels and role templates.

Single Sign-On

Connect Teleport to Okta, GitHub, or any SAML/OIDC provider for SSO-backed SSH.

MFA for SSH

Require per-session MFA touches before a terminal opens.

tsh Reference

Complete reference for tsh ssh, tsh ls, and all other tsh subcommands.

Build docs developers (and LLMs) love

Get started for freeTalk to us