Teleport is made up of three CLI tools.
- teleport: The daemon that runs the Auth Service, Proxy Service, and other Teleport services.
- tsh: A tool that lets end users interact with Teleport.
- tctl: An administrative tool that can configure the Teleport Auth Service.
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 thehistory
command on a compromised system.
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.
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.
Service | Role Name | Description |
---|---|---|
Node | node | Runs a daemon on a host that allows SSH connections from authenticated clients. |
Auth | auth | Authenticates hosts and users who want access to Teleport-managed resources or information about a cluster. |
Proxy | proxy | The gateway that clients use to connect to the Auth Service or resources managed by Teleport. |
App | app | Runs a daemon on a host that provides access to applications using an SSH reverse tunnel. |
Kube | kube | The Teleport daemon will run the Kubernetes Service. |
DB | db | The Teleport daemon will run the Database Service. |
Trusted Cluster | trusted_cluster | The Teleport daemon will support a leaf cluster used to connect to another Teleport cluster. |
Windows Desktop | windowsdesktop | The Teleport daemon will run the Windows Desktop Service. |
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, auth, node, db, app or windowsdesktop | 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 | value returned by the hostname command on the machine | string | assigns an alternative name for the node which can be used by clients to log in. |
-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. |
--skip-version-check | false | true or false | Skips version checks between the Auth Server this Teleport instance |
--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
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 will use |
--proxy | none | host:https_port[,ssh_proxy_port] | Teleport Proxy Service address |
--user | $USER | none | The Teleport username |
--ttl | 720 (12 hours) | integer | Number of minutes a certificate issued for the tsh user will be valid for |
-i, --identity | none | string filepath | Identity file |
--cert-format | file | file or openssh | SSH certificate format |
--insecure | none | none | Do not verify the server's certificate and host name. Use only in test environments. |
--auth | local | any defined authentication connector, including local and passwordless | Specify the type of authentication connector to use. |
--mfa-mode | auto | auto , cross-platform , platform or otp | Preferred mode for MFA and Passwordless assertions. |
--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
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
Thenodename
of a cluster Node or a label specification likeenv=aws
to run on all matching hosts.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]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 configAppend 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 byteleport 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
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 byteleport 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.tarPlaying 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, runtsh apps ls
.
Flags
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--port | none | port number | Specify 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
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>]
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
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
-v, --verbose | none | none | also 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 lsNode 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 -vNode 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=osxNode Name Address Labels
--------- ------------------ ------
grav-02 10.156.0.7:3022 os:osx
tsh kube ls
List Kubernetes clusters:
tsh kube ls
Examples
tsh kube lsKube 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
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 clustersCluster Name Status
------------ ------
staging online
production offline
tsh clusters --quietstaging 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
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
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 loginUse ports 8080 and 8023 for https and SSH proxy:
tsh --proxy=proxy.example.com:8080,8023 loginUse port 8080 and 3023 (default) for SSH proxy:
tsh --proxy=proxy.example.com:8080 loginUse port 23 as custom SSH port, keep HTTPS proxy port as default
tsh --proxy=work.example.com:,23 loginLogin and select cluster "two":
tsh --proxy=proxy.example.com login twoSelect cluster "two" using existing credentials and proxy:
tsh login twoLogin to the cluster with a very short-lived certificate
tsh --ttl=1 loginLogin using the local Teleport 'admin' user:
tsh --proxy=proxy.example.com --auth=local --user=admin loginLogin using GitHub as an SSO provider, assuming the GitHub connector is called "github"
tsh --proxy=proxy.example.com --auth=github --user=admin loginSuppress the opening of the system default browser for external provider logins
tsh --proxy=proxy.example.com --browser=noneLogin to cluster and output a local kubeconfig
tsh login --proxy=proxy.example.com --format=kubernetes -o kubeconfigRequest 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-demoLogged into kubernetes cluster "gke_bens-demos_us-central1-c_gks-demo"
On login, kubeconfig is pointed at the first cluster (alphabetically)
kubectl config current-contextaws-gke_bens-demos_us-central1-c_gks-demo
But all clusters are populated as contexts
kubectl config get-contextsCURRENT 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
Register a new Multi-Factor Authentication (MFA) device:
tsh mfa add
Examples
tsh mfa addChoose 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 addChoose 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: aw[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
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--roles | none | Comma-separated strings | List of Teleport roles to request |
--resource | none | String (flag can be repeated to request multiple resources) | Resource ID to be requested |
--reason | none | String | Reason for making the request (optional) |
--reviewers | none | Comma-separated strings | Suggested reviewers for the request (optional) |
--nowait | false | true or false | Finish without waiting for request resolution |
tsh request ls
List Access Requests
tsh request ls
Flags
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--format | text | text , json , or yaml | Format output |
--reviewable | false | true or false | Only show requests reviewable by current user |
--suggested | false | true or false | Only show requests that suggest current user as reviewer |
--my-requests | false | true or false | Only show requests created by current user |
tsh request show
Show Access Request details
tsh request show <request-id>
Flags
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--format | text | text , json , or yaml | Format output |
Arguments
<request-id>
- ID of the target request
tsh request review
Review an Access Request
tsh request review [<flags>] <request-id>
Flags
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--approve | false | true or false | Review proposes approval |
--deny | false | true or false | Review proposes denial |
--reason | none | String | Review reason message |
Arguments
<request-id>
- ID of the target request
tsh request search
Search for resources to request access to
tsh request search [<flags>]
Flags
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--kind | none | node , kubernetes_cluster , db , app , windows_desktop | Resource kind to search for (required) |
--search | none | Comma-separated strings | List of comma-separated search keywords or phrases enclosed in single quotes |
--query | none | String | Query by predicate language enclosed in single quotes |
--labels | none | Comma-separated strings | List 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 Variable | Description | Example Value |
---|---|---|
TELEPORT_AUTH | Name of a defined local, SAML, OIDC, or Github auth connector | okta |
TELEPORT_MFA_MODE | Preferred mode for MFA and Passwordless assertions | otp |
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 |
TELEPORT_GLOBAL_TSH_CONFIG | Override 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 withTELEPORT_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.
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"
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 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
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 Service address(es) instead of a local Auth Service (127.0.0.1:3025 ) |
-i, --identity | none | string filepath | Path to an identity file |
--insecure | none | none | When 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
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--roles | none | Comma-separated strings | List of Teleport roles to assign to the new user |
--logins | none | Comma-separated strings | List of allowed SSH logins for the new user |
--kubernetes-groups | none | Comma-separated strings | Kubernetes groups to assign to a user, e.g. system:masters |
--kubernetes-users | none | Comma-separated strings | Kubernetes user to assign to a user, e.g. jenkins |
--db-users | none | Comma-separated strings | List of allowed database users for the new user |
--db-names | none | Comma-separated strings | List of allowed database names for the new user |
--windows-logins | none | Comma-separated strings | List of allowed Windows logins for the new user |
--aws-role-arns | none | Comma-separated strings | List of allowed AWS role ARNs for the new user |
--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 and {{ internal.logins }} to "joe" and "ubuntu"
tctl users add joe --roles=access joe,ubuntuAdds 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
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--set-roles | none | a role name | Comma-separated list of roles for the user to assume, replaces current roles |
Examples
tctl users update joe --set-roles=access,editorAssigns 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,timRemoves 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 jeffUser 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 lsToken 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 | proxy, auth, node, db, app or windowsdesktop | 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 addGenerates 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 | proxy , auth , trusted_cluster , node , db , kube , app , windowsdesktop | Type of token to add |
--value | none | string token value | Value of token to add |
--ttl | 1h | relative duration like 5s, 2m, or 3h | Set expiration time for token |
--format | none | text , json , yaml | Output 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=5mGenerate an invite token for a trusted_cluster with labels
tctl tokens add --type=trusted_cluster --labels=env=prodGenerate an invite token for a node
This is equivalent to `tctl nodes add`
tctl tokens add --type=nodeGenerate a join token for both a Node and the Database Service
tctl tokens add --type=node,dbGenerate an invite token for a kubernetes_service
tctl tokens add --type=kubeGenerate 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
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
--format | none | text , json , yaml | Output 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 lsToken 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. SHA256:<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 exportFilter by fingerprint
tctl auth export --fingerprint=SHA256:8xu5kh1CbHCZRrGuitbQd4hM+d9V+I7YA1mUwA/2tAoExport 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 |
--overwrite | none | none | When specified, write new identity files, even if they already exist |
--format | file | file , openssh , tls or kubernetes | identity format |
--identity | none | file | Identity file to use for logging in to the Auth Service |
--auth-server | none | auth host & port | Remote Teleport host name |
--ttl | 12h | 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 Service | When --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 name | Generate a certificate for accessing the specified web application |
--db-service | "" | database service name | Generate a certificate for accessing the specified database service |
--db-user | "" | database user | When --db-service is specified, encode this database user in the certificate |
--db-name | "" | database name | When --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.pemExport identity formatted for openssh to teleport_id.pem
tctl auth sign --format openssh --user teleport -o teleport_id.pemExport 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-00Invalid command, only one of --user or --host should be set
tctl auth sign --format openssh --host grav-00 --user teleport -o grav_hosterror: --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.pemcreate 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.pemcreate 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=kubernetesExports 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=200hRotate 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
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
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
.
Name | Default Value(s) | Allowed Value(s) | Description |
---|---|---|---|
-n , --name | github | resource name | Connector name. |
-r , --teams-to-roles | none | org,team,role1,role2,... | Sets teams-to-roles mapping. Repeatable. |
--display | none | display name | Controls how this connector is displayed. |
--id | none | GitHub OAuth2 client id | GitHub app client ID. |
--secret | none | GitHub OAuth2 secret | GitHub app client secret. |
--redirect-url | none | Valid callback URL. | Authorization callback URL. |
--ignore-missing-roles | Ignore 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 theoctocats
org will receiveaccess
,editor
andauditor
roles. - members of the
dev
team inoctocats
org will receive theaccess
role.
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_IDINFO [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:
Name | Description |
---|---|
-p , --preset | Preset. One of: google , gitlab , okta . |
-n , --name | Connector name. Required, unless implied from preset. |
-r , --claims-to-roles | Sets claim-to-roles mapping using format claim_name,claim_value,role1,role2,... . Repeatable. |
--display | Display controls how this connector is displayed. |
--id | OIDC app client ID. |
--secret | OIDC app client secret. |
--issuer-url | Issuer URL. |
--redirect-url | Authorization callback URL. |
--prompt | Optional OIDC prompt. Example values: none , select_account , login , consent . |
--scope | Scope specifies additional scopes set by provider. Each repetition of the flag declares one scope. Examples: email , groups , openid . |
--acr | Authentication Context Class Reference values. |
--provider | Sets the external identity provider type to enable IdP specific workarounds. Examples: ping , adfs , netiq , `okta``. |
--ignore-missing-roles | Ignore missing roles referenced in --claims-to-roles . |
Supported presets:
Name | Description | Display | Issuer URL |
---|---|---|---|
google | Google Workspace | https://accounts.google.com | |
gitlab | GitLab | GitLab | https://gitlab.com |
okta | Okta | Okta | https://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:
Name | Description |
---|---|
--google-acc-uri | URI of your service account credentials file. Example: file:///var/lib/teleport/gworkspace-creds.json . |
--google-acc | String containing Google service account credentials. |
--google-admin | Email of a Google admin to impersonate. |
--google-legacy | Flag to select groups with direct membership filtered by domain (legacy behavior). Disabled by default. More info |
--google-id | Shorthand 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
- Generate an OIDC auth connector configuration called
myauth
. Two mappings from OIDC claims to roles are defined:- members of
admin
group will receiveaccess
,editor
andauditor
roles. - members of
developer
group will receiveaccess
role.
- members of
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
- Generate an OIDC auth connector with the Okta preset, enabling the
groups
scope and mapping theokta-admin
group to rolesaccess
,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
- 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]
- 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.
Name | Required? | Description |
---|---|---|
-p/--preset | Preset. One of: okta , onelogin , ad , adfs . | |
-n/--name | Yes, unless --preset is given. | Connector name. |
-e/--entity-descriptor | Yes, 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-roles | Yes, at least one occurrence must be present. | Sets attribute-to-role mapping using format attr_name,attr_value,role1,role2,... . Repeatable. |
--display | Sets the connector display name. | |
--issuer | Sets identity provider issuer. | |
--sso | URL of the identity provider's SSO service. | |
--cert | Path to your IdP's certificate PEM file. Your IdP signs responses using this certificate. | |
--acs | URL for the assertion consumer service on the service provider (Teleport's side). | |
--audience | Uniquely identifies our service provider. | |
--service-provider-issuer | Issuer of the service provider (Teleport). | |
--signing-key-file | A file with request signing key. Must be used together with --signing-cert-file . | |
--signing-cert-file | A file with request certificate. Must be used together with --signing-key-file . | |
--assertion-key-file | A file with key used for securing SAML assertions. Must be used together with --assertion-cert-file . | |
--assertion-cert-file | A file with cert used for securing SAML assertions. Must be used together with --assertion-key-file . | |
--provider | Sets the external identity provider type, enabling workarounds. Examples: ping, adfs. | |
--ignore-missing-roles | Ignore missing roles referenced in --attributes-to-roles . |
Supported presets:
Name | Description | Display |
---|---|---|
okta | Okta | Okta |
onelogin | OneLogin | OneLogin |
ad | Azure Active Directory | Microsoft |
adfs | Active Directory Federation Services | ADFS |
Global flags
These flags are available for all commands: --debug, --config
. Run
tctl help <subcommand>
or see the Global Flags section.
Examples
- Generate a SAML auth connector configuration called
myauth
. Two mappings from SAML attributes to roles are defined:- members of
admin
group will receiveaccess
,editor
andauditor
roles. - members of
developer
group will receiveaccess
role. The IdP metadata will be read fromentity-desc.xml
file.
- members of
tctl sso configure saml -n myauth -r group,admin,access,editor,auditor -r group,developer,access -e entity-desc.xml
- 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
- 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
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.yamlAdd a trusted cluster
tctl create cluster.yamlUpdate 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/oktaDelete 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 usersDump the user definition into a file:
tctl get user/joe > joe.yamlPrints the trusted cluster 'east'
tctl get cluster/eastPrints all trusted clusters and all users
tctl get clusters,usersDump 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 CApin 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
, or3h
Example
sudo teleport start --diag-addr=127.0.0.1:3000View 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 lsList nodes using label argument
tsh ls env=staging,os=macList nodes using search keywords
tsh ls --search=staging,macList 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")'