Run Teleport as a Daemon

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

Step 1/3. Install and configure Teleport

Select and complete the appropriate installation instructions for your environment.

Install Teleport on your Linux server:

1. Assign edition to one of the following, depending on your Teleport edition:

   Edition	Value
   Teleport Enterprise Cloud	cloud
   Teleport Enterprise (Self-Hosted)	enterprise
   Teleport Community Edition	oss

2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

   TELEPORT_DOMAIN=example.teleport.com
   TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

   Otherwise, get the version of your Teleport cluster:

   TELEPORT_DOMAIN=example.teleport.com
   TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

3. Install Teleport on your Linux server:

   curl https://cdn.teleport.dev/install-v16.4.8.sh | bash -s ${TELEPORT_VERSION} edition

   The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

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.

sudo systemctl status teleport

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

sudo systemctl enable teleport

sudo systemctl start teleport

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

teleport install systemd

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

sudo systemctl enable teleport

sudo systemctl start teleport

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 (with a timeout of 30 hours).

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:

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.

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