Skip to main content
Version: 19.x (unreleased)

Deploying tbot on Linux

Report an Issue

In this guide, you will deploy the Machine & Workload Identity agent, tbot, on a Linux host.

How it works​

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 native form of identity available to the machine, the preferred join method is bound_keypair. Unlike other join methods, a bound_keypair join token can only be used to join a single bot. Read more about Bound Keypair Joining.

Prerequisites​

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

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

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

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=[email protected]
      tctl status
      Cluster  teleport.example.com
      Version  19.0.0-dev
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

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

Step 1/3. 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 & Workload Identity on.

Install Teleport as appropriate for your platform:

To install Teleport binaries on your Linux server, the recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

  1. Remove any existing Teleport binaries on your system:

    sudo rm -f /usr/local/bin/{tsh,teleport,tctl,tbot,fdpass-teleport,teleport-update}

  2. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).

  3. Run your cluster's install script:

    curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash

Step 2/3. Create a bot user​

This step is completed on your local machine.

Create the bot with tctl bots add:

tctl bots add example
The bot joining URI: tbot+proxy+bound-keypair://bot-example-abc123:[email protected]:443This token must be used within 59 minutes after which it must be recreated.
[...]

Take note of the joining URI as it will be used in the next step. Joining URIs contain all the information needed for the tbot client to connect to and authenticate with your Teleport cluster. Be aware that this URI contains a single use secret value (shown as secret in the above example) and should be copied with care.

Step 3/3. Configure tbot​

This step is completed on the Linux host.

Create /etc/tbot.yaml:

version: v2
join_uri: tbot+proxy+bound-keypair://bot-example-abc123:[email protected]:443
storage:
  type: directory
  path: /var/lib/teleport/bot
# services will be filled in during the completion of an access guide.
services: []

Replace:

  • The join_uri field value with the joining URI printed by tctl in step 2.
note

The first time that tbot runs, the registration secret contained within the joining URI will be used to authenticate the first connection. After the first successful join, the registration secret is invalidated. You may remove it from the join URI (shown as secret in the example token) in your configuration file after the first run has completed, but there is no tangible security benefit to doing so.

Prepare the storage directory​

Create the bot data directory and grant permissions to access it to the Linux user (in our example, teleport) which tbot will run 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
Allow teleport user to open directory
sudo chmod +x /var/lib/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.

If tbot was installed using the Teleport install script or teleport-update command, the tbot systemd service is automatically created for you.

After tbot.yaml is created, enable and start the service:

sudo systemctl enable tbot --now

Check the service has started successfully:

sudo systemctl status tbot

Service properties like User and Group may be configured using systemctl edit tbot.

If tbot was installed manually, service configuration will need to be performed manually as well.

For this guide, systemd will be demonstrated but tbot should be compatible with all common alternatives.

Use tbot install systemd to generate a systemd service file:

sudo tbot install systemd \   --write \   --config /etc/tbot.yaml \   --user teleport \   --group teleport \   --pid-file /run/tbot.pid \   --anonymous-telemetry

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.
  • /run/tbot.pid with a path that the user configured for tbot has write access to. By default, tbot writes its PID file to /run/tbot.pid.

You can omit --write to print the systemd service file to the console instead of writing it to disk.

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

Check the service has started successfully:

sudo systemctl status tbot

Next steps​

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.