Skip to main content
Version: 18.x

Getting Started with tctl

Report an issue with this page

This guide provides an overview of tctl, a command-line tool for managing Teleport dynamic resources.

For an overview of what a dynamic resource is, see Infrastructure as Code.

For a comprehensive list of tctl commands, arguments, flag, and environment variables, see the tctl CLI Reference.

When to use tctl​

tctl is a Teleport Auth Service client that manages dynamic resources. The following Teleport Auth Service clients can also manage dynamic resources:

tctl is best suited for ad hoc operations such as retrieving data about your cluster or unanticipated configuration changes. You can also use it to manage resources on small-scale Teleport clusters.

As the number of Teleport resources increases, we recommend that you to switch to IaC tools such as Terraform or the Kubernetes operator as they offer more robust resource lifecycle management.

tctl permissions​

Every Teleport Auth Service client has an identity with a Teleport username and a list of roles. The identity must list every Teleport resource it has permissions to perform operations on and every operation it has permissions to perform. For example, the following Teleport role has permissions to perform all operations on app resources but read-only operations on Teleport roles:

allow:
  rules:
    - resources:
        - role
      verbs: [list, read]
    - resources:
        - app
      verbs: [list, create, read, update, delete]

See-the Role Reference for more information on configuring access to Teleport resources.

Audit log​

When you create or modify a resource with tctl, Teleport records the operation in the audit log. You can use the Teleport username associated with each audit event to determine which resource modifications took place using tctl and which ones occurred with the Terraform provider, Kubernetes operator, or custom API clients.

See the audit event reference for a full list of events.

Authentication​

Before running tctl commands, administrators must authenticate to a Teleport cluster. You can authenticate to your cluster by running the following command:

tsh login --user=TELEPORT_USER --proxy=PROXY_SERVICE_ADDRESS

See the tsh login reference entry for a full list of tsh login flags.

Using the local Auth Service backend​

Administrators of a self-hosted Teleport cluster can manage the cluster by authenticating to a host that runs 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 the TELEPORT_CONFIG_FILE environment variable points to a configuration file in another location. If the auth_service is disabled in the configuration file, then the configuration file is ignored.

warning

If you set up demo Teleport clusters on your workstation, make sure you remove any configuration files when you are done so tctl works as intended. If tctl attempts to connect to a Teleport cluster on your local machine, you will see an error similar to the following:

ERROR: open /var/lib/teleport/host_uuid: permission denied

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.

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

Resources you can view​

You can view the following resources with the tctl get command:

  • access_graph_settings
  • access_list
  • access_monitoring_rule
  • access_request
  • app
  • app_server
  • audit_query
  • auth_server
  • autoupdate_agent_report
  • autoupdate_agent_rollout
  • autoupdate_bot_instance_report
  • autoupdate_config
  • autoupdate_version
  • bot
  • bot_instance
  • cert_authority
  • cluster_auth_preference
  • cluster_maintenance_config
  • cluster_networking_config
  • connectors
  • crown_jewel
  • db
  • db_object
  • db_object_import_rule
  • db_server
  • db_service
  • device
  • discovery_config
  • dynamic_windows_desktop
  • external_audit_storage
  • git_server
  • github
  • health_check_config
  • inference_model
  • inference_policy
  • inference_secret
  • installer
  • integration
  • kube_cluster
  • kube_server
  • lock
  • login_rule
  • namespace
  • network_restrictions
  • node
  • oidc
  • okta_assignment
  • okta_import_rule
  • plugin
  • proxy
  • relay_server
  • remote_cluster
  • role
  • saml
  • saml_idp_service_provider
  • scoped_role
  • scoped_role_assignment
  • security_report
  • semaphore
  • server_info
  • session_recording_config
  • sigstore_policy
  • spiffe_federation
  • static_host_user
  • token
  • trusted_cluster
  • tunnel
  • ui_config
  • user
  • user_group
  • user_task
  • vnet_config
  • windows_desktop
  • windows_desktop_service
  • workload_identity
  • workload_identity_x509_issuer_override
  • workload_identity_x509_revocation