tbot CLI reference

tbot is a CLI tool used with Machine ID that programatically issues and renews short-lived certificates to any service account (e.g, a CI/CD server).

The primary commands for tbot are as follows:

tbot db

Connects to databases using native clients and queries database information. 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.

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

Flags

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.

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 init

Initializes a certificate destination directory for access from a separate bot user. Allows for certificates to be written to disks other than a Machine ID client, configuring either file or POSIX ACL permissions.

Note that most use cases should instead use tbot's runtime ACL management by specifying allowed reader users and groups in the destination configuration.

Flags

Examples

Example using file permissions.

The following command highlights how to set permissions with tbot through Linux groups, using the user and group jenkins:jenkins. 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

Example using 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 proxy

Allows for access to Teleport resources via a local TLS proxy in TLS Routing mode. The tbot proxy command acts as a wrapper for tsh proxy to provide local proxy functionality for various protocols.

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

Consider using one of the following dedicated tunnel modes where possible:

• tbot start application-tunnel
• tbot start database-tunnel

Flags

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.

Additionally, the following should be noted:

• 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
• If no configuration file is provided, tbot will apply a sample configuration based on provided CLI flags. For this reason, it is recommended that settings are explicitly applied to a configuration file in production.

Examples

Example using OpenSSH

The following command forwards standard input and output over a proxy suitable for use as an OpenSSH ProxyCommand for SSH access:

tbot proxy --destination-dir=./tbot-user --proxy-server=proxy.example.com:3080 ssh alice@node: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.

Example using Database Access

The following example 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-server=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-server=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.

Flags

tbot configure

The tbot configure command is used to convert a tbot start CLI call into a YAML configuration file. It supports all the same subcommands and flags as tbot start, but prints an equivalent configuration instead of starting a bot.

For example, consider this tbot start identity CLI call:

tbot start identity \   --destination=./example \   --join-method=token \   --token=foo \   --proxy-server=teleport.example.com:443

To convert this CLI command into a configuration file, replace tbot start with tbot configure:

tbot configure identity \   --destination=./example \   --join-method=token \   --token=foo \   --proxy-server=teleport.example.com:443

An equivalent YAML configuration will be printed, which can be written to a file. The client can then be started using this configuration file:

tbot configure identity \   --destination=./example \   --join-method=token \   --token=foo \   --proxy-server=teleport.example.com:443 > tbot.yaml
tbot start -c tbot.yaml

Flags

This subcommand supports one additional flag beyond its tbot start equivalent:

tbot start

The tbot start family of commands starts the Machine ID client in various modes, depending on the type of resources to be accessed:

• tbot start legacy: Starts with a YAML configuration file or in legacy output mode
• tbot start identity: Starts with an identity output for SSH and Teleport API access
• tbot start database: Starts with a database credential output
• tbot start kubernetes: Starts with a Kubernetes output
• tbot start application: Starts with an application TLS credential output
• tbot start application-tunnel: Starts a local application tunnel
• tbot start database-tunnel: Starts a local database tunnel
• tbot start spiffe-svid: Starts a Workload ID SPIFFE SVID output

If only tbot start is specified, tbot start legacy will be inferred by default; this is the correct mode for use with a YAML configuration file.

Common Start Flags

These flags are available to all tbot start commands. Note that tbot start legacy supports slightly different options, so refer to its specific section for details when using a YAML config file or legacy output.

tbot start legacy

Starts the Machine ID client tbot, fetching and writing certificates to disk at a set interval. This command either starts from a configuration file if -c is specified, or starts with a default, legacy-compatible identity output.

This is the default tbot start subcommand if no other command is specified. Unless using a configuration file, consider using tbot start identity or another dedicated mode instead.

Flags

Examples

tbot start \   --data-dir=/var/lib/teleport/bot \   --destination-dir=/opt/machine-id \   --token=00000000000000000000000000000000 \   --join-method=token \   --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \   --proxy-server=example.teleport.sh:443

tbot start \   --data-dir=/var/lib/teleport/bot \   --destination-dir=/opt/machine-id \   --token=00000000000000000000000000000000 \   --join-method=token \   --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \   --proxy-server=teleport.example.com:443

tbot start identity

Starts the Machine ID client tbot with an identity output, fetching and writing certificates at a regular interval to the output specified with --destination.

tbot start identity --destination=DESTINATION [<flags>]

Flags

In addition to the common tbot start flags, this command supports these additional flags:

Examples

To start a bot with a one-time-use join token:

tbot start identity \  --proxy-server=example.teleport.sh:443 \  --join-type=token \  --token=TOKEN \  --destination=./tbot-user \  --storage=./tbot-data

tbot start database

Starts the Machine ID client tbot with a database output, fetching and writing database certificates at a regular interval to the output specified with --destination.

tbot start database --destination=DESTINATION --service=SERVICE --username=USERNAME --database=DATABASE [<flags>]

Flags

In addition to the common tbot start flags, this command supports these additional flags:

tbot start kubernetes

Starts the Machine ID client tbot with a Kubernetes output, fetching and writing Kubernetes credentials and a kubeconfig.yaml at a regular interval to the output specified with --destination.

tbot start kubernetes --destination=DESTINATION --kubernetes-cluster=KUBERNETES-CLUSTER [<flags>]

Flags

In addition to the common tbot start flags, this command supports these additional flags:

tbot start application

Starts the Machine ID client tbot with an application output, fetching and writing application TLS credentials at a regular interval to the output specified with --destination.

tbot start application --destination=DESTINATION --app=APP [<flags>]

Flags

In addition to the common tbot start flags, this command supports these additional flags:

tbot start application-tunnel

Starts the Machine ID client with a local tunnel to a particular application. This tunnel will run continuously and automatically refresh its certificates.

Note that this tunnel will be unencrypted. Be wary of the selected listen address, and prefer to use localhost or an equivalent loopback interface address when possible. Additionally, note that all users on the local system will be able to access this socket.

If you wish to tunnel multiple apps from one bot instance, use tbot configure application-tunnel ... to generate a configuration file and repeat the generated block under services: as desired.

This tunneling method is preferred over the legacy tbot proxy app.

tbot start application-tunnel --listen=LISTEN --app=APP [<flags>]

Flags

tbot start database-tunnel

Starts the Machine ID client with a local tunnel to a particular database. This tunnel will run continuously and automatically refresh its certificates.

Note that this tunnel will be unencrypted. Be wary of the selected listen address, and prefer to use localhost or an equivalent loopback interface address when possible. Additionally, note that all users on the local system will be able to access this socket.

If you wish to tunnel multiple databases from one bot instance, use tbot configure database-tunnel ... to generate a configuration file and repeat the generated block under services: as desired.

This tunneling method is preferred over the legacy tbot proxy db, and is roughly equivalent to tbot proxy db --tunnel.

tbot start database-tunnel --listen=LISTEN --service=SERVICE --username=USERNAME --database=DATABASE [<flags>]

Flags

In addition to the common tbot start flags, this command supports these additional flags:

tbot start spiffe-svid

Flags

In addition to the common tbot start flags, this command supports these additional flags:

tbot install systemd

Generates and installs a systemd unit file for a specific tbot configuration.

Flags

Examples

tbot install systemd \   --config=/etc/tbot.yaml \   --write

Destination URIs

Many tbot start subcommands accept destination URIs via the --storage and --destination flags.

Plain file paths are also be accepted with no file:// prefix; these will be treated as directory outputs.

Note that tbot start legacy only supports directory output destinations via the --destination-dir flag, though it does support URIs for --storage. All other tbot start subcommands accept these URIs where relevant.