How to Install a Teleport Cluster on Debian 11

Teleport is an open-source that can be used as an access plane for your global infrastructure. It provides zero-trust access to various services such as servers, Kubernetes clusters, database servers, DevOps applications like AWS Management Console, CI/CD, version control, and desktops. Teleport is the single source of truth for access, synchronized across your entire infrastructure.

Teleport can eliminate the need for services such as VPNs by providing a single gateway to access your global computing infrastructure. It's an Identity-Native Access Proxy that allows you to access your infrastructure securely.

Teleport has been publicly audited by security companies such as Cure53 and Doyensec. Teleport is currently deployed and used in production by companies such as Samsung, NASDAQ, IBM, Epic Games, and many more.

In this guide, you will install and configure Teleport - the access plane for your infrastructure on a Debian 11 server. You'll learn how to initialize the secure Teleport Cluster, set up the Teleport user, and then add Nodes to the Teleport Cluster with two different methods.

Prerequisites

To get started, you will need the following requirements:

• A Debian 11 server - This example uses a Debian server with hostname 'teleport-server' with IP address '192.168.5.100'.
• A non-root user with sudo/root administrator privileges.
• A domain name pointed to the server IP address.
• Generated SSL Letsencrypt for your domain name.
• Two Factor Authentication apps such as KeepassXC for computer users, Aegis for Android users, or Google Authenticator for iOS.

You'll also need other nodes/servers that you will add to the Teleport server. You can use different Linux distributions, this example uses two servers 'client1' and 'client2' with both also the Debian system.

When you're ready to continue, log in with your user and start executing the following commands to get started.

Installing Teleport on Debian Server

First, you'll install the Teleport packages to the 'teleport-server'. Teleport provides DEB packages for Debian-based distributions and RPM packages for RHEL-based distributions.

In this step, you'll add the Teleport repository to your Debian server. Then install Teleport packages via APT.

Run the below apt command to install basic dependencies for managing repositories.

sudo apt install curl wget apt-transport-https gnupg2

Input y when prompted and press ENTER to proceed.

Next, run the below command to load the environment variables available on the file '/etc/os-release'.

source /etc/os-release

Run the curl command below to download the GPG key of the Teleport repository. Then, add the Teleport repository for Debian-based distributions via the echo and tee commands below.

sudo curl https://apt.releases.teleport.dev/gpg \
-o /usr/share/keyrings/teleport-archive-keyring.asc

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

After adding the Teleport repository, run the below apt command to update your package manager cache.

sudo apt update

You'll see the Teleport repository is added to your Debian server.

Now install Teleport via the apt command below. The Teleport installation should now begin automatically.

sudo apt install teleport

After installing Teleport, you can move on t set up your Teleport deployment.

Configuring Teleport Server

To use Teleport, you must first configure the Teleport itself. You must have the domain name that will be used for Teleport and generated SSL certificates for securing your Teleport deployment.

In this step, you'll initialize Teleport installation on a Debian server, enable the Teleport web application dashboard, then start and enable Teleport service.

This example uses the domain name 'tele.howtoforge.local' for the Teleport deployment and SSL certificates generated in the '/etc/letsencrypt/live/tele.howtoforge.local/' directory.

To start, run the below teleport command to initialize the Teleport server configuration. Also, be sure to change the domain name, cluster name, and the path of both SSL certificates, public and private keys.

sudo teleport configure -o file \
--cluster-name=tele.howtoforge.local \
--public-addr=tele.howtoforge.local:443 \
--cert-file=/etc/letsencrypt/live/tele.howtoforge.local/fullchain.pem \
--key-file=/etc/letsencrypt/live/tele.howtoforge.local/privkey.pem

In the output on your terminal, you should see the Teleport configuration generated to the '/etc/teleport.yml' file.

Next, open the Teleport config file '/etc/teleport.yaml' using the below nano editor command.

sudo nano /etc/teleport.yaml

Add the following lines to the end of the line. With these lines, you'll enable the Teleport web service that provides an administration dashboard. Also, be sure to change the domain name 'tele.howtoforge.local'.

app_service:
  enabled: yes
  apps:
  - name: "teleport-webapp"
    uri: "http://localhost:9000"
    public_addr: "tele.howtoforge.local"

Save the file and exit the editor when finished.

Now run the below systemctl command utility to start and enable the Teleport service.

sudo systemctl start teleport
sudo systemctl enable teleport

The Teleport service should be running and enabled, so the service will start automatically upon the bootup. Verify the Teleport service using the below command.

sudo systemctl status teleport

In the output, you should see the Teleport service status is running, and it's enabled.

At this point, your Teleport Cluster is running with the web service enabled on top of it. To verify that the Teleport web service is enabled, open your web browser and visit the domain name of your Teleport installation (i.e: https://tele.howtoforge.local/).

You should now get the Teleport web service login page.

In the next steps, you'll start configuring the Teleport admin user via the command line and web administration dashboard.

Setting up Teleport User

The Teleport service and web service is running, but you still can't log in to it because you still need to add a new Teleport user. With a Teleport user, you can manage Teleport Cluster via the command lines (tctl and tsh) or using the web administration dashboard provided by the Teleport web service.

Before creating a Teleport user, ensure that the Two Factor Authentication app is installed on your devices. You can use mobile apps via Aegis or Google Authentication, or you can use KeepassXC with a 2FA plugin for computer users.

On the 'teleport-server' machine, run the below command to create a new Teleport user.

sudo tctl users add teleport-admin --roles=editor,access --logins=root,debian,ec2-user

This command will create a new user 'teleport-admin' with roles editor and access. Also, the flag '--logins' allows 'teleport-admin' to log in to any nodes via user root, debian, or ec2-user. Users behind the '--login' flag must be created on target nodes.

Below is the similar output you should receive on your terminal - You can see the generated link that will be used to set up Teleport user 'teleport-admin'.

Copy the generated link and paste it into your web browser. And you should get the welcome message for setting up the new Teleport user. Click the GET STARTED button to start configuring the new user.

Now input the username for your Teleport user and input the new strong password and repeat. Then click NEXT to continue.

Next, you must set up the Two Factor Authentication for your Teleport user. Scan the QR code on your screen to add the new application to your 2FA application.

Input the generated authentication code from your 2FA application and click SUBMIT.

If the 2FA code is correct, you should get the message 'Registration Successful' on your screen. This means the new user 'teleport-admin' is added and configured.

Click GO TO DASHBOARD.

You should now get the web administration dashboard of your Teleport deployment, which is running securely with HTTPS enabled and the user is created with 2FA enabled.

Managing Teleport Cluster via Command Line

Teleports provides command lines tsh and tctl that can be used for managing Teleport Cluster. Both command lines are included by default with the Teleport package.

The tsh command allows users to authenticate and manage Teleport Cluster from the terminal. You can add, edit, or delete Teleport resources on the cluster. For security, you must run the tsh command as a non-root user.
The tctl command to set up and configure the Teleport Auth Service. This must be run with sudo or root privileges.

In this step, you'll access and manage Teleport Cluster via both command lines tsh and tctl.

First, log in to the non-root user via the below command. This example uses the user 'debian'.

su - debian

Now run the below tsh command to authenticate to your Teleport Cluster. This example will authenticate to the Teleport Cluster that runs on the domain name 'tele.howtoforge.local' with the user 'teleport-admin'.

tsh login --proxy=tele.howtoforge.local --user=teleport-admin

You'll be asked to input the password for the 'teleport-admin' user and input the OTP authentication code. Input the correct password for your user and the correct OTP code from your 2FA application.

When successful and authenticated, you should receive the detailed connections to the Teleport Cluster as the following.

You can also verify the current connection to the Teleport Cluster via the below tsh command. This will generate the same output as the screenshot on top.

tsh status

Now that you've authenticated to the Teleport Cluster via tsh, you can now manage resources in Teleport via terminal.

Run the below tsh command to check the list of hosts/nodes/servers that are available on the Teleport Cluster.

tsh ls

Now verify the enabled application on Teleport CLuster via the tsh command below.

tsh apps ls

In the output, you should see one node is available on the Teleport Cluster (teleport-server) and the application 'teleport-webapp' is enabled.

Next, you can also log in to nodes that are available on the Teleport Cluster via the tsh command as below. With this, you'll be logging into the 'teleport-server' via the tsh command with the user 'root' or/and 'debian'.

tsh ssh root@teleport-server
tsh ssh debian@teleport-server

You should see the output like the following - With both tsh commands you have successfully logged in to the 'teleport-server' via the tsh command.

For the tctl command, you should run with sudo at the beginning. Run the below tctl command to check available nodes/servers on the Teleport Cluster.

sudo tctl nodes ls

In the next step, you'll learn how to add Nodes/Servers to the Teleport Cluster via two different methods, automatically via the web administration dashboard or manually via the command line.

Adding Nodes to the Teleport Cluster

To add nodes/servers to the Teleport Cluster, you must ensure that the server is reachable. And you can use two different methods to add Nodes/Servers to your Teleport Cluster.

You can use Teleport as the control plane management for different services such as servers, Kubernetes Cluster, Database Server, Applictaions, and Desktops.

In this step, you'll add two different servers to the Teleport CLuster. You'll add the machine 'client1' via the installer script that will be generated from the web administration dashboard, and add the 'client2' machine manually via the command line.

Adding client1 via Installer Script

First, back to the Teleport web administration dashboard and click the ADD SERVER button.

Select the resource type you want to add. You can add Kubernetes Cluster, Database servers, Applications, and Desktops. Select SERVERS to add resource type server and click NEXT.

Now you'll see the generated installer script and command line that can be used to add the 'client1' machine. Copy that generated command line.

Now log in to the 'client1' machine, access the root privileges via the sudo command, then paste and run the generated command line on the 'client1' machine. This will download the generated script to the 'client1' machine and run the script.

You'll receive a similar output like this on your terminal - The installer script will add the 'client1' machine by using the generated token and the ca pin of the Teleport Cluster. Also, the installer script will automatically detect your current operating system, install the Teleport package automatically, and generates the Teleport configuration '/etc/teleport.yaml' file.

After the process is finished, you should receive the output like this. The Teleport service on the 'client1' machine also automatically started and enabled.

Now back to the Teleport web administration dashboard and you should see a message such as 'The server successfully joined this Teleport cluster'. Click NEXT to continue.