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

Machine ID Getting Started Guide

Report an issue with this page

In this getting started guide, you will configure Machine ID to issue certificates that enable a bot user to connect to a remote host.

Here's an overview of what you will do:

  • Download and install tbot on the host that will run Machine ID.
  • Create a bot user.
  • Start Machine ID.
  • Use certificates issued by Machine ID to connect to a remote machine with SSH.

This guide covers configuring Machine ID for development and learning purposes. For a production-ready configuration of Machine ID, visit the Deploying Machine ID guides.

Prerequisites​

  • A host that you wish to assign an identity to using Machine ID.

  • A running Teleport cluster version 17.0.0-dev 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.

    Visit Installation for instructions on downloading tctl and tsh.

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.

For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email@example.com to your Teleport username:

tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
Cluster  teleport.example.com
Version  17.0.0-dev
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.

Step 1/4. Download and install Teleport​

In this step, you will be downloading and installing Teleport binaries onto the machine you wish to assign an identity to.

Each Teleport package hosted on our downloads page ships with several useful binaries, including teleport, tctl, tsh,tbot, and fdpass-teleport:

  • teleport is the daemon used to initialize a Teleport cluster; this binary is not used in this guide
  • tctl is the administrative tool you will use to create the bot user (step 1/4)
  • tsh is the client tool you will use to log in to the Teleport Cluster (steps 2/4 and 4/4)
  • tbot is the Machine ID tool you will use to associate a bot user with a machine (step 3/4)
  • fdpass-teleport is used to integrate Machine ID with OpenSSH to enable higher performance and reduced resource consumption when establishing SSH connections; this binary is not used in this guide

Download the appropriate Teleport package for your platform:

To install a Teleport Agent on your Linux server:

The easiest installation method, for Teleport versions 17.3 and above, is the cluster install script. It will use the best version, edition, and installation mode for your cluster.

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

  2. Run your cluster's install script:

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

On older Teleport versions:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  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:443
    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:443
    TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

  3. Install Teleport on your Linux server:

    curl https://cdn.teleport.dev/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​

In Teleport, a Bot represents an identity for a machine. This is similar to how a user represents the identity of a human. Like users, bots are assigned roles to manage their access to resources. However, unlike users, bots do not authenticate using a username and password or SSO. Instead, they initially authenticate in a process called joining.

Teleport supports a number of secure join methods specific to the platform the bot is running on, but for the purposes of this guide, we will use the simpler token join method. You can follow a deployment guide later to learn about the secure join methods available for your platform.

Before you create a bot user, you need to determine which role(s) you want to assign to it. You can use the tctl command below to examine what roles exist on your system.

On your client machine, log in to Teleport using tsh, then use tctl to examine what roles exist on your system.

tctl get roles --format=text

You will see something like the output below on a fresh install of Teleport with the default roles—your cluster may have different roles. In this example, let's assume you want to give the bot the access role to allow it to connect to machines within your cluster.

Role    Allowed to login as                           Node Labels Access to resources
------- --------------------------------------------- ----------- ----------------------------------------
access  {{internal.logins}}                           <all nodes> event:list,read,session:read,list
auditor no-login-6566121f-b602-47f1-a118-c9c618ee5aec             session:list,read,event:list,read
editor                                                            user:list,create,read,update,delete,...

The internal.logins trait is replaced with values from the Teleport local user database. For full details on how traits work in Teleport roles, see the Access Controls Reference.

Assuming that you are using the default access role, ensure that you use the --logins flag when adding your bot to specify the SSH logins that you wish to allow the bot to access on hosts. For our example, we will be using root.

Use tctl bots add to create our bot:

tctl bots add robot --roles=access --logins=root

Step 3/4. Start Machine ID​

Now start Machine ID using the tbot binary. The tbot start command will start running Machine ID in a loop, writing renewable certificates to /var/lib/teleport/bot and the short-lived certificates your application will use to /opt/machine-id.

In a production environment you will want to run Machine ID in the background using a service manager like systemd. However, in this guide you will run it in the foreground to better understand how it works.

export TELEPORT_ANONYMOUS_TELEMETRY=1
sudo tbot start \ --data-dir=/var/lib/teleport/bot \ --destination-dir=/opt/machine-id \ --token=abcd123-insecure-do-not-use-this \ --join-method=token \ --proxy-server=example.teleport.sh:443

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.

Replace the following fields with values from your own cluster.

  • token is the token output by the tctl bots add command or the name of your IAM method token.
  • destination-dir is where Machine ID writes user certificates that can be used by applications and tools.
  • data-dir is where Machine ID writes its private data, including its own short-lived renewable certificates. These should not be used by applications and tools.
  • proxy-server is the address of your Teleport Proxy service, for example example.teleport.sh:443.

Now that Machine ID has successfully started, let's investigate the /opt/machine-id directory to see what was written to disk.

tree /opt/machine-id
machine-id├── identity├── key├── key-cert.pub├── key.pub├── known_hosts├── ssh_config├── teleport-database-ca.crt├── teleport-host-ca.crt├── teleport-user-ca.crt└── tlscert
0 directories, 10 files

This directory contains private key material in the key.* files, SSH certificates in the identity file, X.509 certificates in the tls* and *.crt files, OpenSSH configuration in the ssh_config and known_hosts files to make it easy to integrate Machine ID with external applications and tools.

Step 4/4. Use certificates issued by Machine ID​

To use Machine ID, find a host that you want to connect to within your cluster using tsh ls. You might see output like the following on your system.

tsh ls
Node Name Address        Labels--------- -------------- -----------------------------node-name  127.0.0.1:3022 arch=x86_64,group=api-servers
Not seeing Nodes?

When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to display Nodes in the Web UI or via tsh ls), it only returns the Nodes that the current user is authorized to view.

For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:

  • None of the user's roles contain a deny rule that matches the Node's labels.
  • At least one of the user's roles contains an allow rule that matches the Node's labels.

If you are not seeing Nodes when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Access Controls Reference.

To use Machine ID with the OpenSSH integration, run the following command to connect to node-name within cluster example.com.

ssh -F /opt/machine-id/ssh_config root@node-name.example.com

In addition to the ssh client you can use tsh. Replace the --proxy parameter with your proxy address.

tsh ssh --proxy=mytenant.teleport.sh -i /opt/machine-id/identity root@node-name
Roles must have logins defined

The below error can occur when the bot does not have permission to log in to a node as the requested user:

ssh -F /opt/machine-id/ssh_config root@node-name.example.com
root@node-name: Permission denied (publickey).kex_exchange_identification: Connection closed by remote host

This can happen in two circumstances:

  • The user you are trying to log in as is not specified under logins in the role you are using
  • If you have used --logins when creating the bot user, the role the bot is impersonating does not have the {{ internal.logins }} variable specified.

If you have been following along with the access role, do the following.

  • Export the role by running tctl get roles/access > access.yaml
  • Edit the logins field in access.yaml
  • Update the role by running tctl create -f access.yaml

Now you can replace any invocations of ssh with the above command to provide your applications and tools a machine identity that can be rotated, audited, and controlled with access controls.

Next Steps​