# tctl CLI reference `tctl` is a CLI tool that allows a cluster administrator to manage all resources in a cluster, including nodes, users, tokens, certificates, and devices. `tctl` can also be used to modify the dynamic configuration of the cluster, such as creating new user roles or connecting to trusted clusters. ## Authentication Before running `tctl` commands, administrators must authenticate to a Teleport cluster. This section explains how `tctl` authenticates to the cluster. **Self-Hosted** ### 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=`, 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` authenticates using this method if a configuration file exists at `/etc/teleport.yaml` or `TELEPORT_CONFIG_FILE` points to a configuration file in another location. If the `auth_service` is disabled in the configuration file, then the configuration file is ignored. --- NOTE Note that when a `tctl` command is run locally on the Auth Service, the audit logs will show that it was performed by the Auth Service itself. To provide an accurate audit trail, it is important to limit direct SSH access to the Auth Service with [Access Controls](https://goteleport.com/docs/ver/17.x/zero-trust-access/access-controls.md) 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`. **Cloud-Hosted** ### 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=`, 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`. ## 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 acl get Gets and displays information about a particular Access List. ``` $ tctl acl get ``` ## tctl acl ls Lists Access Lists on the cluster. ``` $ tctl acl ls ``` ## tctl acl users add Adds a user to an Access List. ``` $ tctl acl users add [] [] ``` ## tctl acl users ls Lists the users in an Access List. ``` $ tctl acl users ls ``` ## tctl acl users rm Removes a user from an Access List. ``` $ tctl acl users rm ``` ## tctl notifications create Create a new notification for users in the cluster: ``` $ tctl notifications create [] ``` There are several ways to specify which users see the notification. To target a specific user, use the `--user` flag. To target all users with a particular role (or set of roles), use the `--roles` flag. If you specify multiple roles, all users with at least one of the roles will see the notification, in order to require users to have all of the roles specified, add the `--require-all-roles` flag. If neither `--user` nor `--roles` are provided, the notification will default to targeting all users in the cluster, regardless of their roles. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | --------------------- | ---------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-t, --title` | none | **string** | Required. Sets the notification's title | | `--content` | none | **string** | Required. Sets the notification's text content, this is the text that will be displayed when a user clicks on the notification. | | `--user` | none | **string** | If user-specific, the username of the specific user this notification will target. | | `--roles` | none | Comma-separated strings | If role-specific, the set of roles users must have to receive this notification. | | `--require-all-roles` | `false` | `true`,`false` | If role-specific, setting this to `true` will only targets users who have *all* of the roles specified in `--roles`. If `false`, users only need to have one or more of the roles. | | `--ttl` | `30d` | Any duration | Time duration after which the notification will expire and be deleted. | | `--warning` | `false` | `true`,`false` | Whether this notification should be displayed as a warning. | | `--labels` | none | Comma-separated strings | Custom labels to attach to the notification's metadata. Note that these will have no effect on the native behavior of the notification. | ### Examples ``` Create a notification for a specific user $ tctl notifications create --user=alice --title="Upcoming Database Maintenance" --content="We will be conducting a database upgrade tomorrow at 2AM UTC" Create a warning notification for all users $ tctl notifications create --warning --title="Enroll an MFA device" --content="We will soon be enforcing MFA in this cluster, please enroll a device to avoid being locked out of your account." Create a notification for users with the `engineer` role that expires in 2 days $ tctl notifications create --roles=engineer --title="Reminder" --content="Please use access requests to request access to production servers" --ttl=2d ``` ## tctl notifications ls List notifications: ``` $ tctl notifications ls [] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `--user` | none | **string** | List only a specific user's notifications. | | `--format` | `text` | `text`,`yaml`,`json` | The format of the output. | | `--all` | `false` | `true`,`false` | If `true`, notifications generated by Teleport will also be returned, as opposed to only notifications created by admins via the `tctl` interface. | | `--labels` | none | Comma-separated strings | Filter notifications by labels. | ### Examples ``` $ tctl notifications ls ID Created Expires Title Labels ------------------------------------ ------------------- ------------------- -------------------- ------ 0194d8b2-5a38-7858-88fe-5fcee3ff1ceb 06 Feb 25 00:39 UTC 08 Mar 25 00:39 UTC Example notification ``` ## tctl notifications rm Delete a notification: ``` $ tctl notifications rm [] ``` ### Arguments - ``: the ID of the notification to delete. This can be retrieved from the output of `tctl notifications ls`. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | -------- | ---------------- | ---------------- | -------------------------------------------------------------------------------------------- | | `--user` | none | string | The username of the user this notification belongs to, if the notification is user-specific. | ### Examples ``` Delete a notification which was either for all users, or role-based. $ tctl notifications rm 3b8eb3d6-da9a-5353-aece-cbc885ecbf73 Delete a notification which was specific to a user. $ tctl notifications rm --user=alice 4f548918-c853-52a6-b98b-5718b79d0e96 ``` ## tctl alerts ack Temporarily acknowledges a cluster alert, preventing the alert from being displayed to users. Acknowledgements last for 24 hours by default. Users will begin seeing the alert again when the acknowledgement expires. ``` $ tctl alerts ack [] ``` ### Arguments - ``: the ID of the cluster alert to acknowledge ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | ---------------- | ------------------------------------------ | | `--ttl` | 24h | Any duration | Time duration to acknowledge the alert for | | `--clear` | none | | Clear an existing alert acknowledgement | | `--reason` | none | | The reason for suppressing this alert | ### Examples Suppress the cluster alert notifying users that an upgrade is available: ``` $ tctl alerts ack --reason="upgrade scheduled" upgrade-suggestion Successfully acknowledged alert 'upgrade-suggestion'. Alerts with this ID won't be pushed for 24h0m0s. ``` Clear an existing alert acknowledgement: ``` $ tctl alerts ack --clear upgrade-suggestion ``` ## tctl alerts ack ls Lists alert acknowledgements. ``` $ tctl alerts ack ls ID Reason Expires ------------------ ---------------------- -------------------- upgrade-suggestion "upgrade is scheduled" Wed Apr 12 16:52 UTC ``` ## tctl alerts create Creates cluster alerts. Cluster alerts can be displayed to Teleport users in the web UI or upon logging via `tsh`. ``` $ tctl alerts create [] ``` ### Arguments - ``: The message for the alert to display ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------ | ---------------- | ----------------------- | ------------------------------------------------------------------------ | | `--severity` | `low` | `low`, `medium`, `high` | Alert severity | | `--ttl` | none | Any duration | Optional expiry for alert (alert does not expire if no TTL is specified) | | `--labels` | none | any | A list of labels to attach to the alert. | While any labels can be applied to an alert, there are several internal labels that can be used to configure the behavior of alerts: - `teleport.internal/alert-on-login: yes`: ensures that the alert is displayed to users upon login - `teleport.internal/alert-permit-all: yes`: ensures that the alert is displayed to all users If no labels are specified, `tctl` will automatically add both of these labels. ### Examples ``` $ tctl alerts create \ --severity=low \ --ttl=4h \ "The system is under maintenance, functionality may be limited." ``` ## tctl alerts list Lists cluster alerts. This command can also be invoked as `tctl alerts ls`. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------------ | ---------------- | ----------------------- | ------------------------------------------------------------------- | | `--verbose` (`-v`) | false | boolean | If set, display detailed alert info (including acknowledged alerts) | | `--labels` | none | Comma-separated strings | A list of labels to filter by | ### Examples ``` $ tctl alerts list ID Severity Expires In Message ------------------------------------ -------- ---------- ---------------------------------------------------------------- da36b401-5688-426f-95b8-d0dd1ef27785 LOW 57m0s "The system is under maintenance, functionality may be limited." ``` ## tctl auth export Exports public cluster CA certificates. This is useful for configuring external systems to trust certificates issued by Teleport. ``` $ tctl auth export [] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | --------------- | ---------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `--keys` | none | none | if set, only exports private keys | | `--fingerprint` | none | **string** e.g. `SHA256:` | filter authority by fingerprint | | `--compat` | none | version number | export certificates compatible with specific version of Teleport | | `--type` | none | `user`, `host`, `tls-host`, `tls-user`, `tls-user-der`, `windows`, `db`, `openssh`, `saml-idp` | certificate type | | `--out` | none | filepath | if set writes exported authorities to files with the given path prefix | ### Global flags These flags are available for all commands `--debug, --config`. Run: ``` $ tctl help ``` or see the [Global Flags section](#tctl-global-flags). ### 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-host ``` ## tctl recordings download Download session recordings from the cluster's recording storage to a local file. If you omit an output directory, recordings are saved to the current working directory. If session recording encryption is enabled in the cluster, recordings are decrypted during download. ### Example ``` $ tctl recordings download [--output-dir ] ``` ## tctl auth rotate Rotate certificate authorities in the cluster: ``` $ tctl auth rotate [] ``` ### 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 ` or see the [Global Flags section](#tctl-global-flags). ### 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 auth sign --- AUTOMATION `tctl auth sign` is commonly used to generate long-lived certificates for automation purposes. On supported platforms, [Machine & Workload Identity](https://goteleport.com/docs/ver/17.x/machine-workload-identity/introduction.md) is a more secure alternative that generates short-lived certificates for automation workflows. --- Create an identity file(s) for a given user: ``` $ tctl auth sign -o [--user | --host ][--format] [] ``` ### 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 instance | | `--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 ` or see the [Global Flags section](#tctl-global-flags). ### 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 Service in preparation for remote tctl execution. $ tctl auth sign --user=admin --out=identity.pem ``` ## tctl bots add Create a new Machine & Workload Identity Bot: ``` $ tctl bots add [] ``` ### Arguments - `` - name of Machine & Workload Identity Bot to create. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `--roles` | none | Comma-separated list of roles to assign to the Bot. | Required. Specifies the roles that the Bot should be able to impersonate and include in generated credentials. | | `--logins` | none | Comma-separated list of allowed SSH logins to set Bot's login trait to. | Optional. Specifies the values that should be configured as the Bot's logins trait for the purpose of role templating. | | `--token` | none | String name of an existing join token. | Optional. Specifies an existing join token to be used rather than creating one as part of the Bot creation. | | `--ttl` | 15m | Duration. | Optional. Overrides the TTL of the token that will be created if `--token` is not specified. | | `--format` | `text` | `text`, `json` | If set to `json`, return new bot information as a machine-readable JSON string. | ### Examples Create a new bot named `example` that may assume the `access` role and log in as `root`: ``` $ tctl bots add example --roles=access --logins=root ``` ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ## tctl bots instances add Onboard a new instance of an existing bot with a one-time use join token: ``` $ tctl bots instances add [flags] ``` Note that a new instance will not be generated immediately; the bot will appear in `tctl bots instances list` as soon as it joins the cluster and is allocated a UUID. ### Arguments - `` - the name of the existing bot for which a new join token should be generated ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `--token` | none | String name of an existing join token. | Optional. Specifies an existing join token to be used rather than creating one as part of the Bot creation. | | `--format` | `text` | `text`, `json` | If set to `json`, return new bot information as a machine-readable JSON string. | ### Examples This generates a new one-time use join token for the bot named "example", without modifying roles or other configuration: ``` $ tctl bots instances add example ``` ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ## tctl bots instances list List all current instances of a Machine & Workload Identity bot: ``` $ tctl bots instances list [] ``` ### Arguments - `[]` - an optional bot name. If provided, filters the result to show only instances for the named bot. Otherwise, shows all instances for all bots. ### Examples This shows all known instances for the bot named "example": ``` $ tctl bots instance list example ``` ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ## tctl bots instances show Shows details about a particular instance of a bot, including join metadata and current status: ``` $ tctl bots instances show / ``` ### Arguments - `` - the name of the existing bot - `` - the UUID of the existing bot instance, as shown in `tctl bots instance list` ### Examples ``` $ tctl bots instances show example/28e605c9-2fe1-423f-afe1-5122335e1c75 ``` ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ## tctl bots ls Lists all Machine & Workload Identity Bots: ``` $ tctl bots ls [] ``` ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ## tctl bots rm Delete a Machine & Workload Identity Bot: ``` $ tctl bots rm [] ``` ### Arguments - `` - name of Machine & Workload Identity Bot to delete. ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ## tctl bots update Update a Machine & Workload Identity Bot: ``` $ tctl bots update [] ``` ### Arguments - `` - The name of the bot to update ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | -------------- | ---------------- | ------------------------------------------------ | ----------------------------------------------------------------- | | `--add-roles` | none | Comma-separated list of roles the bot may assume | Appends the given roles to the existing roles the bot may assume. | | `--set-roles` | none | Comma-separated list of roles the bot may assume | Replaces the bots's current roles with the list provided. | | `--add-logins` | none | Comma-separated list of allowed Unix logins | Appends the given logins to the bot's current allowed logins. | | `--set-logins` | none | Comma-separated list of allowed Unix logins | Replaces the bot's current allowed logins with the given list. | ### Examples Replace the bot `example` roles and add a new allowed Unix login: ``` $ tctl bots update example --add-logins=root --set-roles=access ``` Remove all implicitly allowed Unix logins from a bot named `example` by passing an empty list: ``` $ tctl bots update example --set-logins=, ``` Note that the bot may still be granted additional logins via roles. ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ## tctl create Create or update a Teleport resource from a YAML file. The supported resource types are: user, node, cluster, role, connector, and device. See the [Resources Reference](https://goteleport.com/docs/ver/17.x/reference/resources.md) for complete docs on how to build these yaml files. ``` $ tctl create [] ``` ### Arguments - `` 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 ` or see the [Global Flags section](#tctl-global-flags). ### 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 devices add Register a device. ``` $ tctl devices add --os=OS --asset-tag=SERIAL_NUMBER ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------- | ---------------- | --------------------------- | ----------------------------------------------------- | | `--os` | none | `linux`, `macos`, `windows` | Device operating system | | `--asset-tag` | none | string | Device inventory identifier (e.g., Mac serial number) | | `--enroll` | false | boolean | If set, creates a device enrollment token | ### Examples ``` $ tctl devices add --os=macos --asset-tag=C00AA0AAAA0A Device C00AA0AAAA0A/macOS added to the inventory $ tctl devices add --os=macos --asset-tag=C00AA0AAAA0A --enroll Device C00AA0AAAA0A/macOS added to the inventory Run the command below on device "C00AA0AAAA0A" to enroll it: tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example ``` ## tctl devices enroll Create an enrollment token for a device. ``` $ tctl devices enroll [--device-id=ID] [--asset-tag=ASSET_TAG] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------- | ---------------- | ---------------- | ----------------------------------------------------- | | `--device-id` | none | string | Teleport device identifier | | `--asset-tag` | none | string | Device inventory identifier (e.g., Mac serial number) | One of `--device-id` or `--asset-tag` must be present. ### Examples ``` $ tctl devices enroll --device-id=d40f2ee4-856d-4aef-b784-c4371e39c036 Run the command below on device "d40f2ee4-856d-4aef-b784-c4371e39c036" to enroll it: tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example $ tctl devices enroll --asset-tag=C00AA0AAAA0A Run the command below on device "C00AA0AAAA0A" to enroll it: tsh device enroll --token=AAAAAAAAAAAAAAAAAAAAAAAA-this-is-an-example ``` ## tctl devices ls List registered devices. ``` $ tctl devices ls ``` ### Examples ``` $ tctl devices ls Asset Tag OS Enroll Status Device ID ------------ ----- ------------- ------------------------------------ C00AA0AAAA0A macOS enrolled d40f2ee4-856d-4aef-b784-c4371e39c036 ``` ## tctl devices rm Removes a registered device. A removed device is not considered a trusted device for future device authentication attempts. ``` $ tctl devices rm [--device-id=ID] [--asset-tag=ASSET_TAG] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------- | ---------------- | ---------------- | ----------------------------------------------------- | | `--device-id` | none | string | Teleport device identifier | | `--asset-tag` | none | string | Device inventory identifier (e.g., Mac serial number) | One of `--device-id` or `--asset-tag` must be present. ### Examples ``` $ tctl devices rm --device-id=d40f2ee4-856d-4aef-b784-c4371e39c036 Device "ac3590ec-87d4-4519-8e9e-2f35af0a9f85" removed $ tctl devices rm --asset-tag=C00AA0AAAA0A Device "C00AA0AAAA0A" removed ``` ## tctl edit Modify a Teleport resource using your preferred text editor. ``` $ tctl edit ``` The text editor is selected by checking the following, in order of precedence: - the `TELEPORT_EDITOR` environment variable - the `VISUAL` environment variable - the `EDITOR` environment variable - defaulting to `vi` `tctl` will fetch the resource from the backend and open it in the selected editor. When the editor process terminates, `tctl` will push the updates to the Teleport cluster. To abandon the edit, close the editor without saving the file. Some graphical editors like VS Code launch a background process rather than running in the foreground. This prevents `tctl` from properly detecting when the editor process terminates. To work around this, check whether your editor supports a "wait" option that waits for files to be closed before terminating. For example, to edit a Teleport resource with VS Code, you can set `TELEPORT_EDITOR="code --wait"`. **Note:** Renaming resources with `tctl edit` is not supported since Teleport resources often refer to other resources by name. To rename a resource, we recommend you: - fetch the resource with `tctl get` and redirect the output to a file - change the name of the resource in the file - save the new resource with `tctl create -f` - update any references to the old resource ### Arguments - `` The resource to edit - `` The type of the resource \[for example: `user,cluster,token`] - `` The name of the resource ### Global flags These flags are available for all commands `--debug, --config` . Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples ``` edit the sre role $ tctl edit role/sre edit the alice user with the nano editor $ TELEPORT_EDITOR=nano tctl edit user/alice ``` ## tctl get Print a YAML declaration of various Teleport resources: ``` $ tctl get [] ,... ``` ### Arguments - `` The resource to get - `` The type of the resource \[for example: `user,cluster,token,device`] - `` The name of the resource ### 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 ` or see the [Global Flags section](#tctl-global-flags). ### Examples **Self-Hosted** ``` $ 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 ``` **Teleport Enterprise Cloud** ``` $ 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 ``` ## tctl help Shows help: ``` $ tctl help ``` ## tctl inventory list List Teleport instance inventory: ``` $ tctl inventory list [] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ----------------- | ---------------- | ------------------------- | ---------------------------------------------- | | `--format` | `text` | `yaml, json` or `text` | Output format | | `--older-than` | none | string | Filter for older teleport versions | | `--exact-version` | none | string | Filter output by teleport version | | `--services` | none | string | Filter output by service (node,kube,proxy,etc) | | `--upgrader` | none | `none`, `kube`, or `unit` | Filter output by upgrader (kube,unit,none) | ### Global flags These flags are available for all commands `--debug, --config` . Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples List inventory ``` $ tctl inventory ls Server ID Hostname Services Agent Version Upgrader Upgrader Version ------------------------------------ ------------------------------- -------------------------- ------------- -------- ---------------- 00c3a1f7-5f24-47f9-b866-14401fbb5685 teleport-proxy-77df88c69 Proxy 17.7.20 none none 065ab336-1ac2-4314-8b16-32fc06a172a7 server1 Node 17.7.20 unit 17.7.20 a24d4ad4-ead8-4b15-9ea6-357a5350369e teleport-auth-fb68b5df7 Auth,Discovery 17.7.20 none none ``` List inventory for a specific service and version ``` $ tctl inventory ls --services=node --exact-version=17.7.20 Server ID Hostname Services Agent Version Upgrader Upgrader Version ------------------------------------ ------------------------------- -------------------------- ------------- -------- ---------------- 065ab336-1ac2-4314-8b16-32fc06a172a7 server1 Node 17.7.20 unit 17.7.20 a24d4ad4-ead8-4b15-9ea6-357a5350369e server2 Node,App 17.7.20 unit 17.7.20 ``` Note that newly added Teleport services do not show in the inventory right as the service joins. Those can take around 5 minutes under regular circumstances to show in inventory counts and up to 15 minutes for heavy load. ## tctl inventory status Show inventory status summary: ``` $ tctl inventory status [] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------------ | ---------------- | ---------------------- | ---------------------------------------- | | `--format` | `text` | `yaml, json` or `text` | Output format | | `--[no-]connected` | `--no-connected` | none | Show locally connected instances summary | ### Global flags These are available for all commands `--debug, --config` . Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples **Self-Hosted** List inventory status ``` $ tctl inventory status Versions: v17.7.20: 16 Upgraders: kube: 6 unit: 6 none: 4 Services: Discovery: 2 Auth: 2 Db: 2 Kube: 2 App: 2 Node: 2 Proxy: 2 WindowsDesktop: 2 Total Instances: 16 ``` List inventory status for locally connected instances summary. This allows seeing connected instances on a specific Auth service. ``` $ tctl inventory status --connected Server ID Services Version Upgrader ------------------------------------ ---------------------- ------- -------- b48e6e81-63e0-498f-834b-1a8adea09d95 Auth 17.7.20 none 178d9301-2873-4020-895a-014edf067204 Node 17.7.20 unit ``` **Cloud-Hosted** List inventory status ``` $ tctl inventory status Versions: v18.7.4: 19 Upgraders: kube: 1 unit: 1 none: 16 Services: App: 1 Node: 1 Proxy: 12 Discovery: 2 Auth: 2 Kube: 1 Total Instances: 19 ``` Note that newly added Teleport services do not show in the inventory right as the service joins. Those can take around 5 minutes under regular circumstances to show in inventory counts and up to 15 minutes for heavy load. ## tctl lock Create a new lock. ``` $ tctl lock [] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------------- | ---------------- | ---------------- | ----------------------------------------------------- | | `--user` | none | string | Target a specific user by username. | | `--role` | none | string | Target a specific role by name. | | `--login` | none | string | Target a specific server login. | | `--server-id` | none | string | Target a specific node by name or UUID. | | `--mfa-device` | none | string | Target a specific MFA device by UUID. | | `--windows-desktop` | none | string | Target a specific Windows desktop by name. | | `--access-request` | none | string | Target a specific Access Request by ID. | | `--device` | none | string | Target a specific trusted device by ID. | | `--message` | none | string | Optional message explaining the reason for the lock. | | `--expires` | never | timestamp | When the lock should automatically expire (RFC3339). | | `--ttl` | none | duration | Time-to-live for the lock (alternative to --expires). | ### Examples ``` Lock a specific user $ tctl lock --user alice --message "Security incident investigation" Lock a role with expiration $ tctl lock --role developers --expires "2025-06-26T00:20:47.16109Z" --message "Emergency maintenance" Lock a specific node $ tctl lock --server-id web-server-01 --message "Suspected compromise" Lock multiple targets (user and access-request combination) $ tctl lock --user=foo@example.com --message="Suspicious activity." --ttl=10h --access-request=1234 ``` ## tctl login\_rule test Test a Login Rule resource without installing it in the cluster. ### Arguments - `` input traits file in JSON or YAML format. Empty for stdin. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | --------------------- | ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--resource-file` | none | **string** filepath | Path to Login Rule resource path, can be repeated for multiple files | | `--load-from-cluster` | `false` | `true, false` | When true, all Login Rules currently installed in the cluster will be loaded for the test. Can be combined with `--resource-file` to test interactions. | | `--format` | `yaml` | `yaml, json` | Output format for traits | ### Global flags These flags are available for all commands `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples Test evaluation of the Login Rules from rule1.yaml and rule2.yaml with input traits from traits.json ``` $ tctl login_rule test --resource-file rule1.yaml --resource-file rule2.yaml traits.json ``` Test the Login Rule in rule.yaml along with all Login Rules already present in the cluster ``` $ tctl login_rule test --resource-file rule.yaml --load-from-cluster traits.json ``` Read the input traits from stdin ``` $ echo '{"groups": ["example"]}' | tctl login_rule test --resource-file rule.yaml ``` ## tctl nodes add Generate a node invitation token: ``` $ tctl nodes add [] ``` ### 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 ` or see the [Global Flags section](#tctl-global-flags). ### 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 | 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 ` or see the [Global Flags section](#tctl-global-flags). ## tctl request approve Approve a user's request: ``` $ tctl request approve [token] ``` ### Arguments - `` - comma-separated list of Teleport tokens. ### Examples ``` $ tctl request approve request-id-1, request-id-2 ``` ## tctl request create Create a pending Access Request. ``` $ tctl request create ``` ### Arguments - `` - Name of target user (required). ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | ------------------------------- | ------------------------------------------ | | `roles` | none | Comma-separated list of strings | Roles to be requested | | `resource` | none | Comma-separated list of strings | Resource IDs to be requested | | `reason` | none | String | Optional reason message | | `dry-run` | none | Boolean | Don't actually generate the Access Request | Use the `dry-run` flag if you want to validate whether Teleport can create an Access Request for the user in the `username` argument, given the user's static roles. ### Global flags These flags are available for all commands `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples Create an Access Request for user `myuser` for the `prod` role, providing a reason: ``` $ tctl request create myuser --roles=prod --reason="Fix an outage" ``` ## tctl request deny Denies a user's request: ``` $ tctl request deny [token] ``` ### Arguments - `` - comma-separated list of Teleport tokens. ### Examples ``` $ tctl request deny request-id-1, request-id-2 ``` ## 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 rm Delete a users role request: ``` $ tctl request rm [token] ``` ### Arguments - `` - comma-separated list of Teleport tokens. ### Examples ``` $ tctl request rm request-id-1 ``` ## tctl rm Delete a resource: ``` $ tctl rm ``` ### Arguments - `` Resource to delete - `` Type of a resource \[for example: `saml,oidc,github,user,cluster,tokens,device`] - `` 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 Delete a lock $ tctl rm lock/ed7038cb-a3cc-4f59-8063-09553665b773 ``` ## 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](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). 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 `devs` team in the GitHub org `octocats` will be assigned the `access`, and `editor` roles in Teleport. ``` $ tctl sso configure github --id=GITHUB_CLIENT_ID --secret=GITHUB_SECRET --teams-to-roles=octocats,devs,access,editor [] ``` ### 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 ` or see the [Global Flags section](#tctl-global-flags). ### Examples Generate a GitHub auth connector. Two role mappings are defined: - members of the `admin` team in the `octocats` org will receive `access`, `editor` and `auditor` roles. - members of the `dev` team in `octocats` org will receive the `access` role. --- NOTE `tctl sso configure gh` is an alias for `tctl sso configure github`. --- ``` $ tctl sso configure gh -r octocats,admin,access,editor,auditor -r octocats,dev,access --secret GH_SECRET --id CLIENT_ID INFO [CLIENT] RedirectURL empty, resolving automatically. INFO [CLIENT] RedirectURL set to "https://teleport.example.com:3080/v1/webapi/github/callback" kind: github metadata: name: github spec: client_id: CLIENT_ID client_secret: GH_SECRET display: "" redirect_url: https://teleport.example.com:3080/v1/webapi/github/callback teams_to_logins: - logins: - access - editor - auditor organization: octocats team: admin - logins: - access organization: octocats team: dev version: v3 ``` Generate the configuration and immediately test it using `tctl sso test` command. ``` $ tctl sso configure gh ... | tctl sso test ``` ## tctl sso configure oidc Configure an OIDC auth connector, optionally using a preset. The flag `--claims-to-roles` can be provided multiple times. ``` $ tctl sso configure oidc --id=CLIENT_ID --secret=SECRET --claims-to-roles=... [] ``` ### 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 | Google | `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](https://goteleport.com/docs/ver/17.x/zero-trust-access/sso/google-workspace.md) | | `--google-id` | Shorthand for setting the `--id` flag to `.apps.googleusercontent.com` | ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples 1. Generate an OIDC auth connector configuration called `myauth`. Two mappings from OIDC claims to roles are defined: - members of `admin` group will receive `access`, `editor` and `auditor` roles. - members of `developer` group will receive `access` role. The values for `--secret`, `--id` and `--issuer-url` are provided by the IdP. ``` $ tctl sso configure oidc -n myauth -r groups,admin,access,editor,auditor -r group,developer,access \ --secret IDP_SECRET --id CLIENT_ID \ --issuer-url https://idp.example.com ``` 2. Generate an OIDC auth connector with the Okta preset, enabling the `groups` scope and mapping the `okta-admin` group to roles `access`, `editor`, `auditor`. Issuer URL is set to match a custom Okta domain. ``` $ tctl sso configure oidc --preset okta --scope groups -r groups,okta-admin,access,editor,auditor \ --secret IDP_SECRET --id CLIENT_ID \ --issuer-url dev-123456.oktapreview.com ``` 3. Generate an OIDC auth connector with the Google preset. Service account credentials are set to be loaded from `/var/lib/teleport/gacc.json` with `--google-acc-uri`. ``` $ tctl sso configure oidc --preset google -r groups,mygroup@mydomain.example.com,access \ --secret SECRET --google-id GOOGLE_ID --google-acc-uri /var/lib/teleport/gacc.json \ --google-admin admin@mydomain.example.com ``` 4. Generate the configuration and immediately test it using the `tctl sso test` command. ``` $ tctl sso configure oidc ... | tctl sso test ``` ## tctl sso configure saml Configure the SAML auth connector, optionally using a preset. The flag `--attributes-to-roles/-r` can be provided multiple times. To avoid errors when pasting XML to a YAML file, we encourage the usage of the flag `--entity-descriptor`/`-e`. ``` $ tctl sso configure saml -e entity_desc.xml -r attr,value,role1 [] ``` ### 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` | Microsoft Entra ID | Microsoft | | `adfs` | Active Directory Federation Services | ADFS | ### Global flags These flags are available for all commands: `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples 1. Generate a SAML auth connector configuration called `myauth`. Two mappings from SAML attributes to roles are defined: - members of `admin` group will receive `access`, `editor` and `auditor` roles. - members of `developer` group will receive `access` role. The IdP metadata will be read from `entity-desc.xml` file. ``` $ tctl sso configure saml -n myauth -r group,admin,access,editor,auditor -r group,developer,access -e entity-desc.xml ``` 2. Generate a SAML auth connector configuration using the `okta` preset. The choice of preset affects the default name and display attribute, and may apply IdP-specific tweaks. Instead of an XML file, a URL was provided to the -e flag, which will be fetched by Teleport during runtime. ``` $ tctl sso configure saml -p okta -r group,dev,access -e https://dev-123456.oktapreview.com/app/ex30h8/sso/saml/metadata ``` 3. Generate a configuration and immediately test it using the `tctl sso test` command: ``` $ tctl sso configure saml -p okta -r group,developer,access -e entity-desc.xml | tctl sso test ``` ## tctl 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 [] sso test [] ``` The testing consists of running a single end-to-end authentication request using the provided auth connector definition. Once the request is finished, the results will be printed to standard output along with context-specific diagnostic information. The test process is safe from side effects in that: - it will not change the list of configured auth connectors - the audit log will clearly state the login attempts as "test" ones - there will be no certificates issued for the authenticated user --- IMPORTANT To use this command, you must have access to the `github_request`, `oidc_request`, and `saml_request` resources (depending on the type of connector being tested). If you receive a "permission denied" error, ensure that you have access to the following resources in one of your Teleport roles: ``` - resources: [github_request] verbs: [list,create,read,update,delete] - resources: [oidc_request] verbs: [list,create,read,update,delete] - resources: [saml_request] verbs: [list,create,read,update,delete] ``` --- ### Arguments - `[]` 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 ` or see the [Global Flags section](#tctl-global-flags). ### Examples Test the auth connector from `connector.yaml`: ``` $ tctl sso test connector.yaml ``` The command is designed to be used in conjunction with the `tctl sso configure` family of commands: ``` $ tctl sso configure ... | tctl sso test ``` The pipeline may also utilize `tee` to capture the connector generated with `tctl sso configure`. This will save the connector in `connector.yaml`: ``` $ tctl sso configure ... | tee connector.yaml | tctl sso test ``` You can test an existing auth connector by combining the command with `tctl get`: ``` $ tctl get saml/your-connector-name --with-secrets | tctl sso test ``` --- IMPORTANT Make sure to include `--with-secrets` flag, or the exported auth connector will not be testable. --- ## tctl stable-unix-users ls List the stored usernames and UIDs for automatically created users: ``` $ tctl stable-unix-users ls ``` ### Arguments This command accepts no arguments. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | ---------------- | ------------- | | `--format` | `text` | `json` or `text` | Output format | ### Examples ``` $ tctl stable-unix-users ls Username UID -------- ----- alice 90000 bob 90002 carol 90003 dan 90001 ``` ## tctl status Report cluster and Certificate Authority status: ``` $ tctl status ``` ### Examples ``` Checks status of cluster. $ tctl status Cluster: example.teleport.sh Version: 17.0.0 CA pins: sha256:a5322b9f89cb94fff13da4bc9c7b2e633626e35161a75f7662a179a01be84ccc authority rotation protocol status algorithm storage --------- ----------------------------------------------- -------- ------ ----------- -------- host standby (never rotated) SSH active Ed25519 software TLS active ECDSA P-256 software user standby (last rotated: Oct 3 2024 22:12:09 UTC) SSH active ECDSA P-256 AWS KMS TLS active ECDSA P-256 AWS KMS db standby (never rotated) TLS active RSA 2048 software db_client standby (never rotated) TLS active RSA 2048 software openssh standby (never rotated) SSH active Ed25519 software jwt standby (never rotated) JWT active ECDSA P-256 software saml_idp standby (never rotated) TLS active RSA 2048 software oidc_idp standby (never rotated) JWT active RSA 2048 software spiffe standby (never rotated) JWT active ECDSA P-256 software TLS active ECDSA P-256 software okta standby (never rotated) JWT active ECDSA P-256 software $ tctl status \ --auth-server=192.168.99.102:3025 \ --identity=identity.pem ``` ## tctl tokens add Create an invitation token: ``` $ tctl tokens add --type=TYPE [] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | --------------------------------------------------------------------------------- | ------------------------------------- | | `--format` | none | `text`, `json`, `yaml` | Output format | | `--labels` | none | `text` | Sets token labels | | `--ttl` | 1h | Duration like 5s, 2m, or 3h | Sets how long the token is valid for. | | `--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 | ### Global flags These flags are available for all commands `--debug, --config` . Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### 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,region=us-west Generate an invite token for a node This is equivalent to `tctl nodes add` $ tctl tokens add --type=node Generate a join token for both a Node and the Database Service $ tctl tokens add --type=node,db Generate an invite token for a kubernetes_service $ tctl tokens add --type=kube Generate an invite token for an app_service $ tctl tokens add --type=app ``` ## tctl tokens ls List node and user invitation tokens: ``` $ tctl tokens ls [] ``` ### 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 ` or see the [Global Flags section](#tctl-global-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 tokens rm Delete/revoke an invitation token: ``` $ tctl tokens rm [] ``` ### Arguments - `` The full-length token string to delete ## tctl top Reports diagnostic information. `tctl top` can consume metrics from a HTTP diagnostic endpoint. ``` $ tctl top [] [] ``` When a specific endpoint is provided, `tctl top` will always attempt to connect to it. The endpoint should be a valid HTTP URL, corresponding to a matching diagnostic metrics service configuration such as `teleport start --diag-addr=`. When no endpoint is specified, `tctl top` will attempt to connect via the debug UNIX socket endpoint, falling back to localhost. ### Argument - `[]` Diagnostic HTTP URL (HTTPS not supported) - `[]` 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 Use configured defaults $ tctl top ``` ## tctl users add Generates a user invitation token: ``` $ tctl users add [] ``` ### Arguments - `` - 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 | | `--gcp-service-accounts` | none | Comma-separated strings | List of allowed GCP service accounts for the new user | | `--azure-identities` | none | Comma-separated strings | List of Azure managed identities to allow the user to assume. Must be the full URIs of the identities | | `--ttl` | 1h | relative duration like 5s, 2m, or 3h, **maximum 48h** | Set expiration time for token | | `--host-user-uid` | none | Unix UID | UID for auto provisioned host users to use | | `--host-user-gid` | none | Unix GID | GID for auto provisioned host users to use | ### Global flags These flags are available for all commands `--debug, --config`. Run `tctl help ` or see the [Global Flags section](#tctl-global-flags). ### Examples ``` Adds Teleport user "joe" with the "access" and "requester" roles and permissions to assume the "joe" and "ubuntu" logins $ tctl users add joe --roles=access,requester --logins=joe,ubuntu ``` ## tctl users ls Lists all user accounts: ``` $ tctl users ls [] ``` ## tctl users reset Reset local user account password and any associated multi-factor devices with expiring link to populate values. **Usage**: `tctl users reset ` ### Arguments - `` - 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 users rm Deletes user accounts: ``` $ tctl users rm ``` ### Arguments - `` - comma-separated list of Teleport users ### Examples ``` $ tctl users rm sally,tim Removes users sally and tim ``` ## tctl users update Update user account: ``` $ tctl users update [] ``` ### Arguments - `` - The Teleport user account name. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------------------ | ---------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `--set-roles` | none | Comma-separated list of roles for the user to assume. | Assigns the user's roles to the ones provided, replacing the user's current roles. | | `--set-azure-identities` | none | Comma-separated list of allowed Azure identity URIs. | Assigns the user's allowed Azure identities to the ones provided, replacing the user's currently allowed Azure identities. | ### Examples Set the user `joe`'s roles to `access` and `editor`: ``` $ tctl users update joe --set-roles=access,editor ``` Set the user `priya`'s Azure identities to `developer` and `dba`: ``` $ tctl users update priya --set-azure-identities \ `/subscriptions/${SUBSCRIPTION_ID?}/resourceGroups/${MY_RESOURCE_GROUP?}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/developer,\ `/subscriptions/${SUBSCRIPTION_ID?}/resourceGroups/${MY_RESOURCE_GROUP?}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/dba ``` ## tctl autoupdate client-tools status ``` $ tctl autoupdate client-tools status [] ``` Requests the current status of client tool managed updates, indicating whether managed updates are enabled and displaying the target version for the update. If the `--proxy` flag is defined, tctl sends a request to an unauthenticated endpoint to retrieve the data. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ---------- | ---------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `--proxy` | none | none | Address of the Teleport Proxy Service. When defined this address will be used to retrieve client tool auto update configuration. | | `--format` | yaml | `json`, `yaml` | Output format: 'yaml' or 'json'. | ### Examples ``` $ tctl autoupdate client-tools status mode: enabled target_version: 17.2.7 $ tctl autoupdate client-tools status --format json { "mode": "enabled", "target_version": "17.2.7" } Request to an unauthenticated endpoint. $ tctl autoupdate client-tools status --proxy proxy.example.com mode: enabled target_version: 17.2.7 ``` ## tctl autoupdate client-tools enable Enables managed updates for client tools in the cluster. If the target version is not set, the proxy version will be advertised. ### Examples ``` $ tctl autoupdate client-tools enable client tools auto update mode has been changed ``` ## tctl autoupdate client-tools disable Disables managed updates for client tools in the cluster. ### Examples ``` $ tctl autoupdate client-tools disable client tools auto update mode has been changed ``` ## tctl autoupdate client-tools target ``` $ tctl autoupdate client-tools target [] ``` Sets the target version for client tools in the cluster. After login, client tools will be advertised to this version and initiate the update process. ### Arguments - `` - Client tools target version. Clients will be told to update to this version. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | --------- | ---------------- | ---------------- | ------------------------------------------------------------------------------- | | `--clear` | none | none | Removes the target version, Teleport will default to its current proxy version. | ### Examples ``` $ tctl autoupdate client-tools target 17.2.7 client tools auto update target version has been set $ tctl autoupdate client-tools target --clear client tools auto update target version has been cleared ``` ## tctl autoupdate agents status Prints the status of automatic updates for Teleport Agents. ### Examples ``` $ tctl autoupdate agents status Agent autoupdate mode: enabled Rollout creation date: 2025-01-14 16:17:36 Start version: 17.0.1 Target version: 17.1.5 Rollout state: Done Group Name State Start Time State Reason ---------- ----- ------------------- -------------- dev Done 2025-01-15 12:00:08 outside_window stage Done 2025-01-15 16:17:45 outside_window prod Done 2025-01-15 18:00:12 outside_window backup Done 2025-01-14 20:00:31 outside_window ``` ## tctl plugins install awsic Install the AWS Identity Center integration. ``` $ tctl plugins install awsic ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------------------------- | ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--access-list-default-owner` | none | string | Required. A Teleport username to set as the default owner for the imported Access Lists. Multiple flags allowed. | | `--scim-url` | none | string | Required. AWS Identity Center SCIM provisioning endpoint. Must be a valid AWS Identity Center SCIM endpoint URL, as per [this AWS Knowledge Center article](https://repost.aws/knowledge-center/iam-identity-center-provision). | | `--scim-token` | none | string | Required. The AWS Identify Center SCIM provisioning access bearer token. | | `--instance-arn` | none | string | Required. The ARN of the Identity Center instance to manage. | | `--instance-region` | none | string | Required. The AWS region where the Identity Center instance is located. | | `--[no-]use-system-credentials` | `--no-use-system-credentials` | boolean | Required. Use system AWS credentials to authenticate with AWS. Note that currently only `--use-system-credentials` is supported by `tctl`. | | `--assume-role-arn` | none | string | Required. AWS IAM Role ARN value that the integration will use to obtain a temporary security credential. | | `--[no]force-scim-url` | `--no-force-scim-url` | boolean | Optional. Force the use of the provided SCIM provisioning endpoint even if it fails SCIM endpoint validation. | | `--user-label` | none | string | Optional. Add user label filter, in the form of a comma-separated list of "name=value" pairs. All matching users will be provisioned to AWS Identity Center. If no label filters are supplied, *all* Teleport users will be provisioned to Identity Center. Multiple filters allowed. | | `--user-origin` | none | string | Optional. Shorthand for setting a label filter that filters by origin. For example, `--user-origin $ORIGIN` is identical to specifying `--user-label teleport.dev/origin=$ORIGIN`. | | `--group-name` | none | string | Optional. Add an AWS Identity Center group to group to the group import list by name. Can be a glob, or enclosed in `^$` to specify a regular expression. If no filters are supplied then *all* AWS groups will be imported. | | `--account-name` | none | string | Optional. Add an AWS account to the account import list by name. Can be a glob, or enclosed in `^$` to specify a regular expression. *All* AWS accounts will be imported if no items are added to account import list. Multiple filters allowed. | | `--account-id` | none | string | Optional. Adds a specific AWS account to account import list by ID. *All* AWS accounts will be imported if no items are added to account import list. | ### Example ``` $ tctl plugins install awsic \ --instance-arn "arn:aws:sso:::instance/ssoins-722326ecc902a06a" \ --instance-region us-east-1 \ --use-system-credentials \ --assume-role-arn arn:aws:iam::xxxx:role/role-name-to-assume \ --scim-url https://scim.us-east-1.amazonaws.com/f3v9c6bc2ca-b104-4571-b669-f2eba522efe8/scim/v2 \ --scim-token ${IDENTITY_CENTER_SCIM_BEARER_TOKEN} \ --access-list-default-owner admin \ --access-list-default-owner root@example.com \ --user-origin okta \ --user-label "role=aws-admin,dept=engineering" \ --account-name "^production ap-southeast-\d$" \ --account-id "637423191929" \ --group-name "^Group 001\d$" ``` Multiple `--access-list-default-owner` flags are collected together. In the given example, all Access Lists imported by the integration will be created wth owners `admin` and `root@example.com`. Multiple filter flags are ORd together. For example, in the command line above the two user filter flags imply that if a user - was provisioned into Teleport by Okta (from `--user-origin okta`), OR - has the label values `role=aws-admin` AND `dept=engineering` (from `--user-label "role=aws-admin,dept=engineering"`) then they will be provisioned into AWS Identity Center by Teleport. ## tctl plugins install okta Install the Okta integration. ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ------------------------ | ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `--name` | `okta` | string | Required. Name of the plugin resource to create. | | `--org` | none | URL | Required. URL of Okta organization. | | `--saml-connector` | none | string | Required. SAML connector used for Okta SSO login. | | `--app-id` | none | string | Optional. Okta ID of the APP used for SSO via SAML. | | `--api-token` | none | string | Optional. Okta API token for the plugin to use. | | `--[no-]scim` | `--no-scim` | boolean | Optional. Enable SCIM Okta integration. | | `--[no-]users-sync` | `--users-sync` | none | Optional. Enable user synchronization. | | `-o`, `--owner` | none | string | Optional. Add a default owner for synced Access Lists. | | `--[no-]accesslist-sync` | `--accesslist-sync` | none | Optional. Enable or disable group to Access List synchronization. | | `--[no-]appgroup-sync` | `--appgroup-sync` | none | Optional. Enable or disable Okta Applications and Groups sync. | | `-g`, `--group-filter` | none | string | Optional. Add a group filter. Supports globbing by default. Enclose in `^pattern$` for full regex support. | | `-a`, `--app-filter` | none | string | Optional. Add an app filter. Supports globbing by default. Enclose in `^pattern$` for full regex support. | ### Example ``` $ tctl plugins install okta \ --org https://example.okta.com \ --saml-connector "okta" \ --app-id xxxxxxx \ --api-token ${OKTA_API_TOKEN} \ --no-scim \ --no-accesslist-sync \ --no-appgroup-sync ``` ## tctl plugins rotate awsic Rotate the bearer token used by Teleport to authenticate with the AWS IAM Identity Center SCIM service when provisioning AWS users and groups. By default, `tctl` will validate that the token can be used to authenticate with the SCIM service configured in the integration. Use the `--no-validate-token` flag to disable token validation. ``` $ tctl plugins rotate awsic [] ``` ### Flags | Name | Default Value(s) | Allowed Value(s) | Description | | ----------------------- | ------------------ | ---------------- | ------------------------------------------------------------------------------------ | | `--plugin-name` | | string | Optionally override the name of the AWS IAM Identity Center integration to target | | `--[no-]validate-token` | `--validate-token` | none | Enables or disables validating the supplied token against the configured SCIM server | ### Examples Rotate the SCIM bearer token without displaying the token in your command history ``` $ tctl plugins rotate awsic $(cat ./aws-iam-ic-bearer-token) ``` Rotate the the SCIM bearer token for a custom integration enrollment that does not have the default name set by the guided enrollment flow. ``` $ tctl plugins rotate awsic --plugin-name "my-custom-ic-integration" ${TOKEN_VALUE} ``` ## tctl version Print the version of your `tctl` binary: ``` tctl version ```