{"token_count": 3031} # Deploying tbot on Linux 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 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 accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - 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: **Mac/Linux** ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` **Windows - Powershell** ``` $ $TELEPORT_DOMAIN = "teleport.example.com:443" $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation/single-machine.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` Connecting with TLS routing disabled This guide's commands assume your Teleport cluster uses TLS routing (`proxy_listener_mode: multiplex`), where the `tctl` and `tsh` clients reach every Teleport service through the Proxy Service's web address on port `443`. If you're not sure whether this applies to your cluster, check with whoever manages it. If your cluster uses separate listener ports instead, adjust ports as follows: - **`tsh` commands** (e.g., `tsh login --proxy=...`): continue using the Proxy Service web address on port `3080` (or `443` if behind a load balancer). Do not change these to port `3025`. - **Direct `tctl` or Auth Service API commands**: use port `3025` for the Auth Service gRPC listener: ``` $ tctl status --auth-server=teleport.example.com:3025 ``` * 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\@example.com 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@example.com $ tctl status Cluster teleport.example.com Version 18.10.0 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](https://goteleport.com/docs/machine-workload-identity/getting-started.md) 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: ``` $ 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/3. 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 # services will be filled in during the completion of an access guide. services: [] ``` Replace: - `example.teleport.sh:443` with the address of your Teleport Proxy or Auth Service. 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. --- NOTE The first time that `tbot` runs, this token will be exchanged for a certificate that the bot uses for authentication. At this point, the token is invalidated. This means you may remove the token from the 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. - Follow the [access guides](https://goteleport.com/docs/machine-workload-identity/access-guides.md) to finish configuring `tbot` for your environment. - Read the [configuration reference](https://goteleport.com/docs/reference/machine-workload-identity/configuration.md) to explore all the available configuration options. - [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](https://goteleport.com/docs/reference/machine-workload-identity/telemetry.md)