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.

install basic packages

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.

setup repo

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

sudo apt install teleport

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.hwdomain.io' for the Teleport deployment and SSL certificates generated in the '/etc/letsencrypt/live/tele.hwdomain.io/' 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.hwdomain.io \
--public-addr=tele.hwdomain.io:443 \
--cert-file=/etc/letsencrypt/live/tele.hwdomain.io/fullchain.pem \
--key-file=/etc/letsencrypt/live/tele.hwdomain.io/privkey.pem

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

initialize teleport

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.hwdomain.io'.

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

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

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

status teleport

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.hwdomain.io/).

You should now get the Teleport web service login page.

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

setup teleport user

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.

setup user

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

setup user password

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.

setup 2fa user

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.

user finished

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.

teleport administration dashboard

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.hwdomain.io' with the user 'teleport-admin'.

tsh login --proxy=tele.hwdomain.io --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.

login via cli

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.

list server and apps

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 [email protected]
tsh ssh [email protected]

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.

ssh via teleport

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.

add servers

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.

select type resource

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.

installer script generated

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.

run installer script on client1

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

node added

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.

client1 added

Now input the usernames that are allowed to access the 'client1' machine. Ensure users are available and created on the 'client1' machine. Click NEXT again to continue.

setup user to login

Lastly, you can verify the connections to the 'client1' machine by using the steps available on the web administration dashboard.

  • First, select the user that you want to use to log in.
  • Secondly, click the TEST SERVER button on 'Step 2' and ensure all tests are checked/marked as complete.
  • Lastly, click the START SESSION button that will automatically open a new tab on your web browser and access the 'client1' machine via the selected user.

Below is the screenshot of the 'Test Connection' section with the status successful.

test connectionm

Below is the screenshot after logging in to the 'client1' machine via the START SESSION in Step 3.

access session

Click FINISH to complete the processes.

You'll then be redirected to the Teleport web administration dashboard and you should see that the 'client1' machine is added to the Teleport Cluster.

client1 added

You can also verify the list of nodes/servers on the Teleport Cluster via the tsh and tctl command lines.

Back to the 'teleport-server' and run the below command to verify the list of nodes/servers on the Teleport Cluster.

tsh ls
sudo tctl nodes ls

You should receive the output similar to this - The client1 machine is available and added to the Teleport Cluster.

verify via cli

Lastly, run the below tsh command to log in to the client1 machine as the user 'debian'. You should now be logged in to the 'client1' machine via Teleport.

tsh ssh [email protected]

Below is the terminal screen after mogged into the client1 machine via Teleport.

connect via teleport

With this in mind, you have now successfully added the 'client1' node/server to the Teleport Cluster automatically via the installer script generated from the Teleport web administration dashboard.

Adding client2 node Manually

Run the below command to check the 'CA pin' fingerprint of your Teleport Cluster. The 'CA pin' fingerprint will be used to add the 'client2 machine.

sudo tctl status

Below is a similar output you should receive - Be sure to copy the 'CA pin' fingerprint.

check ca pin

Next, run the below tctl command to generate a new token that the client2 machine will use to join the Teleport Cluster. Then, verify the list of tokens on your Teleport Cluster.

sudo tctl nodes add --ttl=30m --roles=node | grep "invite token:" | grep -Eo "[0-9a-z]{32}"
sudo tctl token ls

You should receive a similar output to this - Be sure to copy the generated token that the client2 machine will use to join the Teleport Cluster.

generate token

Now connect to the 'client2' machine and install the Teleport package via APT.

Run the below command to add the Teleport repository to the 'client2 machine.

Load environment variables on the '/etc/os-release' file.

source /etc/os-release

Add the Teleport GPG key and repository.

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

setup repo

Now run the below apt command to update and refresh your system package index. Then, install Teleport via the below apt command.

sudo apt update
sudo apt install teleport

The Teleport installation should now begin.

install teleport

After installing the Teleport package, create a new Teleport configuration file '/etc/teleport.yaml' using the below nano editor command.

sudo nano /etc/teleport.yaml

Add the following Teleport configurations to the file. Be sure to change the namenode with the machine hostname, the token_name with your generated token, the proxy_server with the domain name of your Teleport Cluster, and the ca_pin with the Teleport Cluster CA pin fingerprint.

version: v3
teleport:
  nodename: client2
  data_dir: /var/lib/teleport
  join_params:
    token_name: 361b76eac6360da13f1a202fa8164024
    method: token
  proxy_server: tele.hwdomain.io:443
  log:
    output: stderr
    severity: INFO
    format:
      output: text
  ca_pin: sha256:2c96568d7bfa05f0a32b7681eb31b52a5c2a3414274579cbe9ece23e0b5e5443
  diag_addr: ""
auth_service:
  enabled: "no"
ssh_service:
  enabled: "yes"
  commands:
  - name: hostname
    command: [hostname]
    period: 1m0s
proxy_service:
  enabled: "no"
  https_keypairs: []
  acme: {}

Save the file and exit the editor when finished.

Next, run the below systemctl command utility to start and enable the Teleport service on the client2 machine.

sudo systemctl start teleport
sudo systemctl enable teleport

Then verify the Teleport service via the below command.

sudo systemctl status teleport

You should receive the output similar to the following screenshot - The Teleport service on the client2 machine is configured and it's running and enabled.

setup client

Now back to the 'teleport-server' terminal to verify the list of available nodes/servers from there. Run the below command to check the list of nodes on the Teleport Cluster

sudo tctl nodes ls

You should see the client2 machine is available and added to the Teleport Cluster.

verify client2

Next, run the below tsh command to access the client2 machine via Teleport SSH. You should now be logged in to the client2 machine via Teleport. Ensure that the 'debian' user is available on the client2 machine.

tsh ssh [email protected]

Below is the output you should get after logging in to the client2 machine via Teleport.

connect via tsh

Now back to the Teleport web administration dashboard and you should see that the client2 machine is available on the Teleport Cluster.

verify via dashboard

Lastly, click the 'CONNECT' button on the 'client2' machine to start and connect to the 'client2'. You should now be logged in to the 'client2' machine via the Teleport web administration dashboard.

access session via web administration

With this in mind, you've now successfully added and configured the client2 machine manually by generating a Teleport token, using the CA pin fingerprint of the Teleport Cluster, installing the Teleport package, and creating a Teleport configuration file.

Conclusion

Your server infrastructure is now secured via Teleport Cluster, and You can now disable SSH services on every node and allow only access from the Teleport Server. You have now learned how to install Teleport Cluster on a Debian 11 system and learned the basic configuration to set up Teleport.

You have also learned how to set up Teleport users with Two Factor Authentication enabled and learned how to use Teleport command lines (tsh and tctl) for managing Teleport Cluster.

Lastly, you've successfully configured and added two nodes client1 and client2 to the Teleport Cluster using two different methods. The first method is via the installer script generated by the Teleport web administration dashboard. The second method manually adds nodes/servers by installing and configuring Teleport on the target machine.

Share this page:

Suggested articles

2 Comment(s)

Add comment

Comments

By: Vuk at: 2023-01-18 14:06:57

This part is not working. ID parameter not set

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

By: arvid larsan at: 2023-01-19 09:34:06

it's working - You just forgot to run "source /etc/os-release" before adding repository.