Teleport

Command Line (CLI) Reference

Teleport is made up of three CLI tools.

teleport: The Teleport daemon that runs the Teleport Service, and acts as a daemon on a node allowing SSH connections.
tsh: A tool that lets end users interact with Teleport nodes. This replaces ssh.
tctl: An administrative tool that can configure Teleport Auth Service.

The examples below may include the use of the sudo keyword, token UUIDs, and users with elevated privileges to make following each step easier.

We recommend you follow the best practices to avoid security incidents:

Avoid using sudo in production environments unless it's necessary.
Create new, non-root, users and use test instances for experimenting with Teleport.
You can run many Teleport's services as a non root. For example, auth, proxy, application access, kubernetes access, and database access services can run as a non-root user. Only the SSH/node service requires root access. 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) and "Zero Admin" best practices. Don't give users permissive roles when giving them more restrictive access,editor roles will do instead.
Save tokens into a file rather than sharing tokens directly as strings.

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 Teleport daemon is called teleport. It can be configured to run one or more "roles" with the --roles flags. The arguments to --roles correspond to the following services.

Service	Role Name	Description
Node	`node`	Runs a daemon on a node which allows SSH connections from authenticated clients.
Auth	`auth`	Authenticates nodes and users who want access to Teleport Nodes or information about the cluster.
Proxy	`proxy`	The gateway that clients use to connect to the Auth or Node Services.
App	`app`	Runs a daemon on a node which provides access to applications using an SSH reverse tunnel.
Kube	`kube`	Runs the Teleport node as a kubernetes access server.
DB	`db`	Indicates that the Teleport node should be run as a database access server.
Trusted Cluster	`trusted_cluster`	The node will support a leaf cluster used to connect to another Teleport cluster.

teleport start

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-d, --debug`	none	none	enable verbose logging to stderr
`--insecure-no-tls`	`false`	`true` or `false`	Tells 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, --roles`	`proxy,node,auth`	string comma-separated list of `proxy, node` or `auth`	start listed services/roles. These roles are explained in the Teleport Architecture document.
`--pid-file`	none	string filepath	create a PID file at the path
`--advertise-ip`	none	string IP	advertise IP to clients, often used behind NAT
`-l, --listen-ip`	`0.0.0.0`	net. IP	binds services to IP
`--auth-server`	none	string IP	proxy attempts to connect to a specified auth server instead of local auth, disables `--roles=auth` if set
`--token`	none	string	set 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-pin`	none	string `sha256:<hash>`	set CA pin to validate the Auth Server. Generated by `tctl status`
`--nodename`	`hostname` command on the machine	string	assigns an alternative name for the node which can be used by clients to login. By default it's equal to the value returned by
`-c, --config`	`/etc/teleport.yaml`	string `.yaml` filepath	starts services with config specified in the YAML file, overrides CLI flags if set
`--bootstrap`	none	string `.yaml` filepath	bootstrap configured YAML resources
`--labels`	none	string comma-separated list	assigns a set of labels to a node, for example env=dev,app=web. See the explanation of labeling mechanism in the Labeling Nodes section.
`--insecure`	none	none	disable certificate validation on Proxy Service, validation still occurs on Auth Service.
`--fips`	none	none	start Teleport in FedRAMP/FIPS 140-2 mode.
`--diag-addr`	none	none	Enable diagnostic endpoints
`--permit-user-env`	none	none	flag reads in environment variables from `~/.tsh/environment` when creating a session.
`--app-name`	none	none	Name of the application to start
`--app-uri`	none	none	Internal address of the application to proxy
`--app-public-addr`	none	none	Public address fo the application to proxy

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

teleport status

Shows the status of a Teleport connection:

teleport status

This command is only available from inside of a recorded SSH session.

teleport configure

Dumps a sample configuration file in YAML format into standard output:

teleport configure

warning

Caution: This sample config is not the default config and should be used for reference only.

View Config Reference for all YAML configuration options.

teleport version

Shows the release version:

teleport version

teleport help

Displays help options for teleport:

teleport help

And, for its subcommands:

teleport help <subcommand>

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

Name	Default Value(s)	Allowed Value(s)	Description
`-l, --login`	none	an identity name	the login identity that the Teleport User should use
`--proxy`	none	`host:https_port[,ssh_proxy_port]`	set SSH proxy address
`--user`	`$USER`	none	the Teleport User name
`--ttl`	none	relative duration like 5s, 2m, or 3h	set time to live for a SSH session, session ttl unrestricted if unset
`-i, --identity`	none	string filepath	Identity file
`--cert-format`	`file`	`file` or `openssh`	SSH certificate format
`--insecure`	none	none	Do not verify server's certificate and host name. Use only in test environments
`--auth`	`local`	any defined authentication connector	Specify the type of authentication connector to use.
`--skip-version-check`	none	none	Skip version checking between server and client.
`-d, --debug`	none	none	Verbose logging to stdout
`-J, --jumphost`	none	A jump host	SSH jumphost

tsh help

Prints help:

tsh help

tsh version

Prints client version:

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 A nodename of a cluster node or a
command The command to execute on a remote host.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-p, --port`	none	port	SSH port on a remote host
`-A, --forward-agent`	none	none	Forward agent to target node like `ssh -A`
`-L, --forward`	none	none	Forward localhost connections to remote server
`-D, --dynamic-forward`	none	none	Forward localhost connections to remote server using SOCKS5
`-N, -no-remote-exec`	none	none	Don't execute remote command, useful for port forwarding
`--local`	none		Execute command on localhost after connecting to SSH node
`-t, --tty`	`file`		Allocate TTY
`--cluster`	none		Specify the cluster to connect
`-o, --option`	`local`		OpenSSH options in the format used in the configuration file
`--enable-escape-sequences`			Enable support for SSH escape sequences. Type `~?` during an SSH session to list supported sequences.
`--no-use-local-ssh-agent`			Do 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

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]

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

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	a cluster_name	Specify the cluster to connect

Global Flags

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

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	a cluster_name	Specify the cluster to connect
`--format`	`pty`	json, pty	Format 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 scp

Copies files from source to dest:

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

Arguments

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

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--cluster`	none	a cluster_name	Specify the cluster to connect
`-r, --recursive`	none	none	Recursive copy of subdirectories
`-P, --port`	none	port number	Port to connect to on the remote host
`-q, --quiet`	none	none	Quiet 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>]

Arguments

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

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`-v, --verbose`	none	none	also print Node ID

Global Flags

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

Name	Default Value(s)	Allowed Value(s)	Description
`-q, --quiet`	none	none	no headers in output

Global Flags

Examples

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

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

Name	Default Value(s)	Allowed Value(s)	Description
`--bind-addr`	none	host:port	Address in the form of host:port to bind to for login command webhook
`-o, --out`	none	filepath	Identity output filepath
`--format`	`file`	`file`, `openssh` or `kubernetes`	Identity format: file, openssh (for OpenSSH compatibility) or kubernetes (for kubeconfig)
`--browser`	none	`none`	Set to 'none' to suppress opening system default browser for `tsh login` commands
`--request-roles`	none		Request one or more extra roles
`--request-reason`	none		Reason for requesting additional roles
`--request-nowait`	none		Finish without waiting for request resolution
`--request-id`	none		Login with the roles requested in the given request
`--no-use-local-ssh-agent`			Do 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

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"

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

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

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>

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

Environment Variable	Description	Example Value
TELEPORT_AUTH	Name of a defined SAML, OIDC, or Github auth connector	okta
TELEPORT_CLUSTER	Name of a Teleport root or leaf cluster	cluster.example.com
TELEPORT_LOGIN	Login name to be used by default on the remote host	root
TELEPORT_LOGIN_BIND_ADDR	Address in the form of host:port to bind to for login command webhook	host:port
TELEPORT_PROXY	Address of the Teleport proxy server	cluster.example.com:3080
TELEPORT_HOME	Home location for tsh configuration and data	/directory
TELEPORT_USER	A Teleport user name	alice
TELEPORT_ADD_KEYS_TO_AGENT	Specifies if the user certificate should be stored on the running SSH agent	yes, no, auto, only
TELEPORT_USE_LOCAL_SSH_AGENT	Disable or enable local SSH agent integration	true, false

tctl

tctl is a CLI tool used to administer a Teleport cluster.

tctl 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, like creating new user roles or connecting trusted clusters.

By default, tctl connects to a local Auth server, meaning it will fail if you attempt to run tctl on a non-auth host.

tctl can also connect to a remote Auth server if the --identity and --auth-server flags are used. An identity file for use with --identity can be exported with tctl auth sign or tsh login --out=<output-path>.

Note

Note that when a tctl command is run locally on an Auth server, the audit logs will show that it was performed by the Auth server itself. To properly audit admin actions at scale, it is important to limit direct ssh access to the Auth server with Access Controls and ensure that admins use tctl remotely with the --identity flag instead.

The TELEPORT_CONFIG_FILE environment variable indicates where the Teleport configuration file is. If you're connecting to a remote Teleport cluster (Teleport Cloud) through a tsh session and have a file /etc/teleport.yaml on your machine set the TELEPORT_CONFIG_FILE to "". 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

Name	Default Value(s)	Allowed Value(s)	Description
`-d, --debug`	none	none	Enable verbose logging to stderr
`-c, --config`	`/etc/teleport.yaml`	string filepath	Path to a configuration file
`--auth-server`	none	`host:port`	Attempts to connect to specific auth/proxy address(es) instead of local auth [127.0.0.1:3025]
`-i, --identity`	none	string filepath	Path to an identity file. Must be provided to make remote connections to auth. An identity file can be exported with 'tctl auth sign'
`--insecure`	none	none	When specifying a proxy 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> [<local-logins>]

Arguments

<account> - The Teleport user account name.
<local-logins> - A comma-separated list of local UNIX users this account can log in as. If unspecified the account will be mapped to an OS user of the same name. See examples below.

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--k8s-groups`	none	a kubernetes group	Kubernetes groups to assign to a user, e.g. `system:masters`
`--k8s-users`	none	a kubernetes user	Kubernetes user to assign to a user, e.g. `jenkins`
`--ttl`	1h	relative duration like 5s, 2m, or 3h, maximum 48h	Set 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 "joe" and "root"
tctl users add joe joe,root
Adds teleport user "joe" with mappings to
OS users "joe" only
tctl users add 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

Name	Default Value(s)	Allowed Value(s)	Description
`--ttl`	`8h`	relative duration like `5s`, `2m`, or `3h`	Set 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

Name	Default Value(s)	Allowed Value(s)	Description
`--roles`	`node`	`node,auth` or `proxy`	Comma-separated list of roles for the new node to assume
`--ttl`	30m	relative duration like 5s, 2m, or 3h	Time to live for a generated token
`--token`	none	string token value	A 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

Name	Default Value(s)	Allowed Value(s)	Description
`--namespace`	none	string namespace	Namespace 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

Name	Default Value(s)	Allowed Value(s)	Description
`--type`	none	`trusted_cluster`, `node`, `proxy`	Type of token to add
`--value`	none	string token value	Value of token to add
`--ttl`	1h	relative duration like 5s, 2m, or 3h, maximum 48h	Set 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

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

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

Name	Default Value(s)	Allowed Value(s)	Description
`--keys`	none	none	if set, will print private keys
`--fingerprint`	none	string e.g. `SHA265:<fingerprint>`	filter authority by fingerprint
`--compat`	none	version number	export certificates compatible with specific version of Teleport
`--type`	none	`user, host` or `tls`	certificate 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

Name	Default Value(s)	Allowed Value(s)	Description
`--user`	none	existing user	Teleport user name
`--host`	none	auth host	Teleport host name
`-o, --out`	none	filepath	identity output
`--format`	`file`	`file`, `openssh`, `tls` or `kubernetes`	identity format
`--identity`	`file`	`file`	identity format
`--auth-server`	none	auth host & port	Remote Teleport host name
`--ttl`	none	relative duration like 5s, 2m, or 3h	TTL (time to live) for the generated certificate
`--compat`	`""`	`standard` or `oldssh`	OpenSSH compatibility flag
`--proxy`	`""`	Address of the teleport proxy.	When --format is set to "kubernetes", this address will be set as cluster address in the generated kubeconfig file
`--leaf-cluster`	`""`	The name of a leaf cluster.
`--kube-cluster-name`	`""`	Kubernetes Cluster Name

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

Name	Default Value(s)	Allowed Value(s)	Description
`--grace-period`	none	relative duration like 5s, 2m, or 3h	Grace period keeps previous certificate authorities signatures valid, if set to 0 will force users to log in again and nodes to re-register.
`--manual`	none	none	Activate manual rotation, set rotation phases manually
`--type`	`user,host`	`user` or `host`	Certificate authority to rotate
`--phase`		`init, standby, update_clients, update_servers, rollback`	Target 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 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

Name	Default Value(s)	Allowed Value(s)	Description
`-f, --force`	none	none	Overwrite 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,token]
- <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

Name	Default Value(s)	Allowed Value(s)	Description
`--format`		`yaml, json` or `text`	Output format
`--with-secrets`	none	none	Include 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 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 cluster version:

tctl version

Experimental features

tctl access ls

Displays user accesses to SSH nodes

tctl access ls [--user <user> | --login <login> | --node <hostname>][<flags>]

Flags

Name	Default Value(s)	Allowed Value(s)	Description
`--user`	none	existing user	Teleport user name
`--login`	none	user login	Teleport user login
`--node`	none	existing hostname	Teleport node hostname
`--namespace`	default	existing namespace	Teleport namespace

Examples

# Get all user accesses over all nodes
tctl access ls
# Get accesses for user 'joe'
tctl access ls --user joe
# Get accesses for node 'prod'
tctl access ls --node prod
# Get accesses for login 'root'
tctl access ls --login root
# Get accesses for user 'joe', node 'prod', and login 'root'
tctl access ls --user joe --login root --node prod

Have a suggestion or can’t find something?

IMPROVE THE DOCS