Teleport

Getting started on a Linux Server

Getting Started with Teleport 9

Length: 20:20

This tutorial will guide you through the steps needed to install and run Teleport 9.3.7 on a Linux machine, then show you how to use Teleport to configure access to resources.

We will run the following Teleport services:

Teleport Auth Service: The certificate authority for your cluster. It issues certificates and conducts authentication challenges. The Auth Service is typically inaccessible outside your private network.
Teleport Proxy Service: The cluster frontend, which handles user requests, forwards user credentials to the Auth Service, and communicates with Teleport instances that enable access to specific resources in your infrastructure.
Teleport Application Service: Enables secure access to web applications in private networks. In this tutorial, we will use Teleport to access a simple web service.
Teleport SSH Service: An SSH server implementation that takes advantage of Teleport's short-lived certificates, sophisticated RBAC, session recording, and other features.

When running Teleport in production, we recommend that you follow the practices below to avoid security incidents. These practices may differ from the examples used in this guide, which are intended for demo environments:

Avoid using sudo in production environments unless it's necessary.
Create new, non-root, users and use test instances for experimenting with Teleport.
Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
Follow the "Principle of Least Privilege" (PoLP). Don't give users permissive roles when giving them more restrictive roles will do instead. For example, assign users the built-in access,editor roles.
When joining a Teleport agent to a cluster, save the invitation token to a file. Otherwise, the token will be visible when examining the teleport command that started the agent, e.g., via the history command on a compromised system.

Prerequisites

A Linux machine with only port 443 open to ingress traffic. You must be able to install and run software on the machine. Either configure access to your machine via SSH for the initial setup (and open an SSH port in addition port 443) or enter the commands in this guide into an Amazon EC2 user data script, Google Compute Engine startup script, or similar.
A two-factor authenticator app such as Authy, Google Authenticator, or Microsoft Authenticator
python3 installed on your Linux machine. We will use this to run a simple HTTP file server, so you can use another HTTP server if you have one installed.

You must also have one of the following:

A registered domain name.
An authoritative DNS nameserver managed by your organization, plus an existing certificate authority. If using this approach, ensure that your browser is configured to use your organization's nameserver.

Local-only setups

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

Step 1/6. 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.

Set up two A DNS records: tele.example.com for all traffic and *.tele.example.com for web apps using Application Access. (We are assuming that your domain name is example.com.)

Teleport assigns a subdomain to each application you have configured for Application Access (e.g., grafana.teleport.example.com), so you will need to ensure that a DNS A record exists for each application-specific subdomain so clients can access your applications via Teleport.

You should create either a separate DNS A record for each subdomain or a single record with a wildcard subdomain such as *.teleport.example.com. This way, your certificate authority (e.g., Let's Encrypt) can issue a certificate for each subdomain, enabling clients to verify your Teleport hosts regardless of the application they are accessing.

Tip for finding AWS zone id by the domain name.
MYIP="$(curl https://ipv4.icanhazip.com/)"
MYZONE_DNS="example.com"
MYZONE=$(aws route53 list-hosted-zones-by-name --dns-name=${MYZONE_DNS?} | jq -r '.HostedZones[0].Id' | sed s_/hostedzone/__)
The fully qualified domain name for your Teleport Proxy Service.
These commands will also create an A record for a wildcard subdomain.
MYDNS="tele.example.com"
Create a JSON file changeset for AWS.
jq -n --arg ip ${MYIP?} --arg dns ${MYDNS?} '{"Comment": "Create records", "Changes": [{"Action": "CREATE","ResourceRecordSet": {"Name": $dns, "Type": "A", "TTL": 300, "ResourceRecords": [{ "Value": $ip}]}},{"Action": "CREATE", "ResourceRecordSet": {"Name": ("*." + $dns), "Type": "A", "TTL": 300, "ResourceRecords": [{ "Value": $ip}]}}]}' > myrecords.json
Review records before applying.
cat myrecords.json | jq
Apply the records and capture change id
CHANGEID=$(aws route53 change-resource-record-sets --hosted-zone-id ${MYZONE?} --change-batch file://myrecords.json | jq -r '.ChangeInfo.Id')
Verify that change has been applied
aws route53 get-change --id ${CHANGEID?} | jq '.ChangeInfo.Status'
"INSYNC"

MYZONE="myzone"
The fully qualified domain name for your Teleport Proxy Service.
These commands will also create an A record for a wildcard subdomain.
MYDNS="tele.example.com"
MYIP="$(curl https://ipv4.icanhazip.com/)"
gcloud dns record-sets transaction start --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction add ${MYIP?} --name="*.${MYDNS?}" --ttl="30" --type="A" --zone="${MYZONE?}"
gcloud dns record-sets transaction describe --zone="${MYZONE?}"
gcloud dns record-sets transaction execute --zone="${MYZONE?}"

Tip

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

dig tele.example.com

Step 2/6. Run a simple web service

Create a directory on your Linux machine called demo-app and run the following command:

cat<<EOF>>demo-app/index.html<!DOCTYPE html><html><head><title>Welcome!</title><head><body><h1>Welcome to your Teleport cluster!</h1></body></html>EOF

Run a simple HTTP service on port 9000 that returns your welcome page:

nohup python3 -m http.server 9000 --directory demo-app &

Since port 9000 is not open on your Linux host, there is currently no way to access the web service from your local machine. We will configure Teleport to enable you to access the web service securely.

Step 3/6. Set up Teleport on your Linux host

Install Teleport

Run the appropriate commands for your environment to install the Teleport binary on your Linux host:

Download Teleport's PGP public key
sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \  -o /usr/share/keyrings/teleport-archive-keyring.asc
Add the Teleport APT repository
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] https://deb.releases.teleport.dev/ stable main" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

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://get.gravitational.com/teleport-v9.3.7-linux-amd64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.3.7-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v9.3.7-linux-amd64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.3.7-linux-amd64-bin.tar.gz
cd teleport
sudo ./install

curl https://get.gravitational.com/teleport-v9.3.7-linux-arm-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.3.7-linux-arm-bin.tar.gz
shasum -a 256 teleport-v9.3.7-linux-arm-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.3.7-linux-arm-bin.tar.gz
cd teleport
sudo ./install

curl https://get.gravitational.com/teleport-v9.3.7-linux-arm64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.3.7-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v9.3.7-linux-arm64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.3.7-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Take a look at the Installation Guide for more options.

Configure Teleport

Generate a configuration file for Teleport using the teleport configure command. This command requires information about a TLS certificate and private key.

If you are running Teleport on the internet, we recommend using Let's Encrypt to receive your key and certificate automatically. For private networks or custom deployments, use your own private key and certificate.

Let's Encrypt verifies that you control the domain name of your Teleport cluster by communicating with the HTTPS server listening on port 443 of your Teleport Proxy Service.

You can configure the Teleport Proxy Service to complete the Let's Encrypt verification process when it starts up.

On the host where you will start the Teleport Auth Service and Proxy Service, run the following teleport configure command, where tele.example.com is the domain name of your Teleport cluster and [email protected] is an email address used for notifications (you can use any domain):

DOMAIN=tele.example.com
[email protected]
teleport configure --acme --acme-email=${EMAIL?} --cluster-name=${DOMAIN?} | \ sudo tee /etc/teleport.yaml > /dev/null

The --acme, --acme-email, and --cluster-name flags will add the following settings to your Teleport configuration file:

proxy_service:
  enabled: "yes"
  web_listen_addr: :443
  public_addr: tele.example.com:443
  acme:
    enabled: "yes"
    email: [email protected]

Port 443 on your Teleport Proxy Service host must allow traffic from all sources.

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

Next, configure Teleport to provide secure access to your web service. Edit your Teleport configuration file (/etc/teleport.yaml) to include the following, replacing teleport.example.com with the domain name of your Teleport cluster.

app_service:
    enabled: yes
    apps:
    - name: "demo"
      uri: "http://localhost:9000"
      public_addr: "demo.teleport.example.com"

Start Teleport

On your Linux machine, run the following command to start the teleport daemon (this depends on how you installed Telport earlier).

sudo systemctl start teleport

sudo teleport start

You can access Teleport's Web UI via HTTPS at the domain you created earlier (e.g., https://teleport.example.com). You should see a welcome screen similar to the following:

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

In this step, 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.

On your Linux machine, run the following command:

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

The command prints a message similar to the following:

User "teleport-admin" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
https://teleport.example.com:443/web/invite/123abc456def789ghi123abc456def78

NOTE: Make sure teleport.example.com:443 points at a Teleport proxy which users can access.

Visit the provided URL in order to create your Teleport user.

OS User Mappings

The users that you specify in the logins flag (e.g., root, ubuntu and ec2-user in our examples) must exist on your Linux machine. Otherwise, you will get authentication errors later in this tutorial.

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.

Teleport enforces the use of two-factor authentication by default. It supports one-time passwords (OTP) and second-factor authenticators (WebAuthn). In this guide, you will need to enroll an OTP authenticator application using the QR code on the Teleport welcome screen.

Step 5/6. Log in using tsh

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

Install tsh on your local machine:

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-v9.3.7-windows-amd64-bin.zip https://get.gravitational.com/teleport-v9.3.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-v9.3.7-linux-amd64-bin.tar.gz
tar -xzf teleport-v9.3.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

Replace teleport.example.com with your Teleport cluster's public address as configured above.
tsh login --proxy=teleport.example.com --user=teleport-admin
> Profile URL:        https://teleport.example.com:443
  Logged in as:       teleport-admin
  Cluster:            teleport.example.com
  Roles:              access, editor
  Logins:             root, ubuntu, ec2-user
  Kubernetes:         enabled
  Valid until:        2022-04-26 03:04:46 -0400 EDT [valid for 12h0m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

Step 6/6. Access resources

Congrats! You've completed setting up Teleport and signed in to your cluster. Now you can use Teleport to quickly access resources.

Visit your demo website

Now that you have logged in to Teleport, you can see the demo website you started earlier. Visit https://demo.teleport.example.com, replacing teleport.example.com with the domain name of your Teleport cluster.

You can use the Teleport Application Service to configure access to any web application in your private network, including HTTP management endpoints for popular infrastructure technologies.

SSH into your Node

You also configured the Teleport SSH Service, meaning that you can easily access your Linux machine after logging in to Teleport.

See the logins you can use to access a Node:

tsh status
> Profile URL:        https://teleport.example.com:443
  Logged in as:       teleport-admin
  Cluster:            teleport.example.com
  Roles:              access, editor
  Logins:             root, ubuntu, ec2-user
  Kubernetes:         enabled
  Valid until:        2022-04-26 04:55:59 -0400 EDT [valid for 11h38m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

List all SSH servers connected to Teleport:

tsh ls
Node Name        Address        Labels                                
---------------- -------------- ------------------------------------- 
mynode 127.0.0.1:3022 env=example,hostname=mynode

SSH into mynode as root:

tsh ssh [email protected]

Next steps

Add resources

Now that you know how to set up a Teleport cluster, learn how to register all of the resources in your infrastructure with Teleport:

Manage your cluster

You can also check out our collection of step-by-step guides for common Teleport tasks, such as:

Sign in to Teleport