Installation

This guide shows you how to install Teleport binaries on your platform, including:

• teleport
• tsh
• tctl
• tbot

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

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.

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

[1] Teleport is written in Go and many of these system requirements are due to the requirements of the Go 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.

Feature support

Some Teleport features have additional requirements:

Installation instructions

Select an edition, then follow the instructions for that edition to install Teleport.

curl https://goteleport.com/static/install.sh | bash -s 14.0.1

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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
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

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

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

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

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 v14. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent

sudo apt-get install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"
sudo yum install teleport-ent
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

sudo yum install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")
sudo yum install teleport-ent
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

sudo yum install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v14. You'll need to update this
file for each major release of Teleport.
First, get the major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"

Install teleport
sudo dnf install teleport-ent

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

sudo dnf install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent

sudo zypper install teleport-ent-fips

curl https://get.gravitational.com/teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

curl https://get.gravitational.com/teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v14.0.1-linux-$SYSTEM_ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"
sudo yum install teleport-ent-updater
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

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

Install teleport
sudo dnf install teleport-ent-updater

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

Source variables about OS version
source /etc/os-release
Add the Teleport Zypper repository for cloud.
First, get the OS major version from $VERSION_ID so this fetches the correct
package version.
VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
Use Zypper to add the teleport RPM repo
sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

Install teleport
sudo zypper install teleport-ent-updater

Docker

Images

We provide a pre-built Docker image for every version of Teleport. This section describes the available Docker images.

These images are hosted on Amazon ECR Public.

Image suffixes

For each of the image names listed in this section, you can specify attributes of the image by appending a suffix to the repository name or tag.

Images with the -distroless suffix within the repository name include only the teleport binary and its runtime dependencies, with no shell or utility applications. An example is public.ecr.aws/gravitational/teleport-distroless for Teleport Community Edition.

Images with the *-distroless-debug suffix within the repository name include a Busybox shell and tool suite in addition to Teleport, and are intended for troubleshooting deployments only. They are not intended for production use. An example is public.ecr.aws/gravitational/teleport-distroless-debug.

You can specify the architecture of an image by appending a suffix to its tag. We support the following architecture suffixes: amd64, arm, and arm64. For example, if you want to pull the ARM64 image for public.ecr.aws/gravitational/teleport, you can use public.ecr.aws/gravitational/teleport:14.0.1-arm64.

*-distroless and *-distroless-debug images support multiple architectures natively, and do not require (or support) image suffixes. You can specify an architecture using the --platform flag of docker pull to pull the arm, arm64 or amd64 version of an image.

Version tags

Images point to a static version of Teleport. Use the image's tag to specify either:

• The major, minor, and patch version (e.g., 14.0.1 for the latest version of Teleport Community Edition).
• The major version only, which implies the latest minor and patch numbers for that major version. For example, 14 implies 14.0.1.

Running Teleport on Docker

When running a container from one of the images listed above, consider the container equivalent to running the teleport binary. The Teleport container requires access to a file system and network ports.

Configuration

Teleport processes read their configuration from a local file path, which is /etc/teleport.yaml by default. Make sure this file path is mounted to your Teleport container.

Data directory

All Teleport processes read from and write to a data directory, which by default is /var/lib/teleport. Make sure the data directory is mounted to your Teleport container.

License file

If your Teleport Enterprise container runs the Auth Service, you will need to give it access to a license file at the path named in the configuration, which is /var/lib/teleport/license.pem by default. Make sure a license exists at this location in the Teleport container's data directory.

Other file paths

Depending on the configuration settings you assign on your Teleport container, you will need to make sure that any file paths you name are mounted on the container.

For example, if you are running the Teleport Proxy Service on a container, you need to mount the directory containing TLS credentials to your Teleport container, then assign the following fields in the container's configuration file to the appropriate paths:

proxy_service:
  https_keypairs:
  - key_file: /my/path/key.pem
    cert_file: /my/path/cert.pem

See the Teleport Configuration Reference for whether a field you would like to assign requires a file path.

Ports

A single Teleport process can run multiple services, each of which listens on a specific set of ports depending on your configuration. See our Networking Reference for the ports on your Teleport container to expose.

Extracting certificates from distroless images

Extracting certificates created with tctl auth sign from a container running a distroless image can be tricky due to the absence of a shell and other OS tools.

Where possible you should log into the Teleport cluster using tsh and use tctl auth sign locally to generate certificates. This way the action will be logged against your Teleport user and be subject to all of the usual Teleport RBAC policies in your cluster.

If this is not possible, use tctl auth sign --tar to collect all the files generated by tctl auth sign into a tar archive, which is streamed directly to stdout. The resulting certificates are never stored on the container filesystem. You can either pipe this output directly to tar, or redirect it to a local file for later use.

For example:

docker exec ${TELEPORT_CONTAINER} \  tctl auth sign --user alice --format tls -o alice.local --tar | tar xvx alice.local.crtx alice.local.keyx alice.local.cas

Example of running a Teleport container

In this example, we will show you how to run the Teleport Auth and Proxy Services on a local Docker container using Teleport Community Edition.

Since this container uses a self-signed certificate, we do not recommend using this configuration to protect any infrastructure outside your workstation. You can, however, join other local Docker containers to it using the token method.

First, create directories in your home directory to mount to the container. The Teleport container will write its configuration and data to these directories:

mkdir -p ~/teleport/config ~/teleport/data

Run teleport configure from the Teleport container to generate a configuration file. This sets the container's name to localhost so your browser can trust the Proxy Service's self-signed TLS certificate:

docker run --hostname localhost --rm \  --entrypoint=/usr/local/bin/teleport \  public.ecr.aws/gravitational/teleport-distroless:14.0.1 configure --roles=proxy,auth > ~/teleport/config/teleport.yaml

Start Teleport on your container:

docker run --hostname localhost --name teleport \  -v ~/teleport/config:/etc/teleport \  -v ~/teleport/data:/var/lib/teleport \  -p 3025:3025 -p 3080:3080 \  public.ecr.aws/gravitational/teleport-distroless:14.0.1

From there, open another terminal and make sure your Teleport container's web API is functioning as intended:

curl --insecure https://localhost:3080/webapi/ping

You should see JSON output similar to the following:

{
  "auth": {
    "type": "local",
    "second_factor": "otp",
    "preferred_local_mfa": "otp",
    "local": {
      "name": ""
    },
    "private_key_policy": "none",
    "device_trust_disabled": true,
    "has_motd": false
  },
  "proxy": {
    "kube": {
      "enabled": true,
      "listen_addr": "0.0.0.0:3080"
    },
    "ssh": {
      "listen_addr": "0.0.0.0:3080",
      "tunnel_listen_addr": "0.0.0.0:3080",
      "web_listen_addr": "0.0.0.0:3080"
    },
    "db": {
      "postgres_listen_addr": "0.0.0.0:3080",
      "mysql_listen_addr": "0.0.0.0:3080"
    },
    "tls_routing_enabled": true
  },
  "server_version": "12.1.5",
  "min_client_version": "11.0.0",
  "cluster_name": "localhost",
  "automatic_upgrades": false
}

We are using the --insecure flag to trust Teleport's self-signed certificate. In production, you will want to provision TLS credentials to the Proxy Service from a trusted CA, e.g., Let's Encrypt.

Amazon EC2

We provide pre-built amd64 Amazon Linux 2023 based EC2 AMIs with Teleport pre-installed.

These images are primarily intended for deploying a Teleport cluster using our reference Terraform code.

See the Starter Cluster Terraform and the Running Teleport Enterprise in High Availability mode on AWS guide for detailed usage examples.

In order to use these AMIs outside of the reference Terraform, you can configure the Teleport installation by setting configuration variables in the /etc/teleport.d/conf file on the EC2 instance. See the Starter Cluster Configuration Template for a list of the available configuration options.

The image names all include the build timestamp (shown as $TIMESTAMP in the table below), and are tagged for easier searching.

All images are based on Amazon Linux 2023 and have been hardened using the Amazon EC2 ImageBuilder STIG hardening component.

Teleport AMIs are automatically published to all non-opt-in AWS regions.

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.

macOS

curl -O https://cdn.teleport.dev/teleport-14.0.1.pkg
Installs on Macintosh HD
sudo installer -pkg teleport-14.0.1.pkg -target /
Password:
installer: Package name is teleport-14.0.1
installer: Upgrading at base path /
installer: The upgrade was successful.
which teleport
/usr/local/bin/teleport

brew install teleport

curl -O https://cdn.teleport.dev/teleport-ent-14.0.1.pkg
Install on Macintosh HD
sudo installer -pkg teleport-ent-14.0.1.pkg -target /
Password:installer: Package name is teleport-ent-14.0.1installer: Upgrading at base path /installer: The upgrade was successful.
which teleport
/usr/local/bin/teleport

Windows (tsh client only)

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 (these commands will not work in cmd.exe):

Set the TLS level to TLS 1.2 (required on Windows Server 2016 and lower)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Get the expected checksum for the Windows tsh package
$Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v14.0.1-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>
Invoke-WebRequest -OutFile teleport-v14.0.1-windows-amd64-bin.zip -Uri https://cdn.teleport.dev/teleport-v14.0.1-windows-amd64-bin.zip
certUtil -hashfile teleport-v14.0.1-windows-amd64-bin.zip SHA256
SHA256 hash of teleport-v14.0.1-windows-amd64-bin.zip:
<checksum>
CertUtil: -hashfile command completed successfully.

Expand-Archive teleport-v{{ .version }}-windows-amd64-bin.zip
cd teleport-v14.0.1-windows-amd64-bin\teleport
.\tsh.exe version
Teleport v14.0.1 git:v{{ .version }} go1.21

Set the TLS level to TLS 1.2 (required on Windows Server 2016 and lower)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Get the expected checksum for the Windows tsh package
$Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v14.0.1-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>
Invoke-WebRequest -OutFile teleport-v14.0.1-windows-amd64-bin.zip -Uri https://cdn.teleport.dev/teleport-v14.0.1-windows-amd64-bin.zip
certUtil -hashfile teleport-v14.0.1-windows-amd64-bin.zip SHA256
SHA256 hash of teleport-v14.0.1-windows-amd64-bin.zip:
<checksum>
CertUtil: -hashfile command completed successfully.

Expand-Archive teleport-v{{ .version }}-windows-amd64-bin.zip
cd teleport-v14.0.1-windows-amd64-bin\teleport
.\tsh.exe version
Teleport v14.0.1 git:v{{ .version }} go1.21

Set the TLS level to TLS 1.2 (required on Windows Server 2016 and lower)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Get the expected checksum for the Windows tsh package
$Resp = Invoke-WebRequest https://get.gravitational.com/teleport-v14.0.1-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>
Invoke-WebRequest -OutFile teleport-v14.0.1-windows-amd64-bin.zip -Uri https://cdn.teleport.dev/teleport-v14.0.1-windows-amd64-bin.zip
certUtil -hashfile teleport-v14.0.1-windows-amd64-bin.zip SHA256
SHA256 hash of teleport-v14.0.1-windows-amd64-bin.zip:
<checksum>
CertUtil: -hashfile command completed successfully.

Expand-Archive teleport-v{{ .version }}-windows-amd64-bin.zip
cd teleport-v14.0.1-windows-amd64-bin\teleport
.\tsh.exe version
Teleport v14.0.1 git:v{{ .version }} go1.21

Building from source

Teleport is written in Go, and currently requires go v1.21 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.

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=v14.0.1
'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>

Uninstalling Teleport

If you wish to uninstall Teleport at any time, see our documentation on Uninstalling Teleport.

Next steps

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

• Server Access
• Kubernetes Access
• Database Access
• Application Access
• Desktop Access
• Machine ID