Fork me on GitHub

Teleport

Deploy Open Source Teleport on a Linux Server

Improve
Getting Started With Teleport 11

Getting Started With Teleport 11

Length: 15:22

This tutorial will guide you through the steps needed to install and run Teleport 11.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 (or CNAME for services that only provide a hostname) record exists for each application-specific subdomain so clients can access your applications via Teleport.

You should create either a separate DNS 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

Run the following commands to create a directory on your Linux machine called demo-app and add a simple HTML file to serve to clients:

mkdir demo-app
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:

Next, use the appropriate commands for your environment to install your package.

Teleport Edition

Add the Teleport repository to your repository list:

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 v11. 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/v11" \| 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 v11. 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/v11/teleport.repo")
sudo yum install teleport

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Optional: Use DNF on newer distributions

$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

$ sudo dnf install teleport

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

curl https://get.gravitational.com/teleport-v11.3.1-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-v11.3.1-linux-
-bin.tar.gz
shasum -a 256 teleport-v11.3.1-linux-
-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-v11.3.1-linux-
-bin.tar.gz
cd teleport
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_11.3.1_
.deb

Selecting previously unselected package teleport-ent.

(Reading database ... 30810 files and directories currently installed.)

Preparing to unpack teleport-ent_11.3.1_$SYSTEM_ARCH.deb ...

Unpacking teleport-ent 11.3.1 ...

Setting up teleport-ent 11.3.1 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-11.3.1.
.rpm

warning: teleport-ent-11.3.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.3.1-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-v11.3.1-linux-
-bin.tar.gz
shasum -a 256 teleport-v11.3.1-linux-
-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-v11.3.1-linux-
-bin.tar.gz
cd teleport
sudo ./install

For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

curl https://get.gravitational.com/teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v11.3.1-linux-
-fips-bin.tar.gz
cd teleport-ent
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_11.2.1_
.deb

Selecting previously unselected package teleport-ent.

(Reading database ... 30810 files and directories currently installed.)

Preparing to unpack teleport-ent_11.2.1_$SYSTEM_ARCH.deb ...

Unpacking teleport-ent 11.2.1 ...

Setting up teleport-ent 11.2.1 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-11.2.1.
.rpm

warning: teleport-ent-11.2.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.2.1-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-v11.2.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v11.2.1-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-v11.2.1-linux-amd64-bin.tar.gz
cd teleport
sudo ./install

Before installing a teleport binary with a version besides v11, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

When running multiple teleport binaries within a cluster, the following rules apply:

  • Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
  • Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
  • Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

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
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: 0.0.0.0: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 necessary commands 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 and the unit file path you'd like to use for your configuration. 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> or use Host user creation

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