Fork me on GitHub

Teleport

Installation

Improve
Installing Teleport: Overview

Installing Teleport: Overview

Length: 03:04

First time trying Teleport?

If you are new to Teleport, we recommend following our getting started guides.

Operating system support

Teleport is officially supported on the platforms listed below. It is worth noting that the open-source community has been successful in building and running Teleport on UNIX variants other than Linux [1].

Operating Systemteleport Daemontctl Admin Tooltsh and Teleport Connect User Clients [2]Web UI (via the browser)tbot Daemon
Linux v2.6.23+ (RHEL/CentOS 7+, Ubuntu 14.04+, and Debian 8+) [3]yesyesyesyesyes
macOS v10.13+ (High Sierra)yesyesyesyesyes
Windows 10+ (rev. 1607) [4]nonoyesyesno

[1] Teleport is written in Go and it's possible to build it on any OS supported by the Golang toolchain.

[2] 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.

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

[4] Teleport server does not run on Windows yet, but tsh and Teleport Connect (the Teleport desktop clients) supports most features on Windows 10 and later.

Linux

All installations include teleport, tsh, tctl, and tbot.

When running Teleport in production, we recommend that you follow the practices below to avoid security incidents. These practices may differ from the examples used in this guide, which are intended for demo environments:

  • Avoid using sudo in production environments unless it's necessary.
  • Create new, non-root, users and use test instances for experimenting with Teleport.
  • Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
  • Follow the "Principle of Least Privilege" (PoLP). Don't give users permissive roles when giving them more restrictive roles will do instead. For example, assign users the built-in access,editor roles.
  • When joining a Teleport resource service (e.g., the Database Service or Application Service) to a cluster, save the invitation token to a file. Otherwise, the token will be visible when examining the teleport command that started the agent, e.g., via the history command on a compromised system.

Next, use the appropriate commands for your environment to install your package.

Teleport Edition

Add the Teleport repository to your repository list:

Download Teleport's PGP public key

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

Source variables about OS version

source /etc/os-release

Add the Teleport APT repository for v11. You'll need to update this

file for each major release of Teleport.

Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67

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

sudo apt-get update
sudo apt-get install teleport

Source variables about OS version

source /etc/os-release

Add the Teleport YUM repository for v11. You'll need to update this

file for each major release of Teleport.

Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'

and the codename your distro was forked from instead of '$ID'

Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153

sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v11/teleport.repo")
sudo yum install teleport

Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)

echo "Defaults secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path

Optional: Use DNF on newer distributions

$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo

$ sudo dnf install teleport

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

curl https://get.gravitational.com/teleport-v11.3.2-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-v11.3.2-linux-
-bin.tar.gz
shasum -a 256 teleport-v11.3.2-linux-
-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-v11.3.2-linux-
-bin.tar.gz
cd teleport
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_11.3.2_
.deb

Selecting previously unselected package teleport-ent.

(Reading database ... 30810 files and directories currently installed.)

Preparing to unpack teleport-ent_11.3.2_$SYSTEM_ARCH.deb ...

Unpacking teleport-ent 11.3.2 ...

Setting up teleport-ent 11.3.2 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-11.3.2.
.rpm

warning: teleport-ent-11.3.2.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.3.2-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v11.3.2-linux-
-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.2-linux-
-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v11.3.2-linux-
-bin.tar.gz
cd teleport-ent
sudo ./install

For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

curl https://get.gravitational.com/teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz
cd teleport-ent
sudo ./install

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

dpkg -i ~/Downloads/teleport-ent_11.2.1_
.deb

Selecting previously unselected package teleport-ent.

(Reading database ... 30810 files and directories currently installed.)

Preparing to unpack teleport-ent_11.2.1_$SYSTEM_ARCH.deb ...

Unpacking teleport-ent 11.2.1 ...

Setting up teleport-ent 11.2.1 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

rpm -i ~/Downloads/teleport-ent-11.2.1.
.rpm

warning: teleport-ent-11.2.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.2.1-linux-
-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v11.2.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-ent-v11.2.1-linux-amd64-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v11.2.1-linux-amd64-bin.tar.gz
cd teleport-ent
sudo ./install

Before installing a teleport binary with a version besides v11, read our compatibility rules to ensure that the binary is compatible with Teleport Cloud.

When running multiple teleport binaries within a cluster, the following rules apply:

  • Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
  • Servers support clients that are 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
  • Proxy Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.

If you've previously installed Teleport via the APT repo at https://deb.releases.teleport.dev/, you can upgrade by re-running the "Debian/Ubuntu (DEB)" install instructions above.

We will also continue to maintain the legacy APT repo at https://deb.releases.teleport.dev/ for the foreseeable future.

Check the Downloads page for the most up-to-date information.

Docker

We provide pre-built amd64, arm, and arm64 Docker images for every version of Teleport.

These images are hosted on Amazon ECR Public. All tags under public.ecr.aws/gravitational/teleport are Teleport Open Source images. You can specify the architecture of a Teleport Docker image by adding a postfix to the image tag, e.g., public.ecr.aws/gravitational/teleport:11-arm64. Versions without an architecture postfix use the amd64 architecture, e.g., public.ecr.aws/gravitational/teleport:11.

The table below gives an idea of how our image naming scheme works. We offer images that point to a static version of Teleport as well as images that are automatically rebuilt every night. These nightly images point to the latest version of Teleport from the three most recent release branches. They are stable, and we recommend their use to keep your Teleport installation up to date.

Image nameTeleport versionImage automatically updated?Image base
public.ecr.aws/gravitational/teleport:11The latest version of Teleport Open SourceYesUbuntu 20.04
public.ecr.aws/gravitational/teleport:11.3.2The version specified in the image's tag (i.e. 11.3.2)NoUbuntu 20.04

For testing, we always recommend that you use the latest released version of Teleport, which is currently public.ecr.aws/gravitational/teleport:11.3.2.

For instructions on running containers with these images, see Getting started with Teleport using Docker.

We provide pre-built amd64, arm, and arm64 Docker images for every version of Teleport Enterprise.

This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are automatically rebuilt every night.

Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.

These images are hosted on our Amazon ECR Public repository. All tags under public.ecr.aws/gravitational/teleport-ent are Teleport Enterprise images. You can specify the architecture of a Teleport Docker image by adding a postfix to the image tag, e.g., public.ecr.aws/gravitational/teleport:11-arm64. Versions without an architecture postfix use the amd64 architecture, e.g., public.ecr.aws/gravitational/teleport:11.

Image nameOpen Source or Enterprise?Teleport versionImage automatically updated?Image base
public.ecr.aws/gravitational/teleport-ent:11EnterpriseThe latest version of Teleport Enterprise 11YesUbuntu 20.04
public.ecr.aws/gravitational/teleport-ent:11-fipsEnterprise FIPSThe latest version of Teleport Enterprise 11 FIPSYesUbuntu 20.04
public.ecr.aws/gravitational/teleport-ent:11.3.2EnterpriseThe version specified in the image's tag (i.e. 11.3.2)NoUbuntu 20.04
public.ecr.aws/gravitational/teleport-ent:11.3.2-fipsEnterprise FIPSThe version specified in the image's tag (i.e. 11.3.2)NoUbuntu 20.04

For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently public.ecr.aws/gravitational/teleport-ent:11.3.2.

For instructions on running containers with these images, see Teleport Enterprise using Docker.

Helm

To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add:

helm repo add teleport https://charts.releases.teleport.dev

To update the cache of charts from the remote repository, run helm repo update:

helm repo update

There are two charts available to install. Please see our guide for using each chart.

ChartIncluded ServicesValues Reference
teleport-clusterAuth Service
Proxy Service
Other Teleport services if using a custom configuration
Reference
teleport-kube-agentKubernetes Service
Application Service
Database Service
Reference

macOS

You can download one of the following .pkg installers for macOS:

LinkBinaries
teleport-11.3.2.pkgteleport
tctl
tsh
tbot
tsh-11.3.2.pkgtsh

You can also fetch an installer via the command line:

curl -O https://cdn.teleport.dev/teleport-11.3.2.pkg

Installs on Macintosh HD

sudo installer -pkg teleport-11.3.2.pkg -target /

Password:

installer: Package name is teleport-11.3.2

installer: Upgrading at base path /

installer: The upgrade was successful.

which teleport

/usr/local/bin/teleport

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 official Teleport packages.

Run the following command:

brew install teleport

If you choose to use Homebrew, you must verify that the versions of tsh and tctl you run on your local machine are compatible with the versions you run on your infrastructure. Homebrew usually ships the latest release of Teleport, which may be incompatible with older versions. See our compatibility policy for details.

Log in to your cluster:

tsh login --proxy=teleport.example.com --user=myuser

Get the version of your Teleport cluster:

tctl status

tctl status

Cluster teleport.example.com

Version 11.3.2

Host CA never updated

User CA never updated

Jwt CA never updated

CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

Get your local tsh version:

tsh version

Teleport v11.3.2 git:v11.3.2 go1.19

Get your local tctl version:

tctl version

Teleport v11.3.2 git:v11.3.2 go1.19

Windows (tsh client only)

Starting with Teleport v7.2.0, most tsh features are supported for Windows 10 1607+. The tsh ssh command can be run under cmd.exe, PowerShell, and Windows Terminal.

To install tsh on Windows, run the following commands in PowerShell:

Get the expected checksum for the Windows tsh package

$Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v11.3.2-windows-amd64-bin.zip.sha256

PowerShell will return the binary representation of the response content

by default, so you need to convert it to a string

[System.Text.Encoding]::UTF8.getstring($Resp.Content)

<checksum> <filename>

curl -O teleport-v11.3.2-windows-amd64-bin.zip https://get.gravitational.com/teleport-v11.3.2-windows-amd64-bin.zip
certUtil -hashfile teleport-v11.3.2-windows-amd64-bin.zip SHA256

SHA256 hash of teleport-v11.3.2-windows-amd64-bin.zip:

<checksum>

CertUtil: -hashfile command completed successfully.

After you have verified that the checksums match, you can extract the archive. The executable will be available at teleport-v11.3.2-windows-amd64-bin\teleport\tsh.exe.

Expand-Archive teleport-v11.3.2-windows-amd64-bin.zip
cd teleport-v11.3.2-windows-amd64-bin\teleport
.\tsh.exe version

Teleport v11.3.2 git:v11.3.2 go1.19

Make sure to move tsh.exe into your PATH.

Building from source

Teleport is written in Go, and currently requires go v1.19 or newer. Detailed instructions for building from source are available in the README.

Checksums

If you want to verify the integrity of a Teleport binary, SHA256 checksums are available for all downloads on our downloads page.

Teleport Checksum

If you download Teleport via an automated system, you can programmatically obtain the checksum by adding .sha256 to the download link. This is the method shown in the installation examples.

export version=v11.3.2

'darwin' 'linux' or 'windows'

export os=linux

'386' 'arm' on linux or 'amd64' for all distros

export arch=amd64
curl https://get.gravitational.com/teleport-$version-$os-$arch-bin.tar.gz.sha256

<checksum> <filename>

Next steps

Now that you know how to install Teleport, you can enable access to all of your infrastructure. Get started with: