Fork me on GitHub

Teleport

Deploy Open Source Teleport on a Linux Server

Improve
Teleport: Server Access Getting Started Guide

Teleport: Server Access Getting Started Guide

Length: 11:30

This tutorial will guide you through the steps needed to install and run Teleport 10.3.1 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 resource service (e.g., the Database Service or Application Service) 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.

Teleport Cloud takes care of this setup for you so you can provide secure access to your infrastructure right away.

Get started with a free trial of Teleport Cloud.

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. Use your own subdomain instead of tele.

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.

Execute the following commands on the host where you are running the Teleport Proxy Service:

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://apt.releases.teleport.dev/gpg \ -o /usr/share/keyrings/teleport-archive-keyring.asc

Source variables about OS version

source /etc/os-release

Add the Teleport APT repository for v10. You'll need to update this

file for each major release of Teleport.

Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67

echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \ https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v10" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport

Source variables about OS version

source /etc/os-release

Add the Teleport YUM repository for v10. You'll need to update this

file for each major release of Teleport.

Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID'

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153

sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v10/teleport.repo")
sudo yum install teleport
curl https://get.gravitational.com/teleport-v10.3.1-linux-amd64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.3.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.3.1-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v10.3.1-linux-arm-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.3.1-linux-arm-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-arm-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.3.1-linux-arm-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v10.3.1-linux-arm64-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://get.gravitational.com/teleport-v10.3.1-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v10.3.1-linux-arm64-bin.tar.gz

Verify that the checksums match

tar -xzf teleport-v10.3.1-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Using this APT repo may result in breaking upgrades upon "apt upgrade" as all major versions will be

published under the same component. We recommend following the instructions in the

"Debian/Ubuntu (DEB)" tab instead.

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

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 commands, 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
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 Teleport earlier).

sudo systemctl start teleport

Create a systemd unit file using the teleport install systemd command on Teleport v10.1.4 and later. Enter the unit file path you'd like to use for your configuration as part of the command. We recommend the path /etc/systemd/system/teleport.service for most use cases:

sudo teleport install systemd -o /etc/systemd/system/teleport.service

Enable and start the new teleport daemon:

sudo systemctl enable teleport && sudo systemctl start teleport

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:

Teleport Welcome Screen

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.

Teleport UI Dashboard

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

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

> 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:

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:

Further reading

  • How Let's Encrypt uses the ACME protocol to issue certificates.
  • Configuration for the teleport daemon relies on systemd. For more information on how the teleport service daemon is configured, see our guide on how to Run Teleport as a Daemon.