This tutorial will guide you through the steps needed to install and run Teleport on Linux machines.
Prerequisites
- A Linux machine with ports
3023,3024,3025and443open. - A domain name.
- Around 20 minutes to complete; half of this may be waiting for DNS propagation.
Follow along with our video guide
Step 1: Install Teleport on a Linux Host
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.
Step 1b: Configure Teleport
Generate a configuration file for Teleport using teleport configure.
Acme turns on automatic TLS certificates from Letsencrypt. Set up email to receive updates from Letsencrypt, 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!
Step 1c: 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 setup two A records for tele.example.com and *.tele.example.com
pointing to the IP/FQDN of the machine with Teleport installed.
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: Create a Teleport user and set up 2-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.
sudo tctl users add teleport-admin --roles=editor,access --logins=root,ubuntu,ec2-user
Teleport will always enforce the use of 2-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 which can scan a QR code.
Here's a selection of compatible Two-Factor authentication apps:
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 are currently logged in as. If you do not map to an existing OS user,
you will get authentication errors later on in this tutorial!
Step 2a: Install a Teleport client locally
Step 3: 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.
Login 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: Have Fun with Teleport!
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:
sudo 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:
sudo 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.