Teleport
Upgrade Self-Hosted Teleport Clusters on Linux
Version preview- Older Versions
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
andtsh
client tools version >= 16.0.0. 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 runtctl
commands using your current credentials.tctl
is supported on macOS and Linux machines.For example:
tsh login --proxy=teleport.example.com --user=email@example.comtctl statusCluster teleport.example.com
Version 16.0.0
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 subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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 Edition
- 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://goteleport.com/static/install.sh | bash -s 16.0.0Download 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 v16. 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/v16" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-entFor FedRAMP/FIPS-compliant installations, install the
teleport-ent-fips
package instead:sudo apt-get install teleport-ent-fipsSource variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v16. 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-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v16/teleport.repo")"sudo yum install teleport-entTip: 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-fipsSource variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for v16. 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-entTip: 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-fipsSource variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for v16. 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/v16/teleport.repo")"Install teleport
sudo dnf install teleport-entTip: 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-fipsSource variables about OS version
source /etc/os-releaseAdd 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/v16/teleport-zypper.repo")Install teleport
sudo zypper install teleport-entFor FedRAMP/FIPS-compliant installations, install the
teleport-ent-fips
package instead:sudo zypper install teleport-ent-fipsIn the example commands below, update
$SYSTEM_ARCH
with the appropriate value (amd64
,arm64
, orarm
). All example commands using this variable will update after one is filled out.curl https://cdn.teleport.dev/teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./installFor FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
curl https://cdn.teleport.dev/teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v16.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./installOS repository channels
The following channels are available for APT, YUM, and Zypper repos. They may be used in place of
stable/v16
anywhere in the Teleport documentation.Channel name Description stable/<major>
Receives releases for the specified major release line, i.e. v16
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.
On the host where you will run your Teleport instance, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleportOn 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.servicesudo systemctl enable teleportsudo systemctl start teleportYou can check the status of your Teleport instance with
systemctl status teleport
and view its logs withjournalctl -fu teleport
.