# Getting Started with tctl 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](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code.md). For a comprehensive list of `tctl` commands, arguments, flag, and environment variables, see the [`tctl` CLI Reference](https://goteleport.com/docs/reference/cli/tctl.md). ## 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: - [Teleport Terraform provider](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider.md) - [Teleport Kubernetes operator](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/teleport-operator.md) - [Custom API clients](https://goteleport.com/docs/zero-trust-access/api.md) `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](https://goteleport.com/docs/reference/access-controls/roles.md#rbac-for-dynamic-teleport-resources) 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](https://goteleport.com/docs/reference/audit-events.md) 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`](https://goteleport.com/docs/reference/cli/tsh.md#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](https://goteleport.com/docs/zero-trust-access/authentication.md) 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=`, 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`