Fork me on GitHub

Teleport

Run Teleport as a Daemon

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

On Linux systems in non-containerized environments, we recommend running the teleport binary as a daemon using systemd. Using a daemon helps to ensure that the teleport process can remain running and available regardless of a controlling terminal session or parent process, and opens up additional configuration options that allow for better optimization, uptime, and availability.

This guide will outline best practices for installing, configuring, and starting teleport as a daemon on a Linux host using systemd.

Prerequisites

  • A Linux host where you will install Teleport. The host must be configured to use systemd. To ensure that your host supports systemd, check whether /sbin/init is symbolically linked to /lib/systemd/systemd or similar:
readlink /sbin/init
/lib/systemd/systemd

Teleport stores data in /var/lib/teleport. Make sure that regular/non-admin users do not have access to this folder on the Auth Service host.

Step 1/3. Install and configure Teleport

Select and complete the appropriate installation instructions for your environment.

Select an edition, then follow the instructions for that edition to install Teleport.

Teleport Edition

curl https://goteleport.com/static/install.sh | bash -s 14.0.0

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

Source variables about OS version

source /etc/os-release

Add 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/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version

source /etc/os-release

Add 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-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-updater

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

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 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 nameDescription
stable/<major>Receives releases for the specified major release line, i.e. v14
stable/cloudRolling channel that receives releases compatible with current Cloud version
stable/rollingRolling channel that receives all published Teleport releases

Before installing a teleport binary with a version besides v13, 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.asc

Source variables about OS version

source /etc/os-release

Add 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/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 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-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/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 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-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 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-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/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.0.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256

<checksum> <filename>

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

Verify that the checksums match

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

<checksum> <filename>

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

Verify that the checksums match

tar -xvf teleport-ent-v14.0.0-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/v14 anywhere in the Teleport documentation.

Channel nameDescription
stable/<major>Receives releases for the specified major release line, i.e. v14
stable/cloudRolling channel that receives releases compatible with current Cloud version
stable/rollingRolling 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.asc

Source variables about OS version

source /etc/os-release

Add 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/null

sudo apt-get update
sudo apt-get install teleport-ent-updater

Source variables about OS version

source /etc/os-release

Add 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-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-updater

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

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 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 nameDescription
stable/<major>Receives releases for the specified major release line, i.e. v14
stable/cloudRolling channel that receives releases compatible with current Cloud version
stable/rollingRolling channel that receives all published Teleport releases

Before installing a teleport binary with a version besides v13, 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.

Teleport requires a configuration YAML file to be created and configured in order to run. After initial installation, no configuration file exists until we create it. This guide will use a minimal Teleport configuration based on defaults, however in production environments we recommend reviewing configuration file options to better suit your needs.

To create the default Teleport configuration file, enter the following command:

sudo teleport configure -o file
Wrote config to file "/etc/teleport.yaml". Now you can start the server. Happy Teleporting!

Step 2/3. Create and configure a systemd service

Once you've installed the teleport binary and created a Teleport configuration file, let's create and configure the Teleport daemon.

Systemd is designed to use unit files, which are the files used to define and configure any service daemon on systemd, in this case the teleport service. The rest of this guide will focus on creating and configuring the teleport service daemon depending on your preferred installation method, either a package manager, or from source.

We have included a default teleport daemon configuration for packages installed with DEM or RPM package managers. To check that this daemon was installed correctly, enter the following command:

sudo systemctl status teleport

You will see output similar to the following, including the file path (/lib/systemd/system/teleport.service) that contains the unit file for the systemd configuration being applied:

● teleport.service - Teleport Service Loaded: loaded (/lib/systemd/system/teleport.service; disabled; vendor preset: enabled) Active: inactive (dead)

Enter the following command to enable the systemd teleport daemon. Enabling the daemon using systemctl allows systemd to place the daemon in its dependency tree, ensuring that the Teleport service will be automatically restarted on any potential reboot:

sudo systemctl enable teleport

Next, enter the following command to start the teleport service daemon:

sudo systemctl start teleport

Confirm that the Teleport daemon was installed correctly by checking the service status. The following command will output a status of Active: active (running):

sudo systemctl status teleport | grep Active
Active: active (running) since Mon 2022-04-18 18:33:41 UTC; 41s ago

Enter the following teleport command to have Teleport output a systemd unit file to stdout to be reviewed and applied as needed:

teleport install systemd

If the output describes a good configuration for your environment, enter the command once again using the -o flag to write the output to a file within one of systemd's accepted unit file load paths. For most use cases, we recommend using the path /etc/systemd/system/teleport.service for your unit file:

sudo teleport install systemd -o /etc/systemd/system/teleport.service

Enable the teleport service daemon using systemctl so that systemd can place it in its dependency tree. This also ensures that the teleport service will be automatically restarted on any potential reboot:

sudo systemctl enable teleport

Start the teleport service daemon using systemctl:

sudo systemctl start teleport

Finally, confirm that the Teleport daemon has been installed correctly by checking the service daemon's status. The following command will output a status of Active: active (running) if the configuration has been applied correctly:

sudo systemctl status teleport | grep Active
Active: active (running) since Mon 2022-04-18 18:33:41 UTC; 41s ago

Step 3/3. Restart the Teleport daemon

Teleport supports graceful restarts, enabling you to easily change your Teleport configuration or upgrade your teleport binary without sacrificing availability.

Run the following command to gracefully restart the teleport daemon:

sudo systemctl reload teleport

This will perform a graceful restart, i.e. the Teleport daemon will fork a new process to handle new incoming requests, leaving the old daemon process running until existing clients disconnect.

Upgrading

To upgrade a host to a newer version of Teleport, you must:

  • Replace the Teleport binaries, usually teleport and tctl.
  • Execute systemctl reload teleport.

Understanding Teleport daemon command line options for unit file configuration

The teleport install systemd command includes a number of optional flags that you can use to strictly define parameters of the generated unit file and set where that output will be written. The following table includes all command line options available with the teleport install systemd command, a brief description of what they do, and their default settings:

FlagDescriptionDefault
--fd-limitThe maximum number of open file descriptors by the service, defined by LimitNOFILE in the unit file.--fd-limit=8192
--env-fileThe path to the EnvironmentFile defined by the system unit file, containing any potential variables to be used in the configuration.--envfile=/etc/default/teleport
--pid-fileThe path to the pid file containing the process identification number.--pid-file=/run/teleport.pid
--teleport-pathThe full path to the teleport binary.--teleport-path=/usr/local/bin/teleport
-o, --outputThe full unit file load path which will define where to create and store the system unit file itself. This flag is used to write the output to the designated file.--output=/etc/systemd/system/teleport.service

While a default configuration can always be created using the sudo teleport install systemd -o /etc/systemd/system/teleport.servicecommand, the same configuration using command line options is demonstrated below:

sudo teleport install systemd \--fd-limit=8192 \--env-file=/etc/default/teleport \--pid-file=/run/teleport.pid \--teleport-path=/usr/local/bin/teleport \--output=/etc/systemd/system/teleport.service

Next steps

In this guide, we showed you how to run teleport start as a systemd service. To see all commands that you can run via the teleport binary, see the Teleport CLI Reference.

While we used a minimal configuration in this guide, for a production Teleport cluster, you should consult our Configuration Reference.

If you need information on how systemctl reload teleport works, see our guide to upgrading a Teleport binary.

For information on unit file configurations and unit file load paths, see systemd's documentation on systemd.unit configurations