![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Deploying Machine ID on Linux
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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 16.2.1 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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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:
-
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
-
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.comTELEPORT_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.comTELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')" -
Install Teleport on your Linux server:
curl https://cdn.teleport.dev/install-v16.2.1.sh | bash -s ${TELEPORT_VERSION} editionThe 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 bytctl bots add
in the previous step.
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
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/botsudo 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.
Use tbot install systemd
to generate a systemd service file:
tbot install systemd \ --write \ --config /etc/tbot.yaml \ --user teleport \ --group teleport \ --anonymous-telemetry
Ensure that you replace:
teleport
with the name of Linux user you wish to runtbot
as./etc/tbot.yaml
with the path to the configuration file you have created.
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-reloadsudo systemctl enable tbotsudo 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
.