Skip to main content

Installing Teleport on Linux

Report an Issue

This guide explains how to install the teleport binary on a single Linux machine.

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 Installing Teleport as an agent.

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 control plane components​

This section only applies to self-hosted Teleport deployments. If you have a Teleport Cloud account, or only want to deploy Teleport Agents, read Installing Teleport as an agent.

To install the teleport binary on an individual machine in order to run the Teleport Auth Service or Proxy Service, you can fetch a one-line installation script, which finds an appropriate package manager and uses it to install the teleport package.

tip

If you are self-hosting a Teleport cluster, 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 Self-Hosted Teleport Enterprise.

Execute the one-line installation script​

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 "19.0.0-dev" "enterprise"

Verify control plane component 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.

Configure your Teleport installation​

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 installation script to run on Linux hosts.

Outside of the Web UI, you can run a cluster-specific installation 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. You can also use the teleport-update binary to keep agents up to date.

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.

For an example Terraform module for deploying and configuring Teleport Agents, see Deploy Agents with Terraform.

Run the cluster-specific installation script​

Outside of the Web UI, you can run a 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.

  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

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.

Configure your Teleport Agent​

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.

If it is not possible to use the one-line installation script, for example if you are setting up custom tooling, you can install the teleport binary on a single machine by fetching packages or TAR archives. You can also download a Teleport package from the Teleport Web UI.

Package repositories​

Read the instructions in this section for instructions on working with Teleport package repositories.

  1. Assign the following environment variables in the terminal where you will run Teleport installation commands, indicating the package and version to install:

    export TELEPORT_PKG=teleport-ent
    export TELEPORT_VERSION=v19
    export TELEPORT_CHANNEL=stable/${TELEPORT_VERSION?}

    For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

    export TELEPORT_PKG=teleport-ent-fips

  2. Teleport maintains DEB and RPM package repositories for different Linux distributions based on variables defined in /etc/os-release on Linux systems. Source this file to define the variables:

    . /etc/os-release && echo "$NAME $VERSION_ID"

    Checkpoint: Verify OS release variables

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

  3. 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
    RHEL 10 Support

    Teleport does not currently provide a YUM repository for RHEL 10. Attempting to follow the standard YUM installation instructions on RHEL 10 will result in HTTP 404 errors. To install Teleport on RHEL 10, use a one-line installation script (for Teleport Agents or for Teleport control plane components) for the initial setup and Managed Updates v2 to maintain the installation.

  4. If ID is not listed, check:

    echo $ID_LIKE

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

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

  6. Verify the installation by running the following command:

    teleport version

    Checkpoint: Troubleshoot repository installation issues

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

Downloading packages and TAR archives​

Teleport maintains TAR archives as well as DEB and RPM packages for Linux-compatible binaries at https://cdn.teleport.dev. This section explains how to install Teleport by manually downloading a release.

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

  1. Use environment variables to set the package name, version, and architecture of the package you want to download:

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

  2. Determine your system architecture:

    uname -m

    Map the CPU architecture to a supported build:

    uname -m outputSYSTEM_ARCH value
    x86_64amd64
    aarch64arm64
    armv7larm
    i686386

  3. Assign version and architecture variables:

    TELEPORT_VERSION=19.0.0-dev
    SYSTEM_ARCH=""

  4. Download and install using your preferred format. These steps use sha256sum, which is available by default on most modern Linux distributions. On older systems where sha256sum is not available, use shasum --check --algorithm 256 instead:

    curl -O https://cdn.teleport.dev/${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz.sha256
    curl -O https://cdn.teleport.dev/${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz
    sha256sum --check < ${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz.sha256
    teleport-ent-v18.7.1-linux-amd64-bin.tar.gz: OK
    tar -xvf ${TELEPORT_PKG?}-v${TELEPORT_VERSION?}-linux-${SYSTEM_ARCH?}-bin.tar.gz
    cd ${TELEPORT_PKG?}
    sudo ./teleport-update enable --proxy example.teleport.sh # or sudo ./install for static installation

  5. Verify the installation. Run the following command:

    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.