
Teleport
Upgrading the Teleport Binary
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise
In this guide, we will show you how to upgrade the teleport
binary on a Linux
host without sacrificing availability.
If you are running teleport
as a container, see
How to Run Teleport Using Docker for information on
specifying a version.
Prerequisites
This guide requires a host where the teleport
binary is running. The version
of the binary must be behind the latest.
For Teleport major version 14
the latest version is 14.2.1
.
Compare this to the version of Teleport you have installed on the host:
teleport versionTeleport v8.3.7 git:v8.3.7-0-ga8d066935 go1.17.3
Step 1/3. Download a new Teleport binary
Preserve the old binary, just in case the upgrade goes wrong.
DIR=$(which teleport | xargs dirname)sudo mv ${DIR}/teleport ${DIR}/teleport.bak
Install the newest version of Teleport on the host:
Select an edition, then follow the instructions for that edition to install Teleport.
Teleport Edition
- Teleport Community Edition
- Teleport Team
- Teleport Enterprise
- Teleport Enterprise Cloud
curl https://goteleport.com/static/install.sh | bash -s 14.2.1
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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
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]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"sudo yum install teleport-ent-updaterTip: 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
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
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 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/cloud/teleport-yum.repo")"Install teleport
sudo dnf install teleport-ent-updaterTip: 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
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for cloud.
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")Install teleport
sudo zypper install teleport-ent-updater
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 |
Before installing a teleport
binary with a version besides
v14, 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.
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 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/nullsudo apt-get updatesudo 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-releaseAdd 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-utilssudo 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-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-fips
Source variables about OS version
source /etc/os-releaseAdd 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-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-fips
Source variables about OS version
source /etc/os-releaseAdd 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-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-fips
Source 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/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://get.gravitational.com/teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-bin.tar.gzshasum -a 256 teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-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-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gzshasum -a 256 teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v14.2.1-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./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 |
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 cloud.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/nullsudo apt-get updatesudo apt-get install teleport-ent-updater
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
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]+")sudo yum install -y yum-utilssudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"sudo yum install teleport-ent-updaterTip: 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
Source variables about OS version
source /etc/os-releaseAdd the Teleport YUM repository for cloud.
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 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/cloud/teleport-yum.repo")"Install teleport
sudo dnf install teleport-ent-updaterTip: 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
Source variables about OS version
source /etc/os-releaseAdd the Teleport Zypper repository for cloud.
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")Install teleport
sudo zypper install teleport-ent-updater
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 |
Before installing a teleport
binary with a version besides v14,
read our compatibility rules to ensure that the binary is compatible with
Teleport Enterprise 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.
Step 2/3. Fork the teleport
process
Fork a new teleport
process by sending it the USR2
signal:
sudo kill -USR2 $(pidof teleport)
The original teleport
process forked a new child process and passed existing file descriptors
to the child. You now have two processes handling requests on the same socket:
pidof teleport235276 235119
In our example, 235276
is a PID of the child process, and 235119
is a PID of the parent.
You can use the following command, which prints the parent for each PID returned
by pidof
:
ps -o ppid= -p $(pidof teleport)1494 1495
In the logs you will see that the parent process reports that it has forked a new child process, and the child accepts file descriptors from its parent.
2021-08-19T10:16:51-07:00 [PROC:1] INFO Forked new child process. path:/usr/local/teleport service/signals.go:457
2021-08-19T10:16:51-07:00 [PROC:1] INFO Using file descriptor diag 127.0.0.1:3434 passed by the parent process. service/signals.go:207
Step 3/3. Return to a single teleport
process
After forking the new teleport
process, check the logs to ensure that the
process is running as expected. After that, you should either roll back or
complete the upgrade:
If the new binary behaves with errors, shut down the child process:
sudo kill -TERM 2352762022-04-20T15:33:58Z INFO [PROC:1] Got signal "terminated", exiting immediately. service/signals.go:862022-04-20T15:33:58Z WARN [PROC:1] Forked teleport process 235276 has exited with status: 0. service/signals.go:506
Do not forget to restore the original binary
sudo mv ${DIR}/teleport.bak ${DIR}/teleport
You can retry the process again later.
If you are upgrading a teleport
daemon using an SSH connection established
via Teleport, make sure to connect to the newly upgraded teleport
process
and shut down the previous teleport
process from it.
You can see which teleport
process handles the connection by using
pstree
:
pstree -aps $$systemd,1 splash
└─systemd,6247 --user
└─teleport-,235276
└─bash,190718
└─pstree,242371 -aps 190718
Shut down the parent process gracefully using SIGQUIT
:
sudo kill -QUIT 235119
The parent process will log a graceful shutdown:
2021-08-19T10:32:10-07:00 INFO [PROXY:SER] Shutting down gracefully. service/service.go:2952
In a couple of minutes, all existing connections drain off and the parent will exit:
pidof teleport235276
If for some reason, the parent process gets stuck (e.g., waiting for existing connections to finish), you can shut it down non-gracefully:
sudo kill -TERM 235119
You are all set.
Further reading
In this guide, we explained how to upgrade the teleport
binary on a single
host. If you would like to learn how to upgrade all of the components in a
Teleport cluster while preserving compatibility, read
Upgrading a Teleport Cluster.
See the full list of supported signals in the Teleport Signals Reference.