Deploying Machine ID on Linux

This page explains how to deploy Machine ID on a Linux host.

The process in which tbot initially authenticates with the Teleport cluster is known as joining. A join method is a specific technique for the bot to prove its identity.

On platforms where there is no form of identity available to the machine, the only available join method is token. The token join method is special as it is the only join method that relies on a shared secret. In order to mitigate the risks associated with this, the token join method is single use and it is not possible to use the same token multiple times.

Prerequisites

• A running Teleport cluster version 15.2.4 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• 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.2.4
  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.
• A Linux host that you wish to install Machine ID onto.
• A Linux user on that host that you wish Machine ID to run as. In the guide, we will use teleport for this.

Step 1/4. Install tbot

This step is completed on the Linux host.

First, tbot needs to be installed on the VM that you wish to use Machine ID on.

Download the appropriate Teleport package for your platform:

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://goteleport.com/static/install.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.

Step 2/4. Create a bot user

This step is completed on your local machine.

Create the bot:

tctl bots add example

A join token will be included in the results of tctl bots add, record this value as it will be needed when configuring tbot.

Step 3/4. Configure tbot

This step is completed on the Linux host.

Create /etc/tbot.yaml:

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: token
  token: abcd123-insecure-do-not-use-this
storage:
  type: directory
  path: /var/lib/teleport/bot
# outputs will be filled in during the completion of an access guide.
outputs: []

Replace:

• example.teleport.sh:443 with the address of your Teleport Proxy or Auth Server. Prefer using the address of a Teleport Proxy.
• abcd123-insecure-do-not-use-this with the token that was returned by tctl bots add in the previous step.

Prepare the storage directory

When using the token join method, tbot must be able to persist its state across restarts. The destination used to persist this state is known as the bot's "storage destination". In this guide, the directory /var/lib/teleport/bot will be used.

As this directory will store the bots sensitive credentials, it is important to protect it. To do this, you will configure the directory to only be accessible to the Linux user which tbot will run as.

Execute the following, replacing teleport with the Linux user that you will run tbot as:

Make the bot directory and assign ownership to teleport user
sudo mkdir -p /var/lib/teleport/bot
sudo chown teleport:teleport /var/lib/teleport/bot

Create a systemd service

By default, tbot will run in daemon mode. However, this must then be configured as a service within the service manager on the Linux host. The service manager will start tbot on boot and ensure it is restarted if it fails. For this guide, systemd will be demonstrated but tbot should be compatible with all common alternatives.

Create a systemd unit file /etc/systemd/system/tbot.service:

[Unit]
Description=Teleport Machine ID Service
After=network.target

[Service]
Type=simple
User=teleport
Group=teleport
Restart=on-failure
Environment="TELEPORT_ANONYMOUS_TELEMETRY=1"
ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/tbot.pid
LimitNOFILE=524288

[Install]
WantedBy=multi-user.target

Ensure that you replace:

• teleport with the name of Linux user you wish to run tbot as.
• /etc/tbot.yaml with the path to the configuration file you have created

TELEPORT_ANONYMOUS_TELEMETRY enables the submission of anonymous usage telemetry. This helps us shape the future development of tbot. You can disable this by omitting this.

Next, enable the service so that it will start on boot and then start the service:

sudo systemctl daemon-reload
sudo systemctl enable tbot
sudo systemctl start tbot

Check the service has started successfully:

sudo systemctl status tbot

Step 4/4. Configure outputs

You have now prepared the base configuration for tbot. At this point, it identifies itself to the Teleport cluster and renews its own credentials but does not output any credentials for other applications to use.

Follow one of the access guides to configure an output that meets your access needs.

Next steps

• Follow the access guides to finish configuring tbot for your environment.
• Read the configuration reference to explore all the available configuration options.
• More information about TELEPORT_ANONYMOUS_TELEMETRY.