![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Machine ID v16 Upgrade Guide
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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=legacytbot 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.