teleport/docs/pages/machine-workload-identity/machine-id/getting-started.mdx

---
title: Machine ID Getting Started Guide
description: Getting started with Teleport Machine ID
tags:
 - get-started
 - mwi
 - infrastructure-identity
---

{/* lint disable page-structure remark-lint */}

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](deployment/deployment.mdx) guides.

## Prerequisites

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

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

(!/docs/pages/includes/tctl.mdx!)

## 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: 

(!docs/pages/includes/install-linux.mdx!)

## 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.

```code
$ 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](../../reference/access-controls/roles.mdx).

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:

```code
$ 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.

```code
$ export TELEPORT_ANONYMOUS_TELEMETRY=1
$ sudo tbot start \
 --data-dir=/var/lib/teleport/bot \
 --destination-dir=/opt/machine-id \
 --token=(=presets.tokens.first=) \
 --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.

```code
$ 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.

```code
$ tsh ls
Node Name Address        Labels
--------- -------------- -----------------------------
node-name  127.0.0.1:3022 arch=x86_64,group=api-servers
```

<details>
<summary>Not seeing Nodes?</summary>

(!docs/pages/includes/node-logins.mdx!)

</details>

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

```code
$ ssh -F /opt/machine-id/ssh_config [email protected]
```

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

```code
$ tsh ssh --proxy=mytenant.teleport.sh -i /opt/machine-id/identity root@node-name
```

<Admonition type="note" title="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:

  ```code
  $ ssh -F /opt/machine-id/ssh_config [email protected]
  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`
</Admonition>

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

- Read the [architecture overview](../../reference/architecture/machine-id-architecture.mdx) to learn about how
  Machine ID works in more detail.
- Check out the [deployment guides](deployment/deployment.mdx) to learn about
  configuring `tbot` in a production-ready way for your platform.
- Check out the [access guides](access-guides/access-guides.mdx) to learn about configuring
  `tbot` for different use cases than SSH.
- Read the [configuration reference](../../reference/machine-workload-identity/machine-id/configuration.mdx) to explore
  all the available configuration options.
- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../../reference/machine-workload-identity/machine-id/telemetry.mdx)