Fork me on GitHub

Teleport

Upgrading the Teleport Binary

Improve

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 13 the latest version is 13.0.3. Compare this to the version of Teleport you have installed on the host:

teleport version

Teleport 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:

Use the appropriate commands for your environment to install your package.

Teleport Edition

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 v13. 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/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

sudo apt-get update
sudo apt-get install teleport

Source variables about OS version

source /etc/os-release

Add the Teleport YUM repository for v13. You'll need to update this

file for each major release of Teleport.

sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
sudo yum install teleport

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

Source variables about OS version

source /etc/os-release

Add the Teleport YUM repository for v13. You'll need to update this

file for each major release of Teleport.

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/v13/teleport.repo")"

Install teleport

sudo dnf install teleport

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

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-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
shasum -a 256 teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
cd teleport
sudo ./install

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 v13. 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/v13" \| 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 v13. You'll need to update this

file for each major release of Teleport.

sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/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 YUM repository for v13. You'll need to update this

file for each major release of Teleport.

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/v13/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

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-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v13.0.3-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://get.gravitational.com/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install
Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

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 teleport

235276 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 235276

2022-04-20T15:33:58Z INFO [PROC:1] Got signal "terminated", exiting immediately. service/signals.go:86

2022-04-20T15:33:58Z WARN [PROC:1] Forked teleport process 235276 has exited with status: 0. service/signals.go:506

WARNING

Do not forget to restore the original binary

sudo mv ${DIR}/teleport.bak ${DIR}/teleport

You can retry the process again later.

WARNING

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 teleport

235276

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.