Machine ID v16 Upgrade Guide

Report an issue with this page

Teleport 16.0 introduces a number of changes to Machine ID. These changes may require action on your part if you use Machine ID with OpenSSH or OpenSSH-based clients (e.g. Ansible).

This guide explains how to migrate your Teleport 16.0 cluster for continued Machine ID support.

Changes OpenSSH support and the tbot proxy ssh command

When using Machine ID with an OpenSSH client, an ssh_config is generated and used to configure the OpenSSH client.

Within the ssh_config, the ProxyCommand directive specifies a special command to be used to connect to the target host.

Historically, this command would be tbot proxy ssh.

We have now introduced a new command: tbot ssh-proxy-command. This has a number of benefits:

• tsh is no longer required to be installed on the machine.
• The amount of CPU and memory used during a connection is significantly reduced.
• The time taken to establish a connection is significantly reduced.

This command was introduced in a Teleport 15 release, and from Teleport 16.0 will become used by default in the generated ssh_config. From Teleport 17.0, the tbot proxy ssh command will no longer be supported and will be removed.

Actions required

If you are using Machine ID with OpenSSH or OpenSSH based clients, you may need to take action.

Using the default ssh_config

If you are using the default generated ssh_config, then no explicit action on your behalf should be necessary. From 16.0, the new command will be automatically used.

We do recommend that you perform a test-run when updating to ensure that everything is working as expected. You can revert to the old behaviour by setting the TBOT_SSH_CONFIG_PROXY_COMMAND_MODE environment variable to legacy in the environment in which you are running tbot:

export TBOT_SSH_CONFIG_PROXY_COMMAND_MODE=legacy
tbot start -c config.yaml

Using a modified ssh_config

If you have modified the ssh_config and therefore do not use the default ssh_config generated by tbot, then you will need to manually update the file. You must do this before 17.0, but we recommend doing this in 16.0 to benefit from the performance improvements.

To update your modified ssh_config, we recommend running an instance of tbot as you would usually configure it. This will generate a new ssh_config. Carefully inspect the ProxyCommand directive, and copy the new command to your modified ssh_config.

You can find a full list of the parameters available for the tbot ssh-proxy-command on the CLI reference page.