Teleport Quick Start

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

Prerequisites

• A Linux Machine. With Ports 3023-3025 and 3080 open.
• A Domain Name, DNS and TLS Certs. We'll provide examples using Let'sEncrypt
• 25 minutes to complete. 15min is waiting for DNS propagation and TLS certificates.

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.

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/

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.

• Authy
• Google Authenticator
• Microsoft Authenticator

Step 2a: Install Teleport Locally

$ brew install teleport

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%

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

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

#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

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.

• Install Teleport
• Share Sessions
• Manage Users
• Label Nodes
• Teleport with OpenSSH