Fork me on GitHub

Teleport

Machine ID CLI Reference

Improve

tbot start

Starts the Machine ID client tbot, fetching and writing certificates to disk at a set interval.

tbot start \ --data-dir=/var/lib/teleport/bot \ --destination-dir=/opt/machine-id \ --token=00000000000000000000000000000000 \ --join-method=token \ --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ --auth-server=auth.example.com:3025
FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a configuration file.
-a/--auth-serverAddress of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant.
--tokenA bot join token, if attempting to onboard a new bot; used on first connect.
--ca-pinCA pin to validate the Teleport Auth Server; used on first connect.
--data-dirDirectory to store internal bot data. Access to this directory should be limited.
--destination-dirDirectory to write short-lived machine certificates.
--certificate-ttlTTL of short-lived machine certificates.
--renewal-intervalInterval at which short-lived certificates are renewed; must be less than the certificate TTL.
--join-methodMethod to use to join the cluster. Can be token or iam.
--oneshotIf set, quit after the first renewal.

tbot init

If you want to write certificates to disk as a different user than the Machine ID client, you can use tbot init to configure either file or POSIX ACLs permissions. This allows you to lock down access to Machine ID's short-lived certificates from other users or applications on the system.

FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a configuration file.
--destination-dirDirectory to write short-lived machine certificates to.
--ownerDefines the Linux user:group owner of --destination-dir. Defaults to the Linux user running tbot if unspecified.
--bot-userEnables POSIX ACLs and defines the Linux user that can read/write short-lived certificates to --destination-dir.
--reader-userEnables POSIX ACLs and defines the Linux user that will read short-lived certificates from --destination-dir.
--init-dirIf using a config file and multiple destinations are configured, controls which destination dir to configure.
--cleanIf set, remove unexpected files and directories from the destination.

tbot init with file permissions

If running tbot as the Linux user root, use the following invocation of tbot init to initialize the short-lived certificate directory /opt/machine-id with owner jenkins:jenkins.

tbot init \ --destination-dir=/opt/machine-id \ --owner=jenkins:jenkins

tbot init with POSIX ACLs

If running tbot as the Linux user teleport, use the following invocation of tbot init to initialize the short-lived certificate directory /opt/machine-id with owner teleport:teleport but allow jenkins to read from /opt/machine-id.

tbot init \ --destination-dir=/opt/machine-id \ --bot-user=teleport \ --reader-user=jenkins

tbot configure

Writes a configuration file with the options specified using the commandline parameters to STDOUT or a path on disk. This file can then be used to control the behaviour of tbot.

It is preferable to generate a configuration, and then use this with tbot rather than directly providing parameters to tbot start.

FlagDescription
-d/--debugEnable verbose logging to stderr.
-o/--outputPath to write configuration file to. If not provided, the generated configuration is output to STDOUT.
-a/--auth-serverAddress of the Teleport Auth Server (on-prem installs) or Teleport Cloud tenant.
--ca-pinCA pin to validate the Teleport Auth Server; used on first connect.
--certificate-ttlTTL of short-lived machine certificates.
--data-dirDirectory to store internal bot data. Access to this directory should be limited.
--join-methodMethod to use to join the cluster. Can be token or iam.
--oneshotIf set, quit after the first renewal.
--renewal-intervalInterval at which short-lived certificates are renewed; must be less than the certificate TTL.
--tokenA bot join token, if attempting to onboard a new bot; used on first connect. Can also be an absolute path to a file containing the token.

tbot db

Retrieves basic information about and connects to databases using native clients.

This is best used for testing and validation purposes; most users will likely prefer to connect their own databases to a local proxy using tbot proxy db as described below.

Note that tsh must also be installed to make use of this command.

FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a configuration file.
--destination-dirPath to the Machine ID destination dir that should be used for authentication. Required.
--proxyThe host:port of the Teleport Proxy Service to use to access resources. Required.
--clusterThe name of the cluster on which resources should be accessed. Extracted from the bot identity if unset.

All other flags and arguments are passed directly to tsh db ..., along with authentication parameters to use the Machine ID identity to skip tsh's login steps.

Note that certain CLI parameters, for example --help, may be captured by tbot even if intended to be passed to the wrapped tsh. A -- argument can be used to ensure all following arguments are passed to tsh and ignored by tbot:

This shows `--help` for `tbot db`:

tbot db --proxy=example.com --destination-dir=./tbot-user/ --help

This shows `--help` for `tsh db`:

tbot db --proxy=example.com --destination-dir=./tbot-user/ -- --help

Additionally, be aware of the following limitations of tbot db:

  • tbot db connect requires a tbot db login for certain database types, like MySQL, so that additional connection parameters can be written to a local configuration file.
  • tbot db env is not fully supported.

tbot proxy

If you want to access Teleport resources on a cluster using TLS Routing, you'll need to run a local ALPN/SNI proxy to access the resources. The tbot proxy command wraps tsh proxy to provide local proxy functionality for various protocols, including SSH and database access.

Note that tsh must also be installed to make use of this command.

FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a configuration file.
--destination-dirPath to the Machine ID destination dir that should be used for authentication. Required.
--proxyThe host:port of the Teleport Proxy Service through which resources will be accessed. Required.
--clusterThe name of the cluster on which resources should be accessed. Extracted from the bot identity if unset.

All other flags and arguments are passed directly to tsh proxy ..., along with authentication parameters to use the Machine ID identity to skip tsh's login step.

Note that certain CLI parameters, for example --help, may be captured by tbot even if intended to be passed to the wrapped tsh. A -- argument can be used to ensure all following arguments are passed to tsh and ignored by tbot:

This shows `--help` for `tbot proxy`:

tbot proxy --proxy=example.com --destination-dir=./tbot-user/ --help

This shows `--help` for `tsh proxy`:

tbot proxy --proxy=example.com --destination-dir=./tbot-user/ -- --help

tbot proxy ssh for SSH access

This forwards standard input and output over a proxy suitable for use as an OpenSSH ProxyCommand.

tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 ssh [email protected]:3022

In this case:

  • alice is the remote username
  • node is the Teleport Node name
  • 3022 is the remote SSH port, which is 3022 for Nodes running the Teleport SSH service.

You can also refer to Machine ID's generated ssh_config for a proxy usage example.

tbot proxy db for database access

This opens a local proxy server to the given database. Your database client must still be configured with client TLS certificates

tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 db --port=1234 example

In this case:

  • example is the name of the database server as it exists in Teleport
  • 1234 is an arbitrary port on which to run the proxy

Though not recommended, to avoid the need for additional client authentication, the --tunnel flag may be used to perform authentication at the local proxy rather than within your client:

tbot proxy --destination-dir=./tbot-user --proxy=proxy.example.com:3080 db --tunnel --port=1234 example

Note that this decreases security:

  • It allows any user on the system to access the database via localhost.
  • Your connection to the database will be unencrypted until it reaches the tbot proxy running on localhost.

Refer to the database guide for more information on using database proxies.