Deploy Open Source Teleport on a Linux Server

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.

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.

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.

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?}"

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.

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

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

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

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

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

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

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

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.

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

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

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

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

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:

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.

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:

brew install teleport

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%

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:

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:

• Applications
• Databases
• Kubernetes clusters
• Servers
• Windows desktops
• Service accounts (via Machine ID)

Manage your cluster

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

• Managing users
• Setting up single sign-on with GitHub
• Recording SSH sessions
• Labeling Teleport resources

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.