Teleport Quick Start

This tutorial will guide you through the steps needed to install and run Teleport on Linux machine(s).

Prerequisites

Step 1: Install Teleport on a Linux Host

There are several ways to install Teleport. Take a look at the Teleport Installation page to pick the most convenient for you.

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

# Optional:  Using DNF on newer distributions
# dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
# dnf install teleport
curl -O https://get.gravitational.com/teleport-v5.0.0-rc.2-linux-arm-bin.tar.gz
tar -xzf teleport-v5.0.0-rc.2-linux-arm-bin.tar.gz
cd teleport
./install
curl -O https://get.gravitational.com/teleport-v5.0.0-rc.2-linux-arm64-bin.tar.gz
tar -xzf teleport-v5.0.0-rc.2-linux-arm64-bin.tar.gz
cd teleport
./install
curl -O https://get.gravitational.com/teleport-v5.0.0-rc.2-linux-amd64-bin.tar.gz
tar -xzf teleport-v5.0.0-rc.2-linux-amd64-bin.tar.gz
cd teleport
./install

Step 1b: Configure Teleport

When setting up Teleport, we recommend running it with Teleports YAML configuration file.

# Concatenate teleport.yaml using a basic demo config.
$ cat > teleport.yaml <<EOF
teleport:
    data_dir: /var/lib/teleport
auth_service:
    enabled: "yes"
    cluster_name: "teleport-quickstart"
    listen_addr: 0.0.0.0:3025
    tokens:
    - proxy,node,app:f7adb7ccdf04037bcd2b52ec6010fd6f0caec94ba190b765
ssh_service:
    enabled: "yes"
    labels:
        env: staging
proxy_service:
    enabled: "yes"
    listen_addr: 0.0.0.0:3023
    web_listen_addr: 0.0.0.0:3080
    tunnel_listen_addr: 0.0.0.0:3024
    https_keypairs:
        - key_file:
        - cert_file:
app_service:
    enabled: "yes"
    debug_app: true
EOF

# Move teleport.yaml to /etc/teleport.yaml
$  mv teleport.yaml /etc

Step 1c: Configure Domain Name & Obtain TLS Certs using Let's Encrypt

Teleport requires a secure public endpoint for the Teleport UI and for end users to connect to. A domain name and TLS are required for Teleport. We'll use Let's Encrypt to obtain a free TLS certificate.

DNS Setup:
For this setup, we'll simply use a A or CNAME record pointing to the IP/FQDN of the machine with Teleport installed.

TLS Setup:
If you already have TLS certs you can use those certificates, or if using a new domain we recommend using Certbot; which is free and simple to setup. Follow certbot instructions for how to obtain a certificate for your distro.

Using Certbot to obtain Wildcard Certs

Let's Encrypt provides free wildcard certificates. If using certbot with DNS challenge the below script will make setup easy. Replace with your email [email protected] and URL for Teleport teleport.example.com

certbot certonly --manual \
  --preferred-challenges=dns \
  --email [email protected] \
  --server https://acme-v02.api.letsencrypt.org/directory \
  --agree-tos \
  --manual-public-ip-logging-ok \
  -d "teleport.example.com, *.teleport.example.com"

Update teleport.yaml
Once you've obtain the certificates from LetsEncrypt. The below command will add update Teleport public_addr and update the location of the LetsEncrypt key pairs.

Replace teleport.example.com with the location of your proxy.

# Replace `teleport.example.com` with your domain name.
export TELEPORT_PUBLIC_DNS_NAME="teleport.example.com"
cat >> /etc/teleport.yaml <<EOL
  public_addr: $TELEPORT_PUBLIC_DNS_NAME:3080
  https_keypairs:
    - key_file: /etc/letsencrypt/live/$TELEPORT_PUBLIC_DNS_NAME/privkey.pem
    - cert_file: /etc/letsencrypt/live/$TELEPORT_PUBLIC_DNS_NAME/fullchain.pem
EOL

Visit: https://teleport.example.com:3080/

Success

Teleport is now up and running

Step 2: Create User & Setup 2FA

Create a new user teleport-admin, with the Principles root, ubuntu, ec2-user

# tctl is an administrative tool that can configure Teleport auth service.
tctl users add teleport-admin root,ubuntu, ec2-user

Teleport will always enforces Two-Factor Authentication and support OTP and Hardware Tokens (U2F).The quick start has been setup with OTP. For setup you'll need an OTP app.

A selection of Two-Factor Authentication apps are.

Teleport User Registration

OS User Mappings

The OS user root, ubuntu, ec2-user must exist! On Linux, if it does not already exist, create it with adduser teleport. If you do not have the permission to create new users on the Linux Host, run tctl users add teleport <your-username> to explicitly map teleport to an existing OS user. If you do not map to a real OS user you will get authentication errors later on in this tutorial!

Teleport UI Dashboard

Step 2a: Install Teleport Locally

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

$ brew install teleport

Note

The Teleport package in Homebrew is not maintained by Teleport. We recommend the use of our own Teleport packages.

curl -O teleport-v5.0.0-rc.2-windows-amd64-bin.zip https://get.gravitational.com/teleport-v5.0.0-rc.2-windows-amd64-bin.zip
# Move `tsh` to your %PATH%

For more options please see our installation page.

curl -O https://get.gravitational.com/teleport-v5.0.0-rc.2-linux-amd64-bin.tar.gz
tar -xzf teleport-v5.0.0-rc.2-linux-amd64-bin.tar.gz
cd teleport
./install

Step 3: Login Using tsh

tsh is our client tool. It helps you login, obtains credentials and list servers,applications and Kubernetes clusters.

Prior to launch you must authenticate.

# Replace teleport.example.com:3080 with your cluster  address.
tsh login --proxy=teleport.example.com:3080 --user=teleport-admin

Step 4: Have Fun with Teleport!

View Status

tsh status

SSH into a node

# list all servers connected to Teleport
tsh ls

# ssh as 'root' into node named `node-name`. replace with values from
tsh ssh [email protected]

Add a Node to the Cluster

When you setup Teleport earlier we setup a strong static token for nodes, apps and tokens. We've used a static token to make setup easier but you can also obtain dyanmic short lived tokens using tctl

#...
#    tokens:
#    - proxy,node,app:f7adb7ccdf04037bcd2b52ec6010fd6f0caec94ba190b765
#...
tctl tokens add --type=node

Armed with these details, we'll bootstrap a new host using

Install Teleport on the target node, then start using.

teleport start \
--roles=node \
--auth-server=https://teleport.example.com:3080 \
--token=f7adb7ccdf04037bcd2b52ec6010fd6f0caec94ba190b765 \
--labels=env=quickstart

Replace auth_servers with the IP and port of your Teleport Cluster

#cloud-config

package_upgrade: true

write_files:
- path: /etc/teleport.yaml
    content: |
        teleport:
            auth_token: "f7adb7ccdf04037bcd2b52ec6010fd6f0caec94ba190b765"
            auth_servers:
                - "https://teleport.example.com:3080"
        auth_service:
            enabled: "false"
        ssh_service:
            enabled: "true"
            labels:
                host: test-machine
        proxy_service:
            enabled: "false"

runcmd:
- 'mkdir -p /run/teleport'
- 'cd /run/teleport && curl -O https://get.gravitational.com/teleport_5.0.0-rc.2_amd64.deb'
- 'dpkg -i /run/teleport/teleport_5.0.0-5.0.0-rc.2_amd64.deb'
- 'systemctl enable teleport.service'
- 'systemctl start teleport.service'

Add an Application to the Cluster

When you setup Teleport earlier we setup a strong static token for nodes, apps and tokens. We've used a static token to make setup easier but you can also obtain dyanmic short lived tokens using tctl

#...
#    tokens:
#    - proxy,node,app:f7adb7ccdf04037bcd2b52ec6010fd6f0caec94ba190b765
#...
tctl tokens add --type=app

Armed with these details, we'll bootstrap a new host using

Install Teleport on a target node, then start using. Review an update auth-server, app-name, app-uri before running this comment.

teleport start \
--roles=app \
--token=f7adb7ccdf04037bcd2b52ec6010fd6f0caec94ba190b765 \
--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.

Next Steps

Congratulations! You've completed the Teleport Quickstart.

In this guide you've learned how to install Teleport on a single-node and seen a few of the most practical features in action. When you're ready to learn how to set up Teleport for your team, we recommend that you read our Admin Guide to get all the important details. This guide will lay out everything you need to safely run Teleport in production, including SSL certificates, security considerations, and YAML configuration.

Guides

If you like to learn by doing, check out our collection of step-by-step guides for common Teleport tasks.

Try Teleport Today

In the Cloud, Self-hosted, or Open Source

View Developer Docs