Fork me on GitHub
Teleport

Getting started on a Linux Server

Improve
Getting started with Teleport 6.0

Getting started with Teleport 6.0

Length: 17:33

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

Prerequisites

Local-only setups

If you would like to try out Teleport on your local machine—e.g., you do not have access to a DNS server or internal public key infrastructure—we recommend following our Docker Compose guide.

Step 1/4. Install Teleport on a Linux host

Run the following commands to install the Teleport binary on your system:

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

curl https://deb.releases.teleport.dev/teleport-pubkey.asc | sudo apt-key add -
sudo add-apt-repository 'deb https://deb.releases.teleport.dev/ stable main'
sudo apt-get update
sudo apt-get install teleport
curl -O https://get.gravitational.com/teleport-v8.0.7-linux-amd64-bin.tar.gz
tar -xzf teleport-v8.0.7-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
curl -O https://get.gravitational.com/teleport-v8.0.7-linux-arm-bin.tar.gz
tar -xzf teleport-v8.0.7-linux-arm-bin.tar.gz
cd teleport
sudo ./install
curl -O https://get.gravitational.com/teleport-v8.0.7-linux-arm64-bin.tar.gz
tar -xzf teleport-v8.0.7-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Take a look at the Installation Guide for more options.

The examples below may include the use of the sudo keyword, token UUIDs, and users with elevated privileges to make following each step easier.

We recommend you follow the best practices to avoid security incidents:

  1. Avoid using sudo in production environments unless it's necessary.
  2. Create new, non-root, users and use test instances for experimenting with Teleport.
  3. You can run many Teleport's services as a non root. For example, auth, proxy, application access, kubernetes access, and database access services can run as a non-root user. Only the SSH/node service requires root access. You will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443)
  4. Follow the "Principle of Least Privilege" (PoLP) and "Zero Admin" best practices. Don't give users permissive roles when giving them more restrictive access,editor roles will do instead.
  5. Save tokens into a file rather than sharing tokens directly as strings.

Configure DNS

Teleport uses TLS to provide secure access to its Proxy Service and Auth Service, and this requires a domain name that clients can use to verify Teleport's certificate. 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 @$DNS_SERVER_ADDRESS tele.example.com

Configure Teleport

Next, generate a configuration file for Teleport using the teleport configure command. This command requires information about a TLS certificate and private key. If your environment allows your Teleport Auth Server to be reachable via the public internet, we recommend using Let's Encrypt to generate your key and certificate automatically. Otherwise, you can use a key and certificate provided via your organization's internal public key infrastructure.

Teleport uses the ACME protocol to request automatic TLS certificates from Let's Encrypt, which accesses an HTTP endpoint on your Teleport host in order to complete authentication challenges.

Use the following command to configure Teleport:

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!

The --acme-email flag indicates an email address that Let's Encrypt can use for notifications, and does not require the same domain name as your Teleport host.

For the --cluster-name flag, enter the domain name you used when creating a DNS A record earlier.

On your Teleport host, place a valid private key and a certificate chain in /var/lib/teleport/privkey.pem and /var/lib/teleport/fullchain.pem respectively.

The leaf certificate must have a subject that corresponds to the domain of your Teleport host, e.g., *.teleport.example.com.

Configure Teleport, changing the values of the --cluster-name and --public-addr flags to match the domain name of your Teleport host.

sudo teleport configure -o file \ --cluster-name=tele.example.com \ --public-addr=tele.example.com:443 \ --cert-file=/var/lib/teleport/fullchain.pem \ --key-file=/var/lib/teleport/privkey.pem

Start Teleport

sudo systemctl start teleport
sudo teleport start

You can access Teleport's Web UI via HTTPS at the domain you created earlier.

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 second factor authenticators (WebAuthn). This quick start will use OTP—you'll need an OTP-compatible app that can scan a QR code.

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 the MacOS .pkg installer (tsh client only, signed) and double-click to run it.

brew install teleport
Note

The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. We recommend the use of our own Teleport packages.

If you choose to use Homebrew, you must verify that the versions of tsh and tctl are compatible with the versions you run server-side. Homebrew usually ships the latest release of Teleport, which may be incompatible with older versions. See our compatibility policy for details.

curl -O teleport-v8.0.7-windows-amd64-bin.zip https://get.gravitational.com/teleport-v8.0.7-windows-amd64-bin.zip

Unzip the archive and move `tsh.exe` to your %PATH%

For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) please see our installation page.

curl -O https://get.gravitational.com/teleport-v8.0.7-linux-amd64-bin.tar.gz
tar -xzf teleport-v8.0.7-linux-amd64-bin.tar.gz
cd teleport
sudo ./install

Teleport binaries have been copied to /usr/local/bin

To configure the systemd service for Teleport take a look at examples/systemd/README.mdx

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 with your Teleport cluster's public address as configured above.

tsh login --proxy=teleport.example.com --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`

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

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

#cloud-config

package_upgrade: true

write_files:
- path: /etc/teleport.yaml
    content: |
        teleport:
            auth_token: ""
            auth_servers:
                - "https://teleport.example.com:443"
        auth_service:
            enabled: false
        proxy_service:
            enabled: false
        ssh_service:
            enabled: true
            labels:
                env: demo

runcmd:
- 'mkdir -p /tmp/teleport'
- 'cd /tmp/teleport && curl -O https://get.gravitational.com/teleport_8.0.7_amd64.deb'
- 'dpkg -i /tmp/teleport/teleport_8.0.7_amd64.deb'
- 'systemctl enable teleport.service'
- 'systemctl start teleport.service'

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.

Further reading

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