Teleport CLI Reference

Teleport is made up of four CLI tools.

• teleport: Supports the Teleport access plane by starting and configuring various Teleport services.
• tsh: Allows end users to authenticate to Teleport and access resources in a cluster.
• tctl: Used to configure the Teleport Auth Service.
• tbot: Supports Machine ID, which provides short lived credentials to service accounts (e.g, a CI/CD server).

teleport

The CLI tool that supports the Teleport access plane is called teleport, and allows Teleport services to be managed over the command line:

• Auth
• Node/SSH
• Proxy
• App
• Database
• Windows Desktop
• Kubernetes

The primary commands for the teleport CLI are as follows:

teleport start

The teleport start command includes a large number of optional configuration flags.

While configuration flags for teleport start can be used to set parameters for Teleport's configuration, we recommend using a configuration file in production.

Flags

teleport start --roles

The --roles flag when used with teleport --start instructs Teleport on which specific Teleport services to start. Below is a more cohesive table of roles and their associated services that teleport start supports:

Examples

# By default without any configuration, teleport starts running as a single-node
# cluster. It's the equivalent of running with --roles=node,proxy,auth
sudo teleport start

# Starts a node named 'db' running in strictly SSH mode role, joining the cluster
# serviced by the auth server running on 10.1.0.1
sudo teleport start --roles=node --auth-server=10.1.0.1 --token=xyz --nodename=db

# Same as the above, but the node runs with db=master label and can be connected
# to using that label in addition to its name.
sudo teleport start --roles=node --auth-server=10.1.0.1 --labels=db=master

# Starts an app server that proxies the application "example-app" running at http://localhost:8080.
sudo teleport start --roles=app --token=xyz --auth-server=proxy.example.com:3080 \
    --app-name="example-app" \
    --app-uri="http://localhost:8080" \
    --labels=group=dev

tsh

tsh is a CLI client used by Teleport Users. It allows users to interact with current and past sessions on the cluster, copy files to and from nodes, and list information about the cluster.

tsh global flags

tsh help

Prints help:

tsh help

tsh version

Prints the version of your tsh binary and the Teleport Proxy Service in the current tsh profile

tsh version [<flags>]

Examples

tsh version
Teleport v12.1.1 git: go1.19
Proxy version: 12.1.1
Proxy: teleport.example.com:443

Display in JSON format:

tsh version --format=json

{
  "version": "12.1.1",
  "gitref": "",
  "runtime": "go1.19",
  "proxyVersion": "12.1.1",
  "proxyPublicAddress": "teleport.example.com:443"
}

Only display the tsh binary version:

tsh version --client
Teleport v12.1.1 git: go1.19

tsh ssh

Run shell or execute a command on a remote SSH node:

tsh ssh [<flags>] <[[email protected]]host> [<command>...]

Arguments

<[[email protected]]host> [<command>...]

• user The login identity to use on the remote host. If [user] is not specified the user defaults to $USER or can be set with --user. If the flag --user and positional argument [user] are specified the arg [user] takes precedence.
• host The nodename of a cluster Node or a label specification like env=aws to run on all matching hosts.
• command The command to execute on a remote host.

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

Log in to node `grav-00` as OS User `root` with Teleport User `teleport`
tsh ssh --proxy proxy.example.com --user teleport -d [email protected]
`tsh ssh` takes the same arguments as OpenSSH client:
tsh ssh -o ForwardAgent=yes [email protected]
tsh ssh -o AddKeysToAgent=yes [email protected]
Run `hostname` on all nodes with the `env: aws` label
tsh ssh [email protected]=aws hostname

tsh config

Generates OpenSSH configuration to use currently logged in teleport as a bastion host.

tsh config

Examples

Print OpenSSH config file to console
tsh config
Append Teleport configuration to ssh config
tsh config >> ~/.ssh/config

tsh apps ls

List all available applications:

tsh apps ls

tsh gcloud

Proxy gcloud CLI commands through the Teleport Application Service. gcloud is a tool for interacting with Google Cloud. A user must already be authenticated to a Google Cloud application in Teleport before they can execute tsh gcloud commands.

tsh gcloud [--app] [<command>]

Arguments

command: A gcloud command to run, including arguments and flags.

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

tsh gcloud compute instances list

tsh gsutil

Proxy gsutil CLI commands through the Teleport Application Service. gsutil is a tool for interacting with Google Cloud Storage. A user must already be authenticated to a Google Cloud application in Teleport before they can execute tsh gsutil commands.

tsh gsutil [--app] [<command>]

Arguments

command: A gsutil command to run, including arguments and flags.

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

tsh gsutil ls

tsh join

Joins an active session:

tsh join [<flags>] <session-id>

Arguments

<session-id>

• session-id The UUID of an active Teleport Session obtained by teleport status within the session.

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

join session using teleport user joe as ec2-user
tsh --user=joe --login=ec2-user join <session-id>

tsh recordings ls

List recorded sessions.

tsh recordings ls [<flags>]

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags section.

Examples

get the recorded sessions from the last 24 hours
tsh --proxy proxy.example.com recordings ls
ID                                   Type Participants Hostname Timestamp
------------------------------------ ---- ------------ -------- -------------------
b0a04442-70dc-4be8-9308-7b7901d2d600 ssh  jeff         dev       Nov 26 16:36:16 UTC
c0a02222-70dc-4be8-9308-7b7901d2d600 kube alice                  Nov 26 20:36:16 UTC
d0a04442-70dc-4be8-9308-7b7901d2d600 ssh  navin        test      Nov 26 16:36:16 UTC
The session can be played with tsh play
tsh play c0a02222-70dc-4be8-9308-7b7901d2d60
List recorded sessions that occurred between Nov 1, 2022 to Nov 3, 2022
tsh recordings ls --from-utc=2022-11-01 --to-utc=2022-11-3
Retrieve recorded sessions in the last 6 hours
tsh recordings ls --last=6h0m0s

tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b
ERROR: Recording for session c8e1b2c5-322a-4095-89e3-391edfd2da9b not found.

tsh play c8e1b2c5-322a-4095-89e3-391edfd2da9b.tar

tsh play

Plays back a prior session:

tsh play [<flags>] <session-id>

Arguments

<session-id>

• session-id The UUID of a past Teleport Session obtained by teleport status within the session or from the Web UI.

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags section.

Examples

tsh --proxy proxy.example.com play <session-id>
Playing back a session using pty format using a downloaded session recording.
tsh play --format=pty 1fe153d1-ce8b-4ef4-9908-6539457ba4ad.tar
Playing back a session in json format using jq to filter on events
tsh play --format=json ~/play/0c0b81ed-91a9-4a2a-8d7c-7495891a6ca0.tar | jq '.event

tsh proxy db

Start a local TLS proxy for database connections when using Teleport with TLS Routing enabled. Clients can connect to a Teleport-registered database through the local proxy.

tsh proxy db [<flags>] <db>

Flags

Global Flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags Section

Examples

Proxy a DB connection to a named database

tsh proxy db <db>

Proxy a connection to mysql db on local port 10700:

tsh proxy db --port 10700  mysql-db
Started DB proxy on 127.0.0.1:10700
Use following credentials to connect to the mysql-db proxy:
ca_file=/Users/jeff/.tsh/keys/teleport.example.com/cas/teleport.example.com.pem
cert_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff-db/tele1c/mysql-db-x509.pem
key_file=/Users/jeff/.tsh/keys/teleport.example.com/jeff

Proxy a connection to mysql db with no credentials required:

tsh proxy db --tunnel mysql-db
Started authenticated tunnel for the MySQL database "mysql-db" in cluster "teleport.example.com" on 127.0.0.1:49415.
Use the following command to connect to the database:
  $ mysql --port 49415 --host localhost --protocol TCP

tsh proxy ssh

Start a local TLS proxy for ssh connections when using Teleport in TLS Routing mode. This is typically used as part of the SSH client configuration to use ssh as a client through Teleport. See the OpenSSH Guide guide on configuring OpenSSH servers and clients. The tsh config output will include tsh proxy ssh within a ProxyCommand directive.

tsh proxy ssh [<flags>] <[[email protected]]host>

Arguments

• <[[email protected]]host> Remote hostname and the login to use

Flags

Global Flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags Section

Examples

Run the following command to generate an OpenSSH client configuration:

tsh config

This command produces the following configuration:

# Common flags for all example.com hosts
Host *.example.com example.com
    UserKnownHostsFile "/Users/jeff/.tsh/known_hosts"
    IdentityFile "/Users/jeff/.tsh/keys/enterprise.teleportdemo.com/jeff"
    CertificateFile "/Users/jeff/.tsh/keys/example.com/jeff-ssh/example.com-cert.pub"
    PubkeyAcceptedKeyTypes [email protected]
    HostKeyAlgorithms [email protected]

# Flags for all example.com hosts except the proxy
Host *.example.com !example.com
    Port 3022
    ProxyCommand "/usr/local/bin/tsh" proxy ssh --cluster=example.com --proxy=example.com %[email protected]%h:%p

This output should be placed into the default SSH Config for environment, ~/.ssh/config for Mac/Linux or .ssh\config in the Windows User home directory. You can use this as a standalone SSH config file too.

When you run an ssh command against a host with a subdomain of your Proxy Service's domain, this SSH configuration will use the ProxyCommand to run tsh proxy ssh:

ssh [email protected]

tsh proxy app

Starts a local TLS proxy for Application Access connections. You can use this proxy to connect to an application repeatedly after a single login to your Teleport cluster, which is especially useful for interacting with an application via a CLI.

tsh proxy app [<flags>] <app>

Arguments

<app>

• app The name of the application to start the local proxy for. To see a list of available applications, run tsh apps ls.

Flags

Global Flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags Section

Examples

tsh proxy app <app>
Proxy a connection to grafana on local port 10700
tsh proxy --port 10700 app grafana &
Proxying connections to grafana on 127.0.0.1:10700
curl http://127.0.0.1:10700/api/users

tsh proxy azure

Starts a local proxy server that provides secure access to an Azure managed service identity endpoint. This is useful for managing access to Azure from custom client applications. The local proxy forwards traffic to the Teleport Application Service, which uses an Azure managed identity to fetch an authentication token from Azure.

tsh proxy azure [<flags>]

The command will print the address of the local proxy server along with export commands for environment variables required to connect:

Started Azure proxy on http://127.0.0.1:54330.
To avoid port randomization, you can choose the listening port using the --port flag.

Use the following credentials and HTTPS proxy setting to connect to the proxy:

  export AZURE_CONFIG_DIR=/Users/myuser/.tsh/azure/my.teleport.cluster/azure
  export HTTPS_PROXY=http://127.0.0.1:54330
  export HTTP_PROXY=http://127.0.0.1:54330
  export MSI_ENDPOINT=https://azure-msi.teleport.dev/eedfd5b55257c0aaa58f
  export REQUESTS_CA_BUNDLE=/Users/myuser/.tsh/keys/teleport.example.com/myuser-app/teleport.example.com/azure-cli-localca.pem

Copy the export commands and paste them into a second terminal.

To run the local proxy server, one of the user's roles must include the spec.allow.azure_identities field with one of the identities used by the Application Service. To learn how to set up secure access to Azure via Teleport, read Protect the Azure CLI with Teleport Application Access.

Arguments

This command does not accept any arguments.

Flags

Global Flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags Section

tsh proxy aws

Start a local proxy for AWS access. The user must already be logged in to at least one AWS application via Teleport before the proxy can start.

tsh proxy aws [<flags>]

Flags

Global Flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags Section

Examples

Proxy a connection to AWS with the default settings
tsh apps login awsapp
tsh proxy aws
Set env variables from output
aws s3 ls
Proxying connections to AWS on 127.0.0.1:10700 to app awsapp2
tsh apps logins awsapp2
tsh proxy aws --port=10700 --app=awsapp2
Set env variables from output
aws s3 ls

tsh proxy gcloud

Start a local proxy for Google Cloud API access. The user must already be logged in to at least one Google Cloud application via Teleport before the proxy can start.

tsh proxy gcloud [<flags>]

Flags

Global Flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost, --format. Run tsh help <subcommand> or see the Global Flags Section

Examples

tsh apps login google-cloud-app
tsh proxy gcloud
Set env variables from output
gcloud compute instances list
gsutil ls

tsh scp

Copies files from source to dest:

tsh scp [<flags>] <source>... <dest>

Arguments

• <source> - filepath to copy
• <dest> - target destination

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

tsh --proxy=proxy.example.com scp example.txt [email protected]:/destination/dir

tsh ls

List cluster nodes:

tsh ls [<flags>] [<label>]

Arguments

• <label> - key=value label to filer nodes by

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

tsh ls
Node Name Address            Labels
--------- ------------------ ------
grav-00   10.164.0.0:3022    os:linux
grav-01   10.156.0.2:3022    os:linux
grav-02   10.156.0.7:3022    os:osx
tsh ls -v
Node Name Node ID                              Address            Labels
--------- ------------------------------------ ------------------ ------
grav-00   52e3e46a-372f-494b-bdd9-a1d25b9d6dec 10.164.0.0:3022    os:linux
grav-01   73d86fc7-7c4b-42e3-9a5f-c46e177a29e8 10.156.0.2:3022    os:linux
grav-02  24503590-e8ae-4a0a-ad7a-dd1865c04e30 10.156.0.7:3022     os:osx
Only show nodes with os label set to 'osx':
tsh ls os=osx
Node Name Address            Labels
--------- ------------------ ------
grav-02   10.156.0.7:3022    os:osx

tsh kube ls

List Kubernetes clusters:

tsh kube ls

Examples

tsh kube ls
Kube Cluster Name                     Selected
------------------------------------- --------
gke_bens-demos_us-central1-c_gks-demo *
microk8s

tsh clusters

tsh clusters [<flags>]

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

tsh clusters
Cluster Name Status
------------ ------
staging          online
production       offline
tsh clusters --quiet
staging online
production offline

tsh login

Logs in to the cluster. When tsh logs in, the auto-expiring key is stored in ~/.tsh and is valid for 12 hours by default unless you specify another interval via --ttl flag (capped by the server-side configuration).

tsh login [<flags>] [<cluster>]

Arguments

• <cluster> - the name of the cluster, see Trusted Cluster for more information.

Flags

Global flags

These flags are available for all commands --login, --proxy, --user, --ttl, --identity, --cert-format, --insecure, --auth, --skip-version-check, --debug, --jumphost. Run tsh help <subcommand> or see the Global Flags section.

Examples

The proxy endpoint can take a https and ssh port in this format host:https_port[,ssh_proxy_port]

Try Toboth ports 443 and 3080 for https
tsh --proxy=proxy.example.com login
Use ports 8080 and 8023 for https and SSH proxy:
tsh --proxy=proxy.example.com:8080,8023 login
Use port 8080 and 3023 (default) for SSH proxy:
tsh --proxy=proxy.example.com:8080 login
Use port 23 as custom SSH port, keep HTTPS proxy port as default
tsh --proxy=work.example.com:,23 login
Login and select cluster "two":
tsh --proxy=proxy.example.com login two
Select cluster "two" using existing credentials and proxy:
tsh login two
Login to the  cluster with a very short-lived certificate
tsh --ttl=1 login
Login using the local Teleport 'admin' user:
tsh --proxy=proxy.example.com --auth=local --user=admin login
Login using GitHub as an SSO provider, assuming the GitHub connector is called "github"
tsh --proxy=proxy.example.com --auth=github login
Suppress the opening of the system default browser for external provider logins
tsh --proxy=proxy.example.com --browser=none
Login to cluster and output a local kubeconfig
tsh login --proxy=proxy.example.com --format=kubernetes -o kubeconfig
Request access to a cluster.
tsh login --proxy=proxy.example.com --request-reason="I need to run a debug script on production"

tsh kube login

Log into a Kubernetes cluster. Discover connected clusters by using tsh kube ls.

tsh kube login <kube-cluster>

tsh kube login to k8s cluster (gke_bens-demos_us-central1-c_gks-demo)
tsh kube login gke_bens-demos_us-central1-c_gks-demo
Logged into kubernetes cluster "gke_bens-demos_us-central1-c_gks-demo". Try 'kubectl version' to test the connection.
On login, kubeconfig is pointed at the first cluster (alphabetically)
kubectl config current-context
aws-gke_bens-demos_us-central1-c_gks-demo
But all clusters are populated as contexts
kubectl config get-contexts
CURRENT   NAME                                        CLUSTER                       AUTHINFO                                    NAMESPACE
*         aws-gke_bens-demos_us-central1-c_gks-demo   aws                           aws-gke_bens-demos_us-central1-c_gks-demo
aws-microk8s                                aws                           aws-microk8s

Flags

tsh logout

Deletes the client's cluster certificate:

tsh logout

tsh status

Display the list of proxy servers and retrieved certificates:

tsh status

Examples

tsh status
> Profile URL:  https://proxy.example.com:3080
Logged in as:       benarent
Cluster:            aws
Roles:              admin*
Logins:             benarent, root, ec2-user, ubunutu
Kubernetes:         enabled
Kubernetes cluster: "gke_bens-demos_us-central1-c_gks-demo"
Kubernetes groups:  system:masters
Valid until:        2020-11-21 01:50:23 -0800 PST [valid for 11h52m0s]
Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

tsh mfa ls

List all registered Multi-Factor Authentication (MFA) devices:

tsh mfa ls

tsh mfa add

Register a new Multi-Factor Authentication (MFA) device:

tsh mfa add

Examples

tsh mfa add
Choose device type [TOTP, WEBAUTHN]: webauthn
Enter device name: desktop yubikey
Tap any *registered* security key
Tap your *new* security key
MFA device "desktop yubikey" added.

tsh mfa add
Choose device type [TOTP, WEBAUTHN]: totp
Enter device name: android
Tap any *registered* security key
Open your TOTP app and create a new manual entry with these fields:
Name: [email protected]:3080
Issuer: Teleport
Algorithm: SHA1
Number of digits: 6
Period: 30s
Secret: 6DHDR7GWA7ZKLLWEWRIF55WXJKZ52UVJ
Once created, enter an OTP code generated by the app: 123456
MFA device "android" added.

tsh mfa rm

Remove a registered Multi-Factor Authentication (MFA) device. You can view your registered devices using tsh mfa ls.

tsh mfa rm <device-name>

tsh request create

Create a new Access Request.

tsh request create [<flags>]

Flags

tsh request ls

List Access Requests

tsh request ls

Flags

tsh request show

Show Access Request details

tsh request show <request-id>

Flags

Arguments

• <request-id> - ID of the target request

tsh request review

Review an Access Request

tsh request review [<flags>] <request-id>

Flags

Arguments

• <request-id> - ID of the target request

tsh request search

Search for resources to request access to

tsh request search [<flags>]

Flags

tsh request drop

Drop one or more access requests from current identity

tsh request drop [<request-id>...]

Arguments

• <request-id> - IDs of requests to "drop" from the current identity so that your certificate will lose elevated roles and/or resource restrictions. If no request ID is given, the default is to drop all Access Requests.

tsh device enroll

Enroll the current device as a trusted device.

Requires a device enrollment token created via tctl devices enroll.

tsh device enroll --token=TOKEN

Flags

Examples

tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example
Device "C00AA0AAAA0A"/macOS enrolled

tsh environment variables

Environment variables configure your tsh client and can help you avoid using flags repetitively.

tsh configuration files

tsh has an optional configuration files:

• global, shared config: /etc/tsh.yaml. Location can be overridden with TELEPORT_GLOBAL_TSH_CONFIG environment variable.
• user specific config: $TELEPORT_HOME/config/config.yaml. Unless changed, TELEPORT_HOME defaults to ~/.tsh.

The settings from both are merged, with the user config taking precedence.

Extra proxy headers

The tsh configuration file enables you to specify HTTP headers to be included in requests to Teleport Proxy Servers with addresses matching the proxy field.

add_headers:
  - proxy: "*.example.com" # matching proxies will have headers included
    headers: # headers are pairs to include in the http headers
      foo: bar # Key/Value to be included in the http request

Adding HTTP headers may be useful, if for example an intermediate HTTP proxy is in place that requires setting an authentication token:

add_headers:
  - proxy: "*.infra.corp.xyz"
    headers:
      "Authorization": "Bearer tokentokentoken"

Aliases

Aliases allow you to define custom commands or change the default flag values for existing commands using the following syntax:

aliases:
    "<alias>": "<command>"

The <alias> can only be a top-level subcommand. In other words, you can define a tsh mycommand alias but not tsh my command.

New command tsh l:

aliases:
    "l": "tsh login --auth=okta"

Make tsh status use JSON as a default format:

aliases:
    "status": "tsh status --format=json"

The alias can use an arbitrary number of arguments. If an argument variable $N is referenced, tsh will check that at least N+1 arguments were given to the alias invocation. All arguments that were given but not referenced in the alias definition will be appended at the end.

Define a custom command using bash. The $0 and $1 variables will be substituted with command arguments.

aliases:
    "connect": "bash -c 'tsh login $0 && tsh ssh $1'"

Define a custom login command where first argument specifies --auth option.

aliases:
    "ap": "tsh login --auth=$0 --proxy=teleport.example.com"

Given the configuration:

aliases:
    "example": "bash -c 'echo first=$0 $0-$1 $3'"

tsh example 0 1 unused-2 3 unused-4 will expand to bash -c 'echo first=0 0-1 3 unused-2 unused-4'.

An alias definition can also reference the $TSH variable. tsh will expand this variable to the absolute path of the current tsh executable. This can be useful if there are multiple tsh versions installed, or the currently used version is not in PATH.

aliases:
    "status": "$TSH status --format=json"

To troubleshoot aliases, set the TELEPORT_DEBUG=1 environment variable. This will cause detailed logs to be printed to the console:

$ TELEPORT_DEBUG=1 tsh status
DEBU [TSH]       Self re-exec command: tsh [status --format=json]. tsh/aliases.go:203
...

tctl

tctl is a CLI tool that allows a cluster administrator to manage all resources in a cluster, including nodes, users, tokens, certificates, and devices.

tctl can also be used to modify the dynamic configuration of the cluster, such as creating new user roles or connecting Trusted Clusters.

Example

export TELEPORT_CONFIG_FILE=""
tctl tokens add --type=node

tctl global flags

tctl help

Shows help:

tctl help

tctl users add

Generates a user invitation token:

tctl users add [<flags>] <account>

Arguments

• <account> - The Teleport user account name.

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Adds teleport user "joe" with mappings to
OS users and {{ internal.logins }} to "joe" and "ubuntu"
tctl users add joe --roles=access joe,ubuntu
Adds Teleport user "joe" with mappings to the editor role
tctl users add joe --roles=editor

tctl users update

Update user account:

tctl users update [<flags>] <account>

Arguments

• <account> - The Teleport user account name.

Flags

Examples

Set the user joe's roles to access and editor:

tctl users update joe --set-roles=access,editor

Set the user priya's Azure identities to developer and dba:

tctl users update priya --set-azure-identities \ `/subscriptions/${SUBSCRIPTION_ID?}/resourceGroups/${MY_RESOURCE_GROUP?}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/developer,\ `/subscriptions/${SUBSCRIPTION_ID?}/resourceGroups/${MY_RESOURCE_GROUP?}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/dba

tctl users ls

Lists all user accounts:

tctl users ls [<flags>]

tctl users rm

Deletes user accounts:

tctl users rm <logins>

Arguments

• <logins> - comma-separated list of Teleport users

Examples

tctl users rm sally,tim
Removes users sally and tim

tctl users reset

Reset local user account password and any associated second factor with expiring link to populate values. Usage: tctl users reset <account>

Arguments

• <account> - Teleport Local DB User

Flags

Examples

tctl users reset jeff
User jeff has been reset. Share this URL with the user to complete password reset, the link is valid for 8h0m0s:
https://teleport.example.com:3080/web/reset/8a4a40bec3a31a28db44fa64c0c70ca3
Resets jeff's password and any associated second factor.  Jeff populates the password and confirms the token with the link.

tctl request ls

List of open requests:

tctl request ls

Examples

tctl request ls
Token                                Requestor Metadata       Created At (UTC)    Status
------------------------------------ --------- -------------- ------------------- -------
request-id-1                         alice     roles=dictator 07 Nov 19 19:38 UTC PENDING

tctl request approve

Approve a user's request:

tctl request approve [token]

Arguments

• <tokens> - comma-separated list of Teleport tokens.

Examples

tctl request approve request-id-1, request-id-2

tctl request deny

Denies a user's request:

tctl request deny [token]

Arguments

• <tokens> - comma-separated list of Teleport tokens.

Examples

tctl request deny request-id-1, request-id-2

tctl request rm

Delete a users role request:

tctl request rm [token]

Arguments

• <tokens> - comma-separated list of Teleport tokens.

Examples

tctl request rm request-id-1

tctl nodes add

Generate a node invitation token:

tctl nodes add [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Generates a token that can be used by a node to join the cluster, default ttl is 30 minutes
tctl nodes add
Generates a token that can be used to add an SSH node to the cluster.
The node will run both the proxy service and the node (ssh) service.
This token can be used within an hour.
tctl nodes add --roles=node,proxy --ttl=1h

tctl nodes ls

List all active SSH nodes within the cluster:

tctl nodes ls [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

tctl tokens add

Create an invitation token:

tctl tokens add --type=TYPE [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

Generate an invite token for a trusted_cluster
tctl tokens add --type=trusted_cluster --ttl=5m
Generate an invite token for a trusted_cluster with labels
tctl tokens add --type=trusted_cluster --labels=env=prod
Generate an invite token for a node
This is equivalent to `tctl nodes add`
tctl tokens add --type=node
Generate a join token for both a Node and the Database Service
tctl tokens add --type=node,db
Generate an invite token for a kubernetes_service
tctl tokens add --type=kube
Generate an invite token for an app_service
tctl tokens add --type=app

tctl tokens rm

Delete/revoke an invitation token:

tctl tokens rm [<token>]

Arguments

• <token> The full-length token string to delete

tctl tokens ls

List node and user invitation tokens:

tctl tokens ls [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Example

tctl tokens ls
Token                            Type            Expiry Time (UTC)
-------------------------------- --------------- -------------------
abcd123-insecure-do-not-use-this Node            11 Oct 19 22:17 UTC
efgh456-insecure-do-not-use-this trusted_cluster 11 Oct 19 22:19 UTC
ijkl789-insecure-do-not-use-this User signup     11 Oct 19 22:20 UTC

tctl auth export

Export public cluster (CA) keys to stdout:

tctl auth export [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run:

tctl help <subcommand>

or see the Global Flags section.

Examples

Export all keys
tctl auth export
Filter by fingerprint
tctl auth export --fingerprint=SHA256:8xu5kh1CbHCZRrGuitbQd4hM+d9V+I7YA1mUwA/2tAo
Export tls certs only
tctl auth export --type tls

tctl auth sign

Create an identity file(s) for a given user:

tctl auth sign -o <filepath> [--user <user> | --host <host>][--format] [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Export identity file to teleport_id.pem
for user `teleport` with a ttl set to 5m
tctl auth sign --format file --ttl=5m --user teleport -o teleport_id.pem
Export identity formatted for openssh to teleport_id.pem
tctl auth sign --format openssh --user teleport -o teleport_id.pem
Export host identity, `--format openssh` must be set with `--host`
Generates grav-01 (private key) and grav-01-cert.pub in the current directory
tctl auth sign --format openssh --host grav-00
Invalid command, only one of --user or --host should be set
tctl auth sign --format openssh --host grav-00 --user teleport -o grav_host
error: --user or --host must be specified
create a certificate with a TTL of 24 hours for the jenkins user
the jenkins.pem file can later be used with `tsh`
tctl auth sign --ttl=24h --user=jenkins --out=jenkins.pem
create a certificate with a TTL of 3 months for the jenkins user
the jenkins.pem file can later be used with `tsh`
tctl auth sign --ttl=2190h --user=jenkins --out=jenkins.pem
create a certificate with a TTL of 1 day for the jenkins user
The kubeconfig file can later be used with `kubectl` or compatible tooling.
tctl auth sign --ttl=24h --user=jenkins --out=kubeconfig --format=kubernetes
Exports an identity from the Auth Server in preparation for remote
tctl execution.
tctl auth sign --user=admin --out=identity.pem

tctl auth rotate

Rotate certificate authorities in the cluster:

tctl auth rotate [<flags>]

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

Rotate only user certificates with a grace period of 200 hours:
tctl auth rotate --type=user --grace-period=200h
Rotate only host certificates with a grace period of 8 hours:
tctl auth rotate --type=host --grace-period=8h

tctl sso test

Perform an end-to-end test of an SSO authentication flow using the provided auth connector definition.

The command supports all auth connector types: github, oidc and saml. The latter two require Teleport Enterprise.

tctl [<global-flags>] sso test [<auth-connector.yaml>]

The testing consists of running a single end-to-end authentication request using the provided auth connector definition. Once the request is finished, the results will be printed to standard output along with context-specific diagnostic information. The test process is safe from side effects in that:

• it will not change the list of configured auth connectors
• the audit log will clearly state the login attempts as "test" ones
• there will be no certificates issued for the authenticated user

- resources: [github_request]
  verbs: [list,create,read,update,delete]
- resources: [oidc_request]
  verbs: [list,create,read,update,delete]
- resources: [saml_request]
  verbs: [list,create,read,update,delete]

Arguments

• [<filename>] Connector resource definition file. Optional. Empty for stdin.

Flags

This command defines no flags.

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Test the auth connector from connector.yaml:

tctl sso test connector.yaml

The command is designed to be used in conjunction with the tctl sso configure family of commands:

tctl sso configure ... | tctl sso test

The pipeline may also utilize tee to capture the connector generated with tctl sso configure. This will save the connector in connector.yaml:

tctl sso configure ... | tee connector.yaml | tctl sso test

You can test an existing auth connector by combining the command with tctl get:

$ tctl get saml/your-connector-name --with-secrets | tctl sso test

tctl sso configure github

Configure the GitHub auth connector.

Required params --id and --secret come from registering a GitHub OAuth app, which you can read about in the GitHub documentation.

The flag --teams-to-roles can be provided multiple times to specify which GitHub Teams are assigned which roles. In this example, members of the octocats team in GitHub will be assigned the devs, access, and editor roles in Teleport.

tctl sso test --id=GITHUB_CLIENT_ID --secret=GITHUB_SECRET --teams-to-roles=octocats,devs,access,editor [<other-flags>]

Arguments

This command accepts no arguments.

Flags

Mandatory flags: --id, --secret, --teams-to-roles.

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Generate a GitHub auth connector. Two role mappings are defined:

• members of the admin team in the octocats org will receive access, editor and auditor roles.
• members of the dev team in octocats org will receive the access role.

tctl sso configure gh -r octocats,admin,access,editor,auditor -r octocats,dev,access --secret GH_SECRET --id CLIENT_ID
INFO [CLIENT]    RedirectURL empty, resolving automatically.
INFO [CLIENT]    RedirectURL set to "https://teleport.example.com:3080/v1/webapi/github/callback"
kind: github
metadata:
  name: github
spec:
  client_id: CLIENT_ID
  client_secret: GH_SECRET
  display: ""
  redirect_url: https://teleport.example.com:3080/v1/webapi/github/callback
  teams_to_logins:
  - logins:
    - access
    - editor
    - auditor
    organization: octocats
    team: admin
  - logins:
    - access
    organization: octocats
    team: dev
version: v3

Generate the configuration and immediately test it using tctl sso test command.

tctl sso configure gh ... | tctl sso test

tctl sso configure oidc

Configure an OIDC auth connector, optionally using a preset.

The flag --claims-to-roles can be provided multiple times.

tctl sso configure oidc --id=CLIENT_ID --secret=SECRET --claims-to-roles=... [<other-flags>]

Arguments

This command accepts no arguments.

Flags

Mandatory flags: --id, --secret, --claims-to-roles. Other flags may be required depending on chosen preset.

General flags:

Supported presets:

The above values for --issuer-url are defaults which may need to be updated depending on your IdP configuration.

The following flags are specific to Google Workspace:

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

1. Generate an OIDC auth connector configuration called myauth. Two mappings from OIDC claims to roles are defined:
   • members of admin group will receive access, editor and auditor roles.
   • members of developer group will receive access role.

The values for --secret, --id and --issuer-url are provided by the IdP.

tctl sso configure oidc -n myauth -r groups,admin,access,editor,auditor -r group,developer,access \      --secret IDP_SECRET --id CLIENT_ID                                                            \      --issuer-url https://idp.example.com

2. Generate an OIDC auth connector with the Okta preset, enabling the groups scope and mapping the okta-admin group to roles access, editor, auditor. Issuer URL is set to match a custom Okta domain.

tctl sso configure oidc --preset okta --scope groups -r groups,okta-admin,access,editor,auditor \      --secret IDP_SECRET --id CLIENT_ID                                                          \      --issuer-url dev-123456.oktapreview.com

3. Generate an OIDC auth connector with the Google preset. Service account credentials are set to be loaded from /var/lib/teleport/gacc.json with --google-acc-uri.

tctl sso configure oidc --preset google -r groups,[email protected],access \      --secret SECRET --google-id GOOGLE_ID --google-acc-uri /var/lib/teleport/gacc.json \      --google-admin [email protected]

4. Generate the configuration and immediately test it using the tctl sso test command.

tctl sso configure oidc ... | tctl sso test

tctl sso configure saml

Configure the SAML auth connector, optionally using a preset.

The flag --attributes-to-roles/-r can be provided multiple times.

To avoid errors when pasting XML to a YAML file, we encourage the usage of the flag --entity-descriptor/-e.

tctl sso configure saml -e entity_desc.xml -r attr,value,role1 [<other-flags>]

Arguments

This command accepts no arguments.

Flags

Mandatory flags: --name, --attributes-to-roles, --entity-descriptor. These flags may become non-mandatory when other flags are present; see table below for details.

Supported presets:

Global flags

These flags are available for all commands: --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

1. Generate a SAML auth connector configuration called myauth. Two mappings from SAML attributes to roles are defined:
   • members of admin group will receive access, editor and auditor roles.
   • members of developer group will receive access role. The IdP metadata will be read from entity-desc.xml file.

tctl sso configure saml -n myauth -r group,admin,access,editor,auditor -r group,developer,access -e entity-desc.xml

2. Generate a SAML auth connector configuration using the okta preset. The choice of preset affects the default name and display attribute, and may apply IdP-specific tweaks. Instead of an XML file, a URL was provided to the -e flag, which will be fetched by Teleport during runtime.

tctl sso configure saml -p okta -r group,dev,access -e https://dev-123456.oktapreview.com/app/ex30h8/sso/saml/metadata

3. Generate a configuration and immediately test it using the tctl sso test command:

tctl sso configure saml -p okta -r group,developer,access -e entity-desc.xml | tctl sso test

tctl login_rule test

Test a Login Rule resource without installing it in the cluster.

Arguments

• <traits-file> input traits file in JSON or YAML format. Empty for stdin.

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Test evaluation of the Login Rules from rule1.yaml and rule2.yaml with input traits from traits.json

tctl login_rule test --resource-file rule1.yaml --resource-file rule2.yaml traits.json

Test the Login Rule in rule.yaml along with all Login Rules already present in the cluster

tctl login_rule test --resource-file rule.yaml --load-from-cluster traits.json

Read the input traits from stdin

echo '{"groups": ["example"]}' | tctl login_rule test --resource-file rule.yaml

tctl create

Create or update a Teleport resource from a YAML file.

The supported resource types are: user, node, cluster, role, connector, and device. See the Resources Reference for complete docs on how to build these yaml files.

tctl create [<flags>] <filename>

Arguments

• <filename> resource definition file

Flags

Global flags

These flags are available for all commands --debug, --config. Run tctl help <subcommand> or see the Global Flags section.

Examples

Update a user record
tctl create -f joe.yaml
Add a trusted cluster
tctl create cluster.yaml
Update a trusted cluster
tctl create -f cluster.yaml

tctl rm

Delete a resource:

tctl rm <resource-type/resource-name>

Arguments

• <resource-type/resource-name> Resource to delete
  • <resource type> Type of a resource [for example: saml,oidc,github,user,cluster,tokens,device]
  • <resource name> Resource name to delete

Examples

Delete a SAML connector called "okta":
tctl rm saml/okta
Delete a local user called "admin":
tctl rm users/admin

tctl get

Print a YAML declaration of various Teleport resources:

tctl get [<flags>] <resource-type/resource-name>,...

Arguments

• <resource-type/resource-name> The resource to get
  • <resource type> The type of the resource [for example: user,cluster,token,device]
  • <resource name> The name of the resource

Flags

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

tctl get users
Dump the user definition into a file:
tctl get user/joe > joe.yaml
Prints the trusted cluster 'east'
tctl get cluster/east
Prints all trusted clusters and all users
tctl get clusters,users
Dump all resources for backup into state.yaml
tctl get all > state.yaml

tctl edit

Modify a Teleport resource using your preferred text editor.

tctl edit <resource-type/resource-name>

The text editor is selected by checking the following, in order of precedence:

• the TELEPORT_EDITOR environment variable
• the VISUAL environment variable
• the EDITOR environment variable
• defaulting to vi

tctl will fetch the resource from the backend and open it in the selected editor. When the editor process terminates, tctl will push the updates to the Teleport cluster. To abandon the edit, close the editor without saving the file.

Some graphical editors like VS Code launch a background process rather than running in the foreground. This prevents tctl from properly detecting when the editor process terminates. To work around this, check whether your editor supports a "wait" option that waits for files to be closed before terminating. For example, to edit a Teleport resource with VS Code, you can set TELEPORT_EDITOR="code --wait".

Note: Renaming resources with tctl edit is not supported since Teleport resources often refer to other resources by name. To rename a resource, we recommend you:

• fetch the resource with tctl get and redirect the output to a file
• change the name of the resource in the file
• save the new resource with tctl create -f
• update any references to the old resource

Arguments

• <resource-type/resource-name> The resource to edit
  • <resource type> The type of the resource [for example: user,cluster,token]
  • <resource name> The name of the resource

Global flags

These flags are available for all commands --debug, --config . Run tctl help <subcommand> or see the Global Flags section.

Examples

edit the sre role
tctl edit role/sre
edit the alice user with the nano editor
TELEPORT_EDITOR=nano tctl edit user/alice

tctl status

Report cluster status:

tctl status

Examples

Checks status of cluster.
tctl status Cluster  grav-00 User CA  never updated Host CA  never updated CA
pin   sha256:1146cdd2b887772dcc2e879232c8f60012a839f7958724ce5744005474b15b9d
Checks remote auth status using exported identity.
tctl status \    --auth-server=192.168.99.102:3025 \    --identity=identity.pem

tctl alerts create

Creates cluster alerts. Cluster alerts can be displayed to Teleport users in the web UI or upon logging via tsh.

tctl alerts create [<flags>] <message>

Arguments

• <message>: The message for the alert to display

Flags

While any labels can be applied to an alert, there are several internal labels that can be used to configure the behavior of alerts:

• teleport.internal/alert-on-login: yes: ensures that the alert is displayed to users upon login
• teleport.internal/alert-permit-all: yes: ensures that the alert is displayed to all users

If no labels are specified, tctl will automatically add both of these labels.

Examples

tctl alerts create \    --severity=low \    --ttl=4h \    "The system is under maintenance, functionality may be limited."

tctl devices add

Register a device.

tctl devices add --os=OS --asset-tag=SERIAL_NUMBER

Flags

Examples

tctl devices add --os=macos --asset-tag=C00AA0AAAA0A
Device C00AA0AAAA0A/macOS added to the inventory
tctl devices add --os=macos --asset-tag=C00AA0AAAA0A --enroll
Device C00AA0AAAA0A/macOS added to the inventory
Run the command below on device "C00AA0AAAA0A" to enroll it:
tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example

tctl devices enroll

Create an enrollment token for a device.

tctl devices enroll [--device-id=ID] [--asset-tag=ASSET_TAG]

Flags

One of --device-id or --asset-tag must be present.

Examples

tctl devices enroll --device-id=d40f2ee4-856d-4aef-b784-c4371e39c036
Run the command below on device "d40f2ee4-856d-4aef-b784-c4371e39c036" to enroll it:
tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example
tctl devices enroll --asset-tag=C00AA0AAAA0A
Run the command below on device "C00AA0AAAA0A" to enroll it:
tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example

tctl devices ls

List registered devices.

tctl devices ls

Examples

tctl devices ls
Asset Tag    OS    Enroll Status Device ID
------------ ----- ------------- ------------------------------------
C00AA0AAAA0A macOS enrolled      d40f2ee4-856d-4aef-b784-c4371e39c036

tctl devices rm

Removes a registered device.

A removed device is not considered a trusted device for future device authentication attempts.

tctl devices rm [--device-id=ID] [--asset-tag=ASSET_TAG]

Flags

One of --device-id or --asset-tag must be present.

Examples

tctl devices rm --device-id=d40f2ee4-856d-4aef-b784-c4371e39c036
Device "ac3590ec-87d4-4519-8e9e-2f35af0a9f85" removed
tctl devices rm --asset-tag=C00AA0AAAA0A
Device "C00AA0AAAA0A" removed

tctl top

Reports diagnostic information.

The diagnostic metrics endpoint must be enabled with teleport start --diag-addr=<bind-addr> for tctl top to work.

tctl top [<diag-addr>] [<refresh>]

Argument

• [<diag-addr>] Diagnostic HTTP URL (HTTPS not supported)
• [<refresh>] Refresh period e.g. 5s, 2m, or 3h

Example

sudo teleport start --diag-addr=127.0.0.1:3000
View stats with a refresh period of 5 seconds
tctl top http://127.0.0.1:3000 5s

tctl version

Print the version of your tctl binary:

tctl version

Resource filtering

Both tsh and tctl allow you to filter servers, applications, databases, desktops, and Kubernetes clusters using the --search and --query flags.

The --search flag performs a simple fuzzy search on resource fields. For example, --search=mac searches for resources containing mac.

The --query flag allows you to perform more sophisticated searches using a predicate language.

In both cases, you can further refine the results by appending a list of comma-separated labels to the command. For example:

tsh ls --search=foo,bar labelKey1=labelValue1,labelKey2=labelValue2

Filter Examples

List all nodes
tsh ls
List nodes using label argument
tsh ls env=staging,os=mac
List nodes using search keywords
tsh ls --search=staging,mac
List nodes using predicate language. This query searches for nodes with labels
with key `env` equal to `staging` and key `os` equal to `mac`.
tsh ls --query='labels["env"] == "staging" && equals(labels["os"], "mac")'

tbot

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 start

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

Flags

Examples

tbot start \   --data-dir=/var/lib/teleport/bot \   --destination-dir=/opt/machine-id \   --token=00000000000000000000000000000000 \   --join-method=token \   --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \   --auth-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 \   --auth-server=auth.example.com:3025

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.

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

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

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

Flags