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 >= 15.2.4. Read Installation for how to install these.

• 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 protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.4
  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 Edition

   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://goteleport.com/static/install.sh | bash -s 15.2.4

   • Debian 9+/Ubuntu 16.04+ (apt)
   • Amazon Linux 2/RHEL 7 (yum)
   • Amazon Linux 2/RHEL 7 (zypper)
   • Amazon Linux 2023/RHEL 8+ (dnf)
   • SLES 12 SP5+ and 15 SP5+ (zypper)
   • Tarball

   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 v15. 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/v15" \| 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 v15. 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/v15/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 v15. 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 v15. 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/v15/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/v15/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-v15.2.4-linux-$SYSTEM_ARCH-bin.tar.gz.sha256
   <checksum> <filename>
   curl -O https://cdn.teleport.dev/teleport-ent-v15.2.4-linux-$SYSTEM_ARCH-bin.tar.gz
   shasum -a 256 teleport-ent-v15.2.4-linux-$SYSTEM_ARCH-bin.tar.gz
   Verify that the checksums match
   tar -xvf teleport-ent-v15.2.4-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-v15.2.4-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256
   <checksum> <filename>
   curl -O https://cdn.teleport.dev/teleport-ent-v15.2.4-linux-$SYSTEM_ARCH-fips-bin.tar.gz
   shasum -a 256 teleport-ent-v15.2.4-linux-$SYSTEM_ARCH-fips-bin.tar.gz
   Verify that the checksums match
   tar -xvf teleport-ent-v15.2.4-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/v15 anywhere in the Teleport documentation.

   Channel name	Description
   stable/<major>	Receives releases for the specified major release line, i.e. v15
   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
   • 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.