Fork me on GitHub

Teleport

Teleport CLI Reference

Improve

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

When running Teleport in production, we recommend that you follow the practices below to avoid security incidents. These practices may differ from the examples used in this guide, which are intended for demo environments:

  • Avoid using sudo in production environments unless it's necessary.
  • Create new, non-root, users and use test instances for experimenting with Teleport.
  • Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
  • Follow the "Principle of Least Privilege" (PoLP). Don't give users permissive roles when giving them more restrictive roles will do instead. For example, assign users the built-in access,editor roles.
  • When joining a Teleport resource service (e.g., the Database Service or Application Service) to a cluster, save the invitation token to a file. Otherwise, the token will be visible when examining the teleport command that started the agent, e.g., via the history command on a compromised system.
Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

teleport

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

The primary commands for the teleport CLI are as follows:

CommandDescription
teleport helpOutputs guidance for using Teleport commands.
teleport startStarts the teleport process in the foregound using the current shell session, including any services configured by the configuration YAML file.
teleport statusPrints the status of the current active Teleport SSH session.
teleport configureGenerates and writes a configuration YAML file for the Teleport service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing.
teleport versionPrints the current release version of the Teleport binary installed on your system.
teleport app startStarts the Teleport Application Service.
teleport db startStarts the Teleport Database Service.
teleport db configure createGenerates a configuration YAML file for the Database Service. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing.
teleport db configure bootstrapUsed to bootstrap a configuration to the Teleport Database Service by reading a provided configuration.
teleport db configure aws print-iamGenerates and outputs current IAM policies for a Teleport-managed database.
teleport db configure aws create-iamGenerates, creates, and attaches desired IAM policies to a Teleport-managed database.
teleport install systemdCreates a systemd unit file, used to configure and install a teleport service daemon.
teleport node configureGenerates a configuration YAML file for a Teleport Node accessed via SSH. This file should be customized in production to suit the needs of your environment, and the default output should only be used when testing.

For more information on subcommands when working with the teleport cli, use the --help option or teleport <subcommand> --help.

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

NameDefault Value(s)Allowed Value(s)Description
-d, --debugnonenoneenable verbose logging to stderr
--insecure-no-tlsfalsetrue or falseTells proxy to not generate default self-signed TLS certificates. This is useful when running Teleport on kubernetes (behind reverse proxy) or behind things like AWS ELBs, GCP LBs or Azure Load Balancers where SSL termination is provided externally.
-r, --rolesproxy, node, auth, app, db, kube, windowsdesktopstring comma-separated list of proxy, auth, node, db, app or windowsdesktopstart listed services/roles. These roles are explained in the Teleport Architecture document.
--pid-filenonestring filepathcreate a PID file at the path
--advertise-ipnonestring IPadvertise IP to clients, often used behind NAT
-l, --listen-ip0.0.0.0net. IPbinds services to IP
--auth-servernonestring IPproxy attempts to connect to a specified auth server instead of local auth, disables --roles=auth if set
--tokennonestringset invitation token to register with an auth server on start, used once and ignored afterwards. Obtain it by running tctl nodes add on the auth server.We recommend to use tools like pwgen to generate sufficiently random tokens of 32+ byte length.
--ca-pinnonestring sha256:<hash>set CA pin to validate the Auth Server. Generated by tctl status
--nodenamevalue returned by the hostname command on the machinestringassigns an alternative name for the node which can be used by clients to log in.
-c, --config/etc/teleport.yamlstring .yaml filepathstarts services with config specified in the YAML file, overrides CLI flags if set
--bootstrapnonestring .yaml filepathbootstrap configured YAML resources
--labelsnonestring comma-separated listassigns a set of labels to a node, for example env=dev,app=web. See the explanation of labeling mechanism in the Labeling Nodes section.
--insecurenonenonedisable certificate validation on Proxy Service, validation still occurs on Auth Service.
--fipsnonenonestart Teleport in FedRAMP/FIPS 140-2 mode.
--skip-version-checkfalsetrue or falseSkips version checks between the Auth Server this Teleport instance
--diag-addrnonenoneEnable diagnostic endpoints
--permit-user-envnonenoneflag reads in environment variables from ~/.tsh/environment when creating a session.
--app-namenonenoneName of the application to start
--app-urinonenoneInternal address of the application to proxy
--app-public-addrnonenonePublic address fo the application to proxy

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:

ServiceRole NameDescription
NodenodeAllows SSH connections from authenticated clients.
AuthauthAuthenticates and authorizes hosts and users who want access to Teleport-managed resources or information about a cluster.
ProxyproxyThe gateway that clients use to connect to the Auth Service or resources managed by Teleport.
AppappProvides access to applications.
DatabasedbProvides access to databases.
Windows DesktopwindowsdesktopProvides Windows Desktop access.

Teleport Cloud manages Teleport instances with the auth and proxy roles. Use the remaining roles to manage access to specific resources and other Teleport clusters.

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

NameDefault Value(s)Allowed Value(s)Description
-l, --loginnonean identity nameThe login identity that the Teleport user will use
--proxynonehost:https_port[,ssh_proxy_port]Teleport Proxy Service address
--user$USERnoneThe Teleport username
--ttl720 (12 hours)integerNumber of minutes a certificate issued for the tsh user will be valid for
-i, --identitynonestring filepathIdentity file
--cert-formatfilefile or opensshSSH certificate format
--insecurenonenoneDo not verify the server's certificate and host name. Use only in test environments.
--authlocalany defined authentication connector, including local and passwordlessSpecify the type of authentication connector to use.
--mfa-modeautoauto, cross-platform, platform or otpPreferred mode for MFA and Passwordless assertions.
--skip-version-checknonenoneSkip version checking between server and client.
-d, --debugnonenoneVerbose logging to stdout
-J, --jumphostnoneA jump hostSSH jumphost

tsh help

Prints help:

tsh help

tsh version

Print the version of your tsh binary:

tsh version

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

NameDefault Value(s)Allowed Value(s)Description
-p, --portnoneportSSH port on a remote host
-A, --forward-agentnonenoneForward agent to target node like ssh -A
-L, --forwardnonenoneForward localhost connections to remote server
-D, --dynamic-forwardnonenoneForward localhost connections to remote server using SOCKS5
-N, -no-remote-execnonenoneDon't execute remote command, useful for port forwarding
--localnoneExecute command on localhost after connecting to SSH node
-t, --ttyfileAllocate TTY
--clusternoneSpecify the cluster to connect
-o, --optionlocalOpenSSH options in the format used in the configuration file
--enable-escape-sequencesEnable support for SSH escape sequences. Type ~? during an SSH session to list supported sequences.
--no-use-local-ssh-agentDo not load generated SSH certificates into the local ssh-agent (specified via $SSH_AUTH_SOCK). Useful when using gpg-agent or Yubikeys. You can also set the TELEPORT_USE_LOCAL_SSH_AGENT environment variable to false (default true)
-X, --x11-untrustednonenoneRequests untrusted (secure) X11 forwarding for this session.
-Y, --x11-trustednonenoneRequests trusted (insecure) X11 forwarding for this session. This can make your local machine vulnerable to attacks, use with caution.
--x11-untrusted-timeout10mdurationSets a timeout for untrusted X11 forwarding, after which the client will reject any forwarding requests from the server.

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

NameDefault Value(s)Allowed Value(s)Description
--clusternonea cluster_nameSpecify the cluster to connect

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

NameDefault Value(s)Allowed Value(s)Description
--clusternonea cluster_nameSpecify the cluster to connect
--formatptyjson, ptyFormat for playback

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

NameDefault Value(s)Allowed Value(s)Description
--portnoneport numberSpecify the source port for the local proxy

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 scp

Copies files from source to dest:

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

Arguments

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

Flags

NameDefault Value(s)Allowed Value(s)Description
--clusternonea cluster_nameSpecify the cluster to connect
-r, --recursivenonenoneRecursive copy of subdirectories
-P, --portnoneport numberPort to connect to on the remote host
-q, --quietnonenoneQuiet mode

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 -P example.txt [email protected]:/destination/dir

tsh ls

List cluster nodes:

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

When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to display Nodes in the Web UI or via tsh ls), it only returns the Nodes that the current user is authorized to view.

For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:

  • None of the user's roles contain a deny rule that matches the Node's labels.
  • None of the user's roles contain a deny rule that matches the user's login.
  • At least one of the user's roles contains an allow rule that matches the Node's labels.
  • At least one of the user's roles contains an allow rule that matches the user's login.

If you are not seeing Nodes when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Teleport Access Controls Reference.

Arguments

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

Flags

NameDefault Value(s)Allowed Value(s)Description
-v, --verbosenonenonealso print Node ID

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

NameDefault Value(s)Allowed Value(s)Description
-q, --quietnonenoneno headers in output

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

NameDefault Value(s)Allowed Value(s)Description
--bind-addrnonehost:portAddress in the form of host:port to bind to for login command webhook
-o, --outnonefilepathIdentity output filepath
--formatfilefile, openssh or kubernetesIdentity format: file, openssh (for OpenSSH compatibility) or kubernetes (for kubeconfig)
--browsernonenoneSet to 'none' to suppress opening system default browser for tsh login commands
--request-rolesnoneRequest one or more extra roles
--request-reasonnoneReason for requesting additional roles
--request-nowaitnoneFinish without waiting for request resolution
--request-idnoneLogin with the roles requested in the given request
--no-use-local-ssh-agentDo not load generated SSH certificates into the local ssh-agent (specified via $SSH_AUTH_SOCK). Useful when using gpg-agent or Yubikeys. You can also set the TELEPORT_USE_LOCAL_SSH_AGENT environment variable to false (default true)

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 --user=admin 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

NameDefault Value(s)Allowed Value(s)Description
--allfalseBooleanWhether to generate a kubeconfig for every Kubernetes cluster the current Teleport user has access to. If this is false, tsh will only generate a kubeconfig for the cluster specified in the tsh kube login command.
--asnonestringThe Kubernetes user that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster.

This uses Kubernetes impersonation, so the Teleport user's Kubernetes user must have permissions to impersonate the target user.
--as-groupsnonestringA Kubernetes group that the current Teleport user will log in as when they authenticate to the specified Kubernetes cluster.

This uses Kubernetes impersonation, so the Teleport user's Kubernetes user must have permissions to impersonate the target group.

You can include this flag multiple times to enable impersonation of multiple Kubernetes groups.
--clusternonestringName of the Teleport cluster to log into in order to connect to the given Kubernetes cluster.
-n, --kube-namespacenonestringThe name of the Kubernetes namespace to configure as the default within the cluster the user is logging into.

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 new

Create a new Access Request.

tsh request new [<flags>]

Flags

NameDefault Value(s)Allowed Value(s)Description
--rolesnoneComma-separated stringsList of Teleport roles to request
--resourcenoneString (flag can be repeated to request multiple resources)Resource ID to be requested
--reasonnoneStringReason for making the request (optional)
--reviewersnoneComma-separated stringsSuggested reviewers for the request (optional)
--nowaitfalsetrue or falseFinish without waiting for request resolution

tsh request ls

List Access Requests

tsh request ls

Flags

NameDefault Value(s)Allowed Value(s)Description
--formattexttext, json, or yamlFormat output
--reviewablefalsetrue or falseOnly show requests reviewable by current user
--suggestedfalsetrue or falseOnly show requests that suggest current user as reviewer
--my-requestsfalsetrue or falseOnly show requests created by current user

tsh request show

Show Access Request details

tsh request show <request-id>

Flags

NameDefault Value(s)Allowed Value(s)Description
--formattexttext, json, or yamlFormat output

Arguments

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

tsh request review

Review an Access Request

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

Flags

NameDefault Value(s)Allowed Value(s)Description
--approvefalsetrue or falseReview proposes approval
--denyfalsetrue or falseReview proposes denial
--reasonnoneStringReview reason message

Arguments

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

Search for resources to request access to

tsh request search [<flags>]

Flags

NameDefault Value(s)Allowed Value(s)Description
--kindnonenode, kubernetes_cluster, db, app, windows_desktopResource kind to search for (required)
--searchnoneComma-separated stringsList of comma-separated search keywords or phrases enclosed in single quotes
--querynoneStringQuery by predicate language enclosed in single quotes
--labelsnoneComma-separated stringsList of comma-separated labels to filter by labels (e.g. key=value1,key2=value2)

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 environment variables

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

Environment VariableDescriptionExample Value
TELEPORT_AUTHName of a defined local, SAML, OIDC, or GitHub auth connectorokta
TELEPORT_MFA_MODEPreferred mode for MFA and Passwordless assertionsotp
TELEPORT_CLUSTERName of a Teleport root or leaf clustercluster.example.com
TELEPORT_LOGINLogin name to be used by default on the remote hostroot
TELEPORT_LOGIN_BIND_ADDRAddress in the form of host:port to bind to for login command webhookhost:port
TELEPORT_PROXYAddress of the Teleport proxy servercluster.example.com:3080
TELEPORT_HOMEHome location for tsh configuration and data/directory
TELEPORT_USERA Teleport user namealice
TELEPORT_ADD_KEYS_TO_AGENTSpecifies if the user certificate should be stored on the running SSH agentyes, no, auto, only
TELEPORT_USE_LOCAL_SSH_AGENTDisable or enable local SSH agent integrationtrue, false
TELEPORT_GLOBAL_TSH_CONFIGOverride location of global tsh config file from default /etc/tsh.yaml/opt/teleport/tsh.yaml

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 --username=alice"

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, and certificates.

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

When running tctl commands, administrators must authenticate to a Teleport cluster. This can be done in three ways:

On a remote host with an identity file

tctl can authenticate with a user-provided identity file. The Teleport Auth Service signs an identity file when a user runs tctl auth sign or tsh login --out=<output-path>, and the user can include the path to the identity file in the --identity flag when running tctl commands.

When using the --identity flag, the user must provide the --auth-server flag with the address of an Auth Service or Proxy Service so tctl knows which cluster to authenticate to.

On the same host as the Teleport Auth Service

If there is a Teleport configuration file on the host where tctl is run, tctl attempts to authenticate to the Auth Service named in the configuration file using an identity stored in its local backend.

tctl only authenticates using this method if an identity file is not provided.

Note

Note that when a tctl command is run locally on the Auth Service, the audit logs will show that it was performed by the Auth Service itself.

To provide an accurate audit trail, it is important to limit direct SSH access to the Auth Service with Access Controls and ensure that admins use tctl remotely instead.

On a remote host after running tsh login

If tctl cannot find a local Teleport configuration file or a user-provided identity file, it attempts to load the user's tsh profile to authenticate to the cluster. The tsh profile is created when a user runs tsh login.

tctl reads the TELEPORT_CONFIG_FILE environment variable to determine if a Teleport configuration file is present. If you are using your tsh profile to authenticate tctl, you must ensure that one of these conditions is true:

  • TELEPORT_CONFIG_FILE is blank
  • No file exists at /etc/teleport.yaml

Otherwise tctl will attempt to connect to a Teleport cluster on the machine, which could result in the error, ERROR: open /var/lib/teleport/host_uuid: permission denied.

When running tctl commands, administrators must authenticate to a Teleport cluster. This can be done in two ways:

On a remote host with an identity file

tctl can authenticate with a user-provided identity file. The Teleport Auth Service signs an identity file when a user runs tctl auth sign or tsh login --out=<output-path>, and the user can include the path to the identity file in the --identity flag when running tctl commands.

When using the --identity flag, the user must alo provide the --auth-server flag with the address of an Auth Service or Proxy Service so tctl knows which cluster to authenticate to.

On a remote host after running tsh login

If tctl cannot find a local Teleport configuration file or a user-provided identity file, it attempts to load the user's tsh profile to authenticate to the cluster. The tsh profile is created when a user runs tsh login.

tctl reads the TELEPORT_CONFIG_FILE environment variable to determine if a Teleport configuration file is present. If you are using your tsh profile to authenticate tctl, you must ensure that one of these conditions is true:

  • TELEPORT_CONFIG_FILE is blank
  • No file exists at /etc/teleport.yaml

Otherwise tctl will attempt to connect to a Teleport cluster on the machine, which could result in the error, ERROR: open /var/lib/teleport/host_uuid: permission denied.

Example

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

tctl global flags

NameDefault Value(s)Allowed Value(s)Description
-d, --debugnonenoneEnable verbose logging to stderr
-c, --config/etc/teleport.yamlstring filepathPath to a configuration file
--auth-servernonehost:portAttempts to connect to specific Auth/Proxy Service address(es) instead of a local Auth Service (127.0.0.1:3025)
-i, --identitynonestring filepathPath to an identity file
--insecurenonenoneWhen specifying a Proxy Service address in --auth-server, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker

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

NameDefault Value(s)Allowed Value(s)Description
--rolesnoneComma-separated stringsList of Teleport roles to assign to the new user
--loginsnoneComma-separated stringsList of allowed SSH logins for the new user
--kubernetes-groupsnoneComma-separated stringsKubernetes groups to assign to a user, e.g. system:masters
--kubernetes-usersnoneComma-separated stringsKubernetes user to assign to a user, e.g. jenkins
--db-usersnoneComma-separated stringsList of allowed database users for the new user
--db-namesnoneComma-separated stringsList of allowed database names for the new user
--windows-loginsnoneComma-separated stringsList of allowed Windows logins for the new user
--aws-role-arnsnoneComma-separated stringsList of allowed AWS role ARNs for the new user
--ttl1hrelative duration like 5s, 2m, or 3h, maximum 48hSet expiration time for token

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

NameDefault Value(s)Allowed Value(s)Description
--set-rolesnonea role nameComma-separated list of roles for the user to assume, replaces current roles

Examples

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

Assigns roles "access" and "editor" to user "joe"

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

NameDefault Value(s)Allowed Value(s)Description
--ttl8hrelative duration like 5s, 2m, or 3hSet the expiration time for token, default is 8h0m0s, maximum is 24h0m0s

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

NameDefault Value(s)Allowed Value(s)Description
--rolesnodeproxy, auth, node, db, app or windowsdesktopComma-separated list of roles for the new node to assume
--ttl30mrelative duration like 5s, 2m, or 3hTime to live for a generated token
--tokennonestring token valueA custom token to use, auto-generated if not provided. Should match token set with teleport start --token

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

NameDefault Value(s)Allowed Value(s)Description
--namespacenonestring namespaceNamespace of the nodes

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

NameDefault Value(s)Allowed Value(s)Description
--typenoneproxy, auth, trusted_cluster, node, db, kube, app, windowsdesktopType of token to add
--valuenonestring token valueValue of token to add
--ttl1hrelative duration like 5s, 2m, or 3hSet expiration time for token
--formatnonetext, json, yamlOutput format

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

NameDefault Value(s)Allowed Value(s)Description
--formatnonetext, json, yamlOutput format

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

NameDefault Value(s)Allowed Value(s)Description
--keysnonenoneif set, will print private keys
--fingerprintnonestring e.g. SHA256:<fingerprint>filter authority by fingerprint
--compatnoneversion numberexport certificates compatible with specific version of Teleport
--typenoneuser, host or tlscertificate type

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

NameDefault Value(s)Allowed Value(s)Description
--usernoneexisting userTeleport user name
--hostnoneauth hostTeleport host name
-o, --outnonefilepathidentity output
--overwritenonenoneWhen specified, write new identity files, even if they already exist
--formatfilefile, openssh, tls or kubernetesidentity format
--identitynonefileIdentity file to use for logging in to the Auth Service
--auth-servernoneauth host & portRemote Teleport host name
--ttl12hrelative duration like 5s, 2m, or 3hTTL (time to live) for the generated certificate
--compat""standard or oldsshOpenSSH compatibility flag
--proxy""Address of the Teleport Proxy ServiceWhen --format is set to kubernetes, this address will be set as the cluster address in the generated kubeconfig file
--leaf-cluster""The name of a leaf cluster.
--kube-cluster-name""Kubernetes Cluster Name
--app-name""application nameGenerate a certificate for accessing the specified web application
--db-service""database service nameGenerate a certificate for accessing the specified database service
--db-user""database userWhen --db-service is specified, encode this database user in the certificate
--db-name""database nameWhen --db-service is specified, encode this database name in the certificate

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

NameDefault Value(s)Allowed Value(s)Description
--grace-periodnonerelative duration like 5s, 2m, or 3hGrace period keeps previous certificate authorities signatures valid, if set to 0 will force users to log in again and nodes to re-register.
--manualnonenoneActivate manual rotation, set rotation phases manually
--typeuser,hostuser or hostCertificate authority to rotate
--phaseinit, standby, update_clients, update_servers, rollbackTarget rotation phase to set, used in manual rotation

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
Important

To use this command, you must have access to the github_request, oidc_request, and saml_request resources (depending on the type of connector being tested).

If you receive a "permission denied" error, ensure that you have access to the following resources in one of your Teleport roles:

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

Make sure to include --with-secrets flag, or the exported auth connector will not be testable.

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.

NameDefault Value(s)Allowed Value(s)Description
-n, --namegithubresource nameConnector name.
-r, --teams-to-rolesnoneorg,team,role1,role2,...Sets teams-to-roles mapping. Repeatable.
--displaynonedisplay nameControls how this connector is displayed.
--idnoneGitHub OAuth2 client idGitHub app client ID.
--secretnoneGitHub OAuth2 secretGitHub app client secret.
--redirect-urlnoneValid callback URL.Authorization callback URL.
--ignore-missing-rolesIgnore missing roles referenced in --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.
Note

tctl sso configure gh is an alias for tctl sso configure github.

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:

NameDescription
-p, --presetPreset. One of: google, gitlab, okta.
-n, --nameConnector name. Required, unless implied from preset.
-r, --claims-to-rolesSets claim-to-roles mapping using format claim_name,claim_value,role1,role2,.... Repeatable.
--displayDisplay controls how this connector is displayed.
--idOIDC app client ID.
--secretOIDC app client secret.
--issuer-urlIssuer URL.
--redirect-urlAuthorization callback URL.
--promptOptional OIDC prompt. Example values: none, select_account, login, consent.
--scopeScope specifies additional scopes set by provider. Each repetition of the flag declares one scope. Examples: email, groups, openid.
--acrAuthentication Context Class Reference values.
--providerSets the external identity provider type to enable IdP specific workarounds. Examples: ping, adfs, netiq, `okta``.
--ignore-missing-rolesIgnore missing roles referenced in --claims-to-roles.

Supported presets:

NameDescriptionDisplayIssuer URL
googleGoogle WorkspaceGooglehttps://accounts.google.com
gitlabGitLabGitLabhttps://gitlab.com
oktaOktaOktahttps://oktaice.okta.com

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:

NameDescription
--google-acc-uriURI of your service account credentials file. Example: file:///var/lib/teleport/gworkspace-creds.json.
--google-accString containing Google service account credentials.
--google-adminEmail of a Google admin to impersonate.
--google-legacyFlag to select groups with direct membership filtered by domain (legacy behavior).
Disabled by default. More info
--google-idShorthand for setting the --id flag to <GOOGLE_WORKSPACE_CLIENT_ID>.apps.googleusercontent.com

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

NameRequired?Description
-p/--presetPreset. One of: okta, onelogin, ad, adfs.
-n/--nameYes, unless --preset is given.Connector name.
-e/--entity-descriptorYes, unless --sso, --acs, --cert and --issuer are also given.Set the Entity Descriptor. Valid values: file path, URL, XML content. Supplies configuration parameters as a single XML document instead of individual elements.
-r/--attributes-to-rolesYes, at least one occurrence must be present.Sets attribute-to-role mapping using format attr_name,attr_value,role1,role2,.... Repeatable.
--displaySets the connector display name.
--issuerSets identity provider issuer.
--ssoURL of the identity provider's SSO service.
--certPath to your IdP's certificate PEM file. Your IdP signs responses using this certificate.
--acsURL for the assertion consumer service on the service provider (Teleport's side).
--audienceUniquely identifies our service provider.
--service-provider-issuerIssuer of the service provider (Teleport).
--signing-key-fileA file with request signing key. Must be used together with --signing-cert-file.
--signing-cert-fileA file with request certificate. Must be used together with --signing-key-file.
--assertion-key-fileA file with key used for securing SAML assertions. Must be used together with --assertion-cert-file.
--assertion-cert-fileA file with cert used for securing SAML assertions. Must be used together with --assertion-key-file.
--providerSets the external identity provider type, enabling workarounds. Examples: ping, adfs.
--ignore-missing-rolesIgnore missing roles referenced in --attributes-to-roles.

Supported presets:

NameDescriptionDisplay
oktaOktaOkta
oneloginOneLoginOneLogin
adAzure Active DirectoryMicrosoft
adfsActive Directory Federation ServicesADFS

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

Create or update a Teleport resource from a YAML file.

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

tctl create [<flags>] <filename>

Arguments

  • <filename> resource definition file

Flags

NameDefault Value(s)Allowed Value(s)Description
-f, --forcenonenoneOverwrite the resource if already exists

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]
    • <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>] Resource to get
    • <resource type> Type of a resource [for example: user,cluster,token]
    • <resource name> Resource name to get

Flags

NameDefault Value(s)Allowed Value(s)Description
--formatyaml, json or textOutput format
--with-secretsnonenoneInclude secrets in resources like certificate authorities or OIDC connectors

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

NameDefault Value(s)Allowed Value(s)Description
--severitylowlow, medium, highAlert severity
--ttlnoneAny durationOptional expiry for alert (alert does not expire if no TTL is specified)
--labelsnoneanyA list of labels to attach to the alert.

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 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 nodes, apps, db, and kube resources 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:

CommandDescription
tbot helpOutputs guidance for using commands with tbot.
tbot versionOutputs the current version of the tbot binary.
tbot configureOutputs a basic Machine ID client configuration file to be adjusted as needed.
tbot startStarts the Machine ID client tbot, fetching and writing certificates to disk at a set interval.
tbot initInitialize a certificate destination directory for writes from a separate bot user, configuring either file or POSIX ACL permissions.
tbot dbConnects to databases using native clients and queries database information. Functions as a wrapper for tsh, and requires tsh installation.
tbot proxyAllows for access to Teleport resources on a cluster using TLS routing. Functions as a wrapper for tsh, and requires tsh installation.

tbot start

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

Flags

FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a Machine ID 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. Can also be an absolute path to a file containing the token.
--ca-pinCA pin to validate the Teleport Auth Server; used on first connect.
--data-dirDirectory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with 0600 permissions.
--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.

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

FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a Machine ID 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.

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

FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a Machine ID configuration file. Required if not using other required configuration flags.
--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.

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 single-port 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

FlagDescription
-d/--debugEnable verbose logging to stderr.
-c/--configPath to a Machine ID configuration file. Required if not using other required configuration flags.
--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.

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

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. Can also be an absolute path to a file containing the token.
--ca-pinCA pin to validate the Teleport Auth Server; used on first connect.
--data-dirDirectory to store internal bot data. In production environments access to this directory should be limited only to an isolated linux user as an owner with 0600 permissions.
--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.