Sign In

Sign in to Teleport

Teleport Cloud LoginLogin to your Teleport AccountDashboard LoginLegacy Login & Teleport Enterprise Downloads
Get Started
Fork me on GitHub
Teleport

Run Teleport as a Daemon

OpenSource
Version 9.0
Improve

The Teleport binary is called teleport. When you run teleport start, the Teleport process runs in the foreground. On Linux systems in non-containerized environments, we recommend running the teleport binary as a daemon using systemd.

Prerequisites

A Linux host where you will install Teleport. The host must be configured to use systemd.

If you're not sure, 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

Choose the appropriate instructions for your environment.

Download Teleport's PGP public key
sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \  -o /usr/share/keyrings/teleport-archive-keyring.asc
Add the Teleport APT repository
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] https://deb.releases.teleport.dev/ stable main" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport
sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
sudo yum install teleport
Optional:  Using DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport
curl https://get.gravitational.com/teleport-v9.3.7-linux-amd64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.3.7-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v9.3.7-linux-amd64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.3.7-linux-amd64-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v9.3.7-linux-arm-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.3.7-linux-arm-bin.tar.gz
shasum -a 256 teleport-v9.3.7-linux-arm-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.3.7-linux-arm-bin.tar.gz
cd teleport
sudo ./install
curl https://get.gravitational.com/teleport-v9.3.7-linux-arm64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.3.7-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v9.3.7-linux-arm64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.3.7-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Teleport requires a configuration file to run. After installation, no configuration file exists. We will create a minimal configuration file to show you how to run Teleport as a daemon:

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

Step 2/3. Create a systemd unit file

Copy the recommended Teleport unit file for systemd below and paste the contents into a file called /usr/lib/systemd/system/teleport.service:

[Unit]
Description=Teleport SSH Service
After=network.target

[Service]
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/teleport start --config=/etc/teleport.yaml --pid-file=/run/teleport.pid
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/teleport.pid

[Install]
WantedBy=multi-user.target

If /usr/lib/systemd/system/ does not exist, consult the list of unit file load paths for other supported paths.

Enable the unit so systemd can place it in its dependency tree:

sudo systemctl enable teleport.service
Created symlink /etc/systemd/system/multi-user.target.wants/teleport.service → /lib/systemd/system/teleport.service.

Start the unit:

sudo systemctl start teleport

You can confirm that Teleport is running as a systemd service with the following command, which should show an Active status of active (running):

sudo systemctl status teleport
● teleport.service - Teleport SSH Service
     Loaded: loaded (/lib/systemd/system/teleport.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2022-04-18 18:33:41 UTC; 41s ago
   Main PID: 442 (teleport)
      Tasks: 9 (limit: 1116)
     Memory: 116.9M
     CGroup: /system.slice/teleport.service
             └─442 /usr/local/bin/teleport start --pid-file=/run/teleport.pid
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [PROXY:SER] SSH proxy service 9.0.4:v9.0.4-0-gf577413>
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [PROXY:SER] SSH proxy service 9.0.4:v9.0.4-0-gf577413>
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [PROC:1]    The new service has started successfully.>
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [PROXY:AGE] Starting reverse tunnel agent pool. servi>
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [PROXY:PRO] Starting Kube proxy on . service/service.>
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [DB:SERVIC] Starting Postgres proxy server on 0.0.0.0>
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [DB:SERVIC] Starting Database TLS proxy server on 0.0>
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [PROXY:SER] Starting proxy gRPC server on [::]:3080. >
Apr 18 18:33:49 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:49Z INFO [PROXY:SER] Starting TLS ALPN SNI proxy server on [::>
Apr 18 18:33:51 ip-172-30-173-50 teleport[442]: 2022-04-18T18:33:51Z WARN [PROXY:1]   Restart watch on error: empty proxy list.>

The next time you restart your host, systemd will run the teleport daemon automatically.

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.

Further reading

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 more information on how systemctl reload teleport works, see our guide to Graceful Restarts.

Have a suggestion or can’t find something?
IMPROVE THE DOCS