Fork me on GitHub
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.

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.

ServiceRole NameDescription
NodenodeRuns a daemon on a node which allows SSH connections from authenticated clients.
AuthauthAuthenticates nodes and users who want access to Teleport Nodes or information about the cluster
ProxyproxyThe gateway that clients use to connect to the Auth or Node Services
AppappRuns a daemon on a node which provides access to applications using an SSH reverse tunnel.

teleport start

Flags

NameDefault Value(s)Allowed Value(s)Description
-d, --debugnonenoneenable verbose logging to stderr
--insecure-no-tlsfalsenoneTells 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,authstring comma-separated list of proxy, node or authstart 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
--nodenamehostname command on the machinestringassigns 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.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.
--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

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

teleport status shows the status of a Teleport connection. This command is only available from inside of a recorded SSH session.

teleport configure

teleport configure dumps a sample configuration file in YAML format into standard output.

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

teleport version

teleport version shows the release version.

teleport help

teleport help shows help teleport and its subcommands like this 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

NameDefault Value(s)Allowed Value(s)Description
-l, --loginnonean identity namethe login identity that the Teleport User should use
--proxynonehost:https_port[,ssh_proxy_port]set SSH proxy address
--user$USERnonethe Teleport User name
--ttlnonerelative duration like 5s, 2m, or 3hset time to live for a SSH session, session ttl unrestricted if unset
-i, --identitynonestring filepathIdentity file
--cert-formatfilefile or opensshSSH certificate format
--insecurenonenoneDo not verify server's certificate and host name. Use only in test environments
--authlocalany defined authentication connectorSpecify the type of authentication connector to use.
--skip-version-checknonenoneSkip version checking between server and client.
-d, --debugnonenoneVerbose logging to stdout
-J, --jumphostnoneA jump hostSSH jumphost

tsh help

Prints help.

Usage: tsh help

tsh version

Prints client version.

Usage: tsh version

tsh ssh

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

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

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)

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 root@grav-00
# `tsh ssh` takes the same arguments as OpenSSH client:
$ tsh ssh -o ForwardAgent=yes root@grav-00
$ tsh ssh -o AddKeysToAgent=yes root@grav-00

tsh apps ls

List all available applications.

Usage: tsh apps ls

tsh join

Joins an active session.

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

tsh --proxy proxy.example.com join <session-id>

tsh play

Plays back a prior session.

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

Global Flags

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

Examples

tsh --proxy proxy.example.com play <session-id>

tsh scp

Copies files from source to dest.

Usage: usage: 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.

Usage: usage: tsh ls [<flags>] [<label>]

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.

Usage: usage: tsh kube ls

Examples

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

tsh clusters

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

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

# 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

# log in 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

# Enterprise only: 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.

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

Usage: tsh logout

tsh status

Display the list of proxy servers and retrieved certificates.

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

Usage: tsh mfa ls

tsh mfa add

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

Usage: tsh mfa add

Examples

$ tsh mfa add
Choose device type [TOTP, U2F]: u2f
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, U2F]: 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.

Usage: tsh mfa rm <device-name>

tctl

tctl is an admin CLI tool used to administer a Teleport cluster. It connects to an Auth Server, meaning that it must be run on the same host with the role auth. If you run tctl on a non- auth node it will show an error.

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.

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

tctl help

Shows help.

Usage: tctl help

tctl users add

Generates a user invitation token.

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

NameDefault Value(s)Allowed Value(s)Description
--k8s-groupsnonea kubernetes groupKubernetes groups to assign to a user, e.g. system:masters
--k8s-usersnonea kubernetes userKubernetes user to assign to a user, e.g. jenkins
--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 "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.

Usage: tctl users ls [<flags>]

tctl users rm

Deletes user accounts.

Usage: 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 a 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 token with link.

tctl request ls

List of open requests.

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

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

Usage: 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 user's role request.

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

Usage: tctl nodes add [<flags>]

Flags

NameDefault Value(s)Allowed Value(s)Description
--rolesnodenode,auth or proxyComma-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 that will run the proxy service is 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.

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

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

Flags

NameDefault Value(s)Allowed Value(s)Description
--typenonetrusted_cluster, node, proxyType of token to add
--valuenonestring token valueValue of token to add
--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

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

Usage: tctl tokens rm [<token>]

Arguments

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

tctl tokens ls

List node and user invitation tokens.

Usage: tctl tokens ls [<flags>]

Example

$ tctl tokens ls
Token                            Type            Expiry Time (UTC)
-------------------------------- --------------- -------------------
ecce46d19bb4144716e5984269db1ac0 Node            11 Oct 19 22:17 UTC
fcbf269ca26440f35865ec29994f0fb4 trusted_cluster 11 Oct 19 22:19 UTC
6fd001d4200348deec9b50c4479ba07d User signup     11 Oct 19 22:20 UTC

tctl auth export

Export public cluster (CA) keys to stdout.

Usage: tctl auth export [<flags>]

Flags

NameDefault Value(s)Allowed Value(s)Description
--keysnonenoneif set, will print private keys
--fingerprintnonestring e.g. SHA265:<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.

Usage: 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
--formatfilefile, openssh, tls or kubernetesidentity format
--identityfilefileidentity format
--auth-servernoneauth host & portRemote Teleport host name
--ttlnonerelative 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.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 10 years for the jenkins user
# the jenkins.pem file can later be used with `tsh`
$ tctl auth sign --ttl=87600h --user=jenkins --out=jenkins.pem
# create a certificate with a TTL of 1 day 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 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.

Usage: 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 create

Create or update a Teleport resource from a YAML file.

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

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

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

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

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

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

Argument

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

Example

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

tctl version

Print cluster version.

Usage: tctl version

Have a suggestion or can’t find something?
IMPROVE THE DOCS