Fork me on GitHub
Teleport

Getting Started

This tutorial will guide you through the steps needed to install and run Teleport 6.2.7 on Linux machines.

Prerequisites

  • A Linux machine with ports 3023, 3024, 3025, and 443 open.
  • A registered domain name.
  • A two-factor authenticator app.
  • An SSH client like OpenSSH.
  • Around 20 minutes to complete; half of this may be waiting for DNS propagation.

Follow along with our video guide

Step 1/4. Install Teleport on a Linux host

Tip

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.

Generally:

  1. We discourage using sudo in production environments unless it's needed.
  2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
  3. We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the admin role when giving them the more restrictive access,editor roles will do instead.
  4. Saving tokens into a file rather than sharing tokens directly as strings.

Learn more about Teleport Role-Based Access Control best practices.

sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
sudo yum install teleport

# Optional:  Using DNF on newer distributions
# $ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
# $ sudo dnf install teleport

Take a look at the Installation Guide for more options.

Configure Teleport

Generate a configuration file for Teleport using teleport configure.

Acme turns on automatic TLS certificates from Let's Encrypt. Set up an email to receive updates from Let's Encrypt, and use a valid DNS name for a cluster name.

sudo teleport configure --acme [email protected] --cluster-name=tele.example.com -o file
Wrote config to file "/etc/teleport.yaml". Now you can start the server. Happy Teleporting!

Configure domain name and obtain TLS certificates using Let's Encrypt

Teleport requires a secure public endpoint for the Teleport UI and for end-users to connect to. To get started, set up two A records for tele.example.com and *.tele.example.com pointing to the IP/FQDN of the machine with Teleport installed.

Tip

You can use dig to make sure that DNS records are propagated:

dig @8.8.8.8 tele.example.com

Start Teleport:

sudo teleport start

You can access Teleport's Web UI on port 443.

Replace tele.example.com with your domain: https://tele.example.com/

Step 2/4. Create a Teleport user and set up two-factor authentication

In this example, we'll create a new Teleport user teleport-admin which is allowed to log into SSH hosts as any of the principals root, ubuntu or ec2-user.

# tctl is an administrative tool that is used to configure Teleport's auth service.
tctl users add teleport-admin --roles=editor,access --logins=root,ubuntu,ec2-user

Teleport will always enforce the use of two-factor authentication by default. It supports One-Time Passwords (OTP) and hardware tokens (U2F). This quick start will use OTP - you'll need an OTP-compatible app that can scan a QR code.

Here's a selection of compatible two-factor authentication apps:

Teleport User Registration
OS User Mappings
The OS users that you specify (root, ubuntu and ec2-user in our examples) must exist! On Linux, if a user does not already exist, you can create it with adduser <login>. If you do not have the permission to create new users on the Linux host, run tctl users add teleport $(whoami) to explicitly allow Teleport to authenticate as the user that you have currently logged in as. If you do not map to an existing OS user, you will get authentication errors later on in this tutorial!
Teleport UI Dashboard

Install a Teleport client locally

Download MacOS .pkg installer (tsh client only, signed) file, double-click to run the installer.

Step 3/4. Log in using tsh

tsh is our client tool. It helps you log into Teleport clusters and obtain short-lived credentials. It can also be used to list servers, applications, and Kubernetes clusters registered with Teleport.

Log in to receive short-lived certificates from Teleport:

# Replace teleport.example.com:443 with your Teleport cluster's public address as configured above.
tsh login --proxy=teleport.example.com:443 --user=teleport-admin

Step 4/4. Have fun with Teleport!

Congrats! You've completed setting up Teleport! Now, feel free to have fun and explore the many features Teleport has to offer.

Here are several common commands and operations you'll likely find useful:

View Status

tsh status

SSH into a node

# list all SSH servers connected to Teleport
tsh ls

# ssh into `node-name` as `root`
tsh ssh [email protected]

Add a node to the cluster

Generate a short-lived dynamic join token using tctl:

tctl tokens add --type=node

Bootstrap a new node:

Replace auth_servers with the hostname and port of your Teleport cluster, token with the token you generated above.

sudo teleport start \
--roles=node \
--auth-server=https://teleport.example.com:443 \
--token=${TOKEN?} \
--labels=env=demo

Add an application to your Teleport cluster

Generate a short-lived dynamic token to join apps:

tctl tokens add --type=app

Add a new application:

Install Teleport on the target node, then start it using a command as shown below. Review and update auth-server, token, app-name, and app-uri before running this command.

sudo teleport start \
--roles=app \
--token=${TOKEN?} \
--auth-server=teleport.example.com:3080 \
--app-name=example-app  \ # Change "example-app" to the name of your application.
--app-uri=http://localhost:8080  # Change "http://localhost:8080" to the address of your application.

Guides

Check out our collection of step-by-step guides for common Teleport tasks.

Have a suggestion or can’t find something?
IMPROVE THE DOCS