Skip to main content

Version: 14.x

Upgrade Self-Hosted Teleport Clusters on Linux

This guide explains how to upgrade self-hosted Teleport clusters running on Linux servers.

Prerequisites

Familiarity with the Upgrading Compatibility Overview guide, which describes the sequence in which to upgrade components of your cluster.
A self-hosted Teleport cluster in which the Auth Service and Proxy Service run on Linux servers.

If you are running more than one Auth Service instance, you must reduce the size of the Auth Service instance pool to one in order to perform an upgrade.

The tctl and tsh client tools version >= 14.3.33.

$ tctl version
# Teleport v14.3.33 go1.21

$ tsh version
# Teleport v14.3.33 go1.21

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines.

For example:
```
$ tsh login --proxy=teleport.example.com [email protected]
$ tctl status
# Cluster  teleport.example.com
# Version  14.3.33
# CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Upgrade Teleport binaries

Complete the following steps on all servers that run the Auth Service and Proxy Service, then on each of your agents:

Install the latest Teleport version on the host.

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

Teleport Community Edition
Teleport Enterprise

The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

$ curl https://cdn.teleport.dev/install-v14.3.33.sh | bash -s 14.3.33

# 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

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

$ 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 install -y yum-utils
$ 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

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

$ 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

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

$ 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

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

$ 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

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

$ sudo zypper install teleport-ent-fips

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://cdn.teleport.dev/teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://cdn.teleport.dev/teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-bin.tar.gz
$ shasum -a 256 teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-bin.tar.gz
# Verify that the checksums match
$ tar -xvf teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-bin.tar.gz
$ cd teleport-ent
$ sudo ./install

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

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

OS repository channels

The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v14 anywhere in the Teleport documentation.

Channel name	Description
`stable/<major>`	Receives releases for the specified major release line, i.e. `v14`
`stable/cloud`	Rolling channel that receives releases compatible with current Cloud version
`stable/rolling`	Rolling channel that receives all published Teleport releases

Confirm that the version of the teleport binary is the one you expect:
```
$ teleport version
```
Now that you have installed a more recent teleport binary on your Auth Service and Proxy Service servers, restart Teleport on these servers to run the new version.

Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.
- Package Manager
- TAR Archive
On the host where you will run your Teleport instance, enable and start Teleport:
$ sudo systemctl enable teleport $ sudo systemctl start teleport
On the host where you will run your Teleport instance, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
$ sudo teleport install systemd -o /etc/systemd/system/teleport.service $ sudo systemctl enable teleport $ sudo systemctl start teleport
You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

Prerequisites
Upgrade Teleport binaries
- OS repository channels