Meet us at KubeCon + CloudNativeCon: Paris, France - March 19
Book Demo
Teleport logoTry For Free
Fork me on GitHub

Teleport

Upgrade Self-Hosted Teleport Clusters on Linux

  • Available for:
  • Enterprise
  • OpenSource

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

    tctl version

    Teleport v15.1.1 go1.21


    tsh version

    Teleport v15.1.1 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 protected]
    tctl status

    Cluster teleport.example.com

    Version 15.1.1

    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

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

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

    <checksum> <filename>

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

    Verify that the checksums match

    tar -xvf teleport-ent-v15.1.1-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.1.1-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256

    <checksum> <filename>

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

    Verify that the checksums match

    tar -xvf teleport-ent-v15.1.1-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 nameDescription
    stable/<major>Receives releases for the specified major release line, i.e. v15
    stable/cloudRolling channel that receives releases compatible with current Cloud version
    stable/rollingRolling 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.

    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.