Skip to main content
Version: 17.x

Installing Teleport on Linux

Report an Issue

Teleport maintains DEB and RPM package repositories for different operating systems, platforms, and Teleport versions. A server that installs Teleport from a DEB or RPM package must have systemd installed. You can also download TAR archives containing Teleport binaries.

Note that Teleport Agents should always use the one-line installation script or teleport-update binary to install Teleport. Otherwise, they will fall out-of-date, become incompatible with the cluster, and eventually disconnect.

Operating system support​

Operating Systemteleport Daemontctl Admin Tooltsh and Teleport Connect User Clients [1]Web UI (via the browser)tbot Daemon
Linux 3.2+ (RHEL/CentOS 7+, Rocky Linux 8+, Amazon Linux 2+, Amazon Linux 2023+, Ubuntu 16.04+, Debian 9+, SLES 12 SP 5+, and SLES 15 SP 5+) [2]yesyesyes [3]yesyes

[1] tsh is a Command Line Client (CLI) and Teleport Connect is a Graphical User Interface (GUI) desktop client. See Using Teleport Connect for usage and installation.

[2] Enhanced Session Recording requires Linux kernel v5.8+.

[3] Teleport Connect on Linux requires glibc 2.28+ present in Ubuntu 20.04+, Debian 10+, Fedora 37+.

For best results, Teleport clients (tsh, tctl, tbot) should be the same major version as the cluster they are connecting to. Teleport servers are compatible with clients that are on the same major version or one major version older. Teleport servers do not support clients that are on a newer major version. See our Upgrading guide for more information.

Installing Teleport as a cluster​

These steps are specifically for the Teleport Enterprise (Self-Hosted) and Community Edition versions.

If you are starting out with Teleport, we recommend beginning with a Teleport Cloud account. From there, the only Teleport components you need to deploy yourself are Teleport Agents, which is discussed in the next section. If you are self-hosting a Teleport cluster, please take a look at our Linux Demo for the Teleport Community Edition or our Self-Hosting Teleport section in the docs for more information on Teleport Enterprise Self-Hosted.

TELEPORT_EDITION="enterprise"
TELEPORT_VERSION="17.7.20"

Then, download and run the generic installation script on the server where you want to install Teleport:

curl https://cdn.teleport.dev/install.sh | bash -s ${TELEPORT_VERSION?} ${TELEPORT_EDITION?}

Verify cluster installation​

Run the following command to verify your installation:

teleport version

You should see output displaying the Teleport version number.

Checkpoint: Troubleshoot cluster installation issues

Success looks like: The system identifies the Teleport binary and returns a valid version number.

Cluster configuration​

The above methods for installing Teleport on a Linux server do not generate a Teleport configuration file for you. For this, we have a teleport configure CLI command or you can create one manually.

See the following guides for help setting up a configuration file:

  • Teleport Configuration Reference: This will provide you with the command you need to generate and populate the /etc/config.yaml file as well as further configuration options for your cluster.
  • Self-Hosted Demo Cluster: If you are deploying the Teleport Auth Service and Proxy Service, read this guide for an example of a configuration file.

Installing Teleport as an agent​

The easiest way to install Teleport as an agent is through the Web UI at /web/discover, where you can select a resource to enroll with your Teleport cluster and retrieve an "all-in-one" installation script to run on Linux hosts.

One-line installation script​

Outside of the WebUI, you can run our one-line cluster install script on your Linux server where you are deploying Teleport as an agent. This script will detect and use the best version, edition, and installation mode for your cluster. Note that this is script is for Teleport versions 17.3 and above. If you are installing a version before this edition or this script does not work on your server, see below for other options.

  1. Assign example.teleport.sh:443 to your Teleport cluster hostname and Web UI port. This should contain your cluster hostname and port, but not the scheme (https://).
  2. Run your cluster's install script:
curl "https://example.teleport.sh:443/scripts/install.sh" | sudo bash

You can also use the example Terraform module for deploying agents in Deploy Agents with Terraform.

Verify agent installation​

Run the following commands to verify your agent installation:

teleport version
sudo systemctl status teleport

You should see the Teleport version and a status showing the service is active and running.

Checkpoint: Troubleshoot agent installation issues

Success looks like: The Teleport version is displayed and the service status is reported as active and running.

Agent configuration​

Outside of deploying Teleport as an agent in the Web UI, the methods for installing Teleport on a Linux server do not generate a Teleport configuration file for you. You will need to generate one prior to starting the Teleport service.

See the following guides for examples of setting up a configuration file:

  • Enroll Resources: Guides to setting up Teleport Agents in order to enroll infrastructure resources in your cluster. These guides include examples of setting up Teleport configuration files.
  • Self-Hosted Demo Cluster: If you are deploying the Teleport Auth Service and Proxy Service, read this guide for an example of a configuration file.
  • Teleport Configuration Reference: A guide to all configuration fields.

Other install methods​

Use this section if you are not using the one-line installation script.

Choose one of the following methods:

  • Install using package repositories
  • Install manually (TAR, DEB, RPM)

Install using package repositories​

Use this method to install Teleport through your system's package manager.

Source OS release variables​

  1. Run:

    source /etc/os-release

    Checkpoint: Verify OS release variables

    Success looks like: The output displays valid identifiers for your distribution and version.

    Verify your distribution is supported​

  2. Confirm that your distribution appears in the table below.

    DistributionVersionID value in /etc/os-release
    Amazon Linux2 and 2023amzn
    CentOS>= 7centos
    Debian>= 9debian
    RHEL>= 7rhel
    Rocky Linux>= 8rocky
    SLES>= 12 SP5, >= 15 SP5sles
    Ubuntu>= 16.04ubuntu

  3. If ID is not listed, check:

    echo $ID_LIKE

    If one of those values appears in the table, use it instead.

    Set required environment variables​

  4. Assign the package name and release channel:

    export TELEPORT_PKG=teleport        # Community Edition
    export TELEPORT_PKG=teleport-ent    # Enterprise
    export TELEPORT_VERSION=v17
    export TELEPORT_CHANNEL=stable/${TELEPORT_VERSION?}

    Install Teleport via package manager​

  5. Follow the instructions for your package manager:

    sudo mkdir -p /etc/apt/keyrings
    sudo curl https://apt.releases.teleport.dev/gpg \  -o /etc/apt/keyrings/teleport-archive-keyring.asc

    echo "deb [signed-by=/etc/apt/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} \${TELEPORT_CHANNEL?}" \  | sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

    sudo apt-get update
    sudo apt-get install ${TELEPORT_PKG?}

    Verify the installation​

  6. Run:

    teleport version

    Checkpoint: Troubleshoot repository installation issues

    Success looks like: The package manager confirms installation and the version command returns successfully.

Install manually (TAR, DEB, RPM)​

Use this method if you prefer to install from release archives or operate in restricted environments.

Set the package name​

  1. Assign the appropriate package:

    TELEPORT_PKG=teleport        # Community Edition
    TELEPORT_PKG=teleport-ent    # Enterprise

    Set the version and architecture​

  2. Assign version and architecture variables:

    TELEPORT_VERSION=17.7.20
    SYSTEM_ARCH=""

  3. Determine your system architecture:

    uname -m

    Map it to a supported build:

    uname -m outputSYSTEM_ARCH value
    x86_64amd64
    aarch64arm64
    armv7larm
    i686386

    Checkpoint: Verify system architecture

    Success looks like: The architecture matches the Teleport build you download.

    Download and install​

  4. Download and install using your preferred format:

    curl -O https://cdn.teleport.dev/${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz
    tar -xvf ${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz
    cd ${TELEPORT_PKG?}
    sudo ./install
    sudo teleport install systemd -o /etc/systemd/system/teleport.service
    sudo ./teleport-update enable --proxy example.teleport.sh

    Verify the installation​

  5. Run:

    teleport version

    Checkpoint: Troubleshoot manual installation issues

    Success looks like: Teleport binaries are accessible from your system path and the version command executes successfully.

From your browser​

For Teleport Community Edition, check the Downloads page for the most up-to-date information.

On cloud-hosted Teleport Enterprise you can visit a download page in the Web UI. Select the user name in the upper right and select Downloads from the menu.

Customers who self-host Teleport Enterprise can access Enterprise downloads and their license file from their dedicated account dashboard.