Fork me on GitHub

Teleport

Try out Teleport on a Linux Server

Improve
Set Up Teleport Open Source in 5 Minutes | Step-by-Step

Set Up Teleport Open Source in 5 Minutes | Step-by-Step

Length: 04:36

This tutorial will show you how to install and run a demo Teleport cluster 13.0.3 on a Linux host using Teleport Community Edition. Once you deploy the cluster, you can configure RBAC, register resources, and protect your small-scale demo environments or home lab.

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 SSH Service: An SSH server implementation that takes advantage of Teleport's short-lived certificates, sophisticated RBAC, session recording, and other features.

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 host with only port 443 open to ingress traffic. You must be able to install and run software on the host. Either configure access to the host 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.

    Quick demo environments

    For a quick demo environment you can use to follow this guide, consider installing our DigitalOcean 1-Click droplet. View the installation page on DigitalOcean Marketplace. Once your droplet is ready, SSH into the droplet and follow the configuration wizard.

  • A two-factor authenticator app such as Authy, Google Authenticator, or Microsoft Authenticator

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.

This guide is not intended for local deployments. If your environment doesn't meet the prerequisites above, you can get started with Teleport by signing up for a free trial of Teleport Enterprise Cloud.

Step 1/4. 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 DNS A records, each pointing to the IP address of your Linux host. Assuming teleport.example.com is your domain name, set up records for:

DomainReason
teleport.example.comTraffic to the Proxy Service from users and services.
*.teleport.example.comTraffic to web applications registered with Teleport. Teleport issues a subdomain of your cluster's domain name to each application.

Step 2/4. Set up Teleport on your Linux host

Install Teleport

On your Linux host, run the following command to install the Teleport binary:

curl https://goteleport.com/static/install.sh | bash -s 13.0.3

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

teleport configure --acme --acme-email=[email protected] --cluster-name=tele.example.com | \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

Start Teleport

Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

On the host where you will run your Teleport instance, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

On the host where you will run your Teleport instance, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

sudo teleport install systemd -o /etc/systemd/system/teleport.service
sudo systemctl enable teleport
sudo systemctl start teleport

You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

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 3/4. 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 host, 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 host. 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.

In addition to Teleport's Web UI, you can access resources in your infrastructure via the tsh client tool.

Install tsh on your local workstation:

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 https://cdn.teleport.dev/teleport-v13.0.3-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-v13.0.3-linux-amd64-bin.tar.gz
tar -xzf teleport-v13.0.3-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 4/4. Enroll your infrastructure

With Teleport, you can protect all of the resources in your infrastructure behind a single identity-aware access proxy, including servers, databases, applications, Kubernetes clusters, Windows desktops, and cloud provider APIs.

To enroll a resource with Teleport, visit the Web UI and click the name of a resource on the sidebar, e.g., Servers, Applications, and Kubernetes. The Web UI will show you the steps you can take to enroll that resource.

Adding resources

In the Servers tab, you can see that you have already enrolled your Linux server.

Next steps

Now that you have launched your Teleport cluster and added your first resources, see how to use Teleport to set up secure access to your infrastructure.

Read the Manage Access documentation to get started setting up role-based access controls for all of the resources you registered.

To learn about common Day Two operations when managing a Teleport cluster, read the Manage your Cluster guides.

You can also read more about how to protect your infrastructure with Teleport, including:

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.