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 --user=email@example.com
  $ 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:

1. Install the latest Teleport version on the host.

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

   Teleport Community Edition

   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

   Teleport Enterprise

   Debian 9+/Ubuntu 16.04+ (apt)

   # 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

   Amazon Linux 2/RHEL 7 (yum)

   # 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

   Amazon Linux 2/RHEL 7 (zypper)

   # 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

   Amazon Linux 2023/RHEL 8+ (dnf)

   # 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

   SLES 12 SP5+ and 15 SP5+ (zypper)

   # 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

   Tarball

   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

2. Confirm that the version of the teleport binary is the one you expect:

   $ teleport version

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

   On the host where you will run your Teleport instance, enable and start Teleport:

   $ sudo systemctl enable teleport
   $ sudo systemctl start teleport

   TAR Archive

   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.