Installing Teleport: Overview
Length: 03:04
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 System | teleport Daemon | tctl Admin Tool | tsh 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] | yes | yes | yes | yes | yes |
macOS v10.13+ (High Sierra) | yes | yes | yes | yes | yes |
Windows 10+ (rev. 1607) [4] | no | no | yes | yes | no |
[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 thehistory
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.ascSource variables about OS version
source /etc/os-releaseAdd 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/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd 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 teleportTip: 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.gzshasum -a 256 teleport-v11.3.2-linux--bin.tar.gzVerify that the checksums match
tar -xvf teleport-v11.3.2-linux--bin.tar.gzcd teleportsudo ./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_.debSelecting 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..rpmwarning: 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.gzshasum -a 256 teleport-ent-v11.3.2-linux--bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v11.3.2-linux--bin.tar.gzcd teleport-entsudo ./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.gzshasum -a 256 teleport-ent-v11.3.2-linux--fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v11.3.2-linux--fips-bin.tar.gzcd teleport-entsudo ./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_.debSelecting 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..rpmwarning: 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.gzshasum -a 256 teleport-ent-v11.2.1-linux-amd64-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v11.2.1-linux-amd64-bin.tar.gzcd teleport-entsudo ./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 name | Teleport version | Image automatically updated? | Image base |
---|---|---|---|
public.ecr.aws/gravitational/teleport:11 | The latest version of Teleport Open Source | Yes | Ubuntu 20.04 |
public.ecr.aws/gravitational/teleport:11.3.2 | The version specified in the image's tag (i.e. 11.3.2) | No | Ubuntu 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 name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Image base |
---|---|---|---|---|
public.ecr.aws/gravitational/teleport-ent:11 | Enterprise | The latest version of Teleport Enterprise 11 | Yes | Ubuntu 20.04 |
public.ecr.aws/gravitational/teleport-ent:11-fips | Enterprise FIPS | The latest version of Teleport Enterprise 11 FIPS | Yes | Ubuntu 20.04 |
public.ecr.aws/gravitational/teleport-ent:11.3.2 | Enterprise | The version specified in the image's tag (i.e. 11.3.2) | No | Ubuntu 20.04 |
public.ecr.aws/gravitational/teleport-ent:11.3.2-fips | Enterprise FIPS | The version specified in the image's tag (i.e. 11.3.2) | No | Ubuntu 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.
Chart | Included Services | Values Reference |
---|---|---|
teleport-cluster | Auth Service Proxy Service Other Teleport services if using a custom configuration | Reference |
teleport-kube-agent | Kubernetes Service Application Service Database Service | Reference |
macOS
You can download one of the following .pkg installers for macOS:
Link | Binaries |
---|---|
teleport-11.3.2.pkg | teleport tctl tsh tbot |
tsh-11.3.2.pkg | tsh |
You can also fetch an installer via the command line:
curl -O https://cdn.teleport.dev/teleport-11.3.2.pkgInstalls 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 statustctl 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 versionTeleport v11.3.2 git:v11.3.2 go1.19
Get your local tctl version:
tctl versionTeleport 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.sha256PowerShell 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.zipcertUtil -hashfile teleport-v11.3.2-windows-amd64-bin.zip SHA256SHA256 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.zipcd teleport-v11.3.2-windows-amd64-bin\teleport.\tsh.exe versionTeleport 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.
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=amd64curl 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: