diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx index 497c5fec5bf8e..ad1f8df4d8ff3 100644 --- a/docs/pages/access-controls/guides/per-session-mfa.mdx +++ b/docs/pages/access-controls/guides/per-session-mfa.mdx @@ -41,6 +41,8 @@ their on-disk Teleport certificates. (!docs/pages/includes/edition-prereqs-tabs.mdx!) +(!docs/pages/includes/tctl.mdx!) + - [WebAuthn configured](webauthn.mdx) on this cluster - Second factor hardware device, such as YubiKey or SoloKey - A Web browser with [WebAuthn support]( diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx index ba6e0ea3744bc..34e6fd3ea9083 100644 --- a/docs/pages/access-controls/reference.mdx +++ b/docs/pages/access-controls/reference.mdx @@ -4,7 +4,8 @@ description: Access Controls reference documentation for role options and proper h1: Teleport Access Controls Reference --- -This document describes Teleport Roles, Role Options, and Role-Based Access Control (RBAC) for Teleport Access Controls. +This guide shows you how to use Teleport roles to manage role-based access +controls (RBAC) in your Teleport cluster. ## Roles @@ -33,10 +34,26 @@ To manage cluster roles, a Teleport administrator can use the Web UI or the command line using [tctl resource commands](../setup/reference/resources.mdx). To see the list of roles in a Teleport cluster, an administrator can execute: + + ```code +# Log in to your cluster with tsh so you can use tctl. +# You can also run tctl on your Auth Service host. +$ tsh login --user=myuser --proxy=teleport.example.com $ tctl get roles ``` + + + +```code +# Log in to your cluster with tsh so you can use tctl. +$ tsh login --user=myuser --proxy=mytenant.teleport.sh +$ tctl get roles +``` + + + (!docs/pages/includes/backup-warning.mdx!) A role definition looks like this: diff --git a/docs/pages/application-access/getting-started.mdx b/docs/pages/application-access/getting-started.mdx index 43127b9ab9a13..7c4624138c5e4 100644 --- a/docs/pages/application-access/getting-started.mdx +++ b/docs/pages/application-access/getting-started.mdx @@ -23,7 +23,10 @@ Let's connect to Grafana using Teleport Application Access in three steps: ## Prerequisites -- The Teleport Auth Service and Proxy Service, deployed on your own infrastructure or via Teleport Cloud. +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + - A Docker installation, which we will use to launch Grafana in a container. Alternatively, if you have another web application you'd like to protect with Application Access, you can use that instead. - A host where you will run the Teleport Application Service. diff --git a/docs/pages/application-access/guides/dynamic-registration.mdx b/docs/pages/application-access/guides/dynamic-registration.mdx index ceb2ab54a40db..fb9252734298e 100644 --- a/docs/pages/application-access/guides/dynamic-registration.mdx +++ b/docs/pages/application-access/guides/dynamic-registration.mdx @@ -82,10 +82,27 @@ version: v5 To create an application resource, run: + + +```code +# Log in to your Teleport cluster so you can use tctl remotely. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser +$ tctl create app.yaml +``` + + + + ```code +# Log in to your Teleport cluster so you can use tctl remotely. +$ tsh login --proxy=mytenant.teleport.sh --user=myuser $ tctl create app.yaml ``` + + + After the resource has been created, it will appear among the list of available apps (in `tsh app ls` or UI) as long as at least one application agent picks it up according to its label selectors. diff --git a/docs/pages/application-access/reference.mdx b/docs/pages/application-access/reference.mdx index c480cf36d397e..0eee16d52d4c5 100644 --- a/docs/pages/application-access/reference.mdx +++ b/docs/pages/application-access/reference.mdx @@ -94,6 +94,31 @@ spec: period: 1m0s ``` +You can create a new `app` resource by running the following commands, which +assume that you have created a YAML file called `app.yaml` with your configuration: + + + +```code +# Log in to your Teleport cluster. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser +# Create the resource +$ tctl create -f app.yaml +``` + + + + +```code +# Log in to your Teleport cluster. +$ tsh login --proxy=mytenant.teleport.sh --user=myuser +# Create the resource. +$ tctl create -f app.yaml +``` + + + ## CLI This section shows CLI commands relevant for Application Access. diff --git a/docs/pages/architecture/overview.mdx b/docs/pages/architecture/overview.mdx index 4aa0348585da6..704dfc46dbc85 100644 --- a/docs/pages/architecture/overview.mdx +++ b/docs/pages/architecture/overview.mdx @@ -109,13 +109,6 @@ steps are explained in detail below the diagram. ![Teleport Everything](../../img/everything.svg) - - The Teleport Admin tool, `tctl`, must be physically present on the same machine where Teleport Auth is running. Adding new nodes or inviting new users to the cluster is only possible using this tool. - - ### 1: Initiate client connection ![Client offers certificate](../../img/client_initiate.svg) @@ -215,7 +208,7 @@ Finally, the client is authorized to create an SSH connection to a node. Teleport offers two command-line tools. `tsh` is a client tool used by the end users, while `tctl` is used for cluster administration. -### TSH +### `tsh` `tsh` is similar in nature to OpenSSH `ssh` or `scp`. It has subcommands named after them so you can call: @@ -234,16 +227,18 @@ valid for 12 hours by default, unless you specify another interval via the You can learn more about `tsh` in the [User Manual](../server-access/guides/tsh.mdx). -### TCTL +### `tctl` -`tctl` is used to administer a Teleport cluster. It connects to the Auth -server listening on `127.0.0.1` and allows a cluster administrator to manage -nodes and users in the cluster. +`tctl` is used to administer a Teleport cluster. It connects to the Teleport +Auth Service and allows an administrator to manage Nodes, users, and other +resources in the cluster. -`tctl` is also a tool that can be used to modify the dynamic configuration of -the cluster, like creating new user roles or connecting trusted clusters. +You can run `tctl` commands either remotely or on the Teleport Auth Service +host. When run remotely, `tctl` requires that the user authenticate to the +cluster. When run on the Auth Service host, `tctl` uses the identity of the Auth +Service itself, and does not require additional authentication. -You can learn more about `tctl` in the [Admin Manual](../setup/admin.mdx). +You can learn more about `tctl` in the [CLI Reference](../setup/reference/cli.mdx#tctl). ## Next steps diff --git a/docs/pages/architecture/users.mdx b/docs/pages/architecture/users.mdx index 8cb3a0809d6fb..aaf2592ce48ef 100644 --- a/docs/pages/architecture/users.mdx +++ b/docs/pages/architecture/users.mdx @@ -4,10 +4,6 @@ description: This chapter explains the concept of a Teleport User and how it's d h1: Teleport Users --- -{ - /* TODO: This doc is incomplete, pending addition of Enterprise topics */ -} - ## Types of users Unlike traditional SSH, Teleport introduces the concept of a User Account. A User Account is not the same as SSH login. Instead, each Teleport User is associated with another account which is used to authenticate the user. @@ -33,10 +29,6 @@ Let's look at this table: | juliet | juliet | Teleport user `juliet` can log in into member nodes only as OS user `juliet`. | | ross | | If no OS login is specified, it defaults to the same name as the Teleport user, here this is `ross`. | -To add a new user to Teleport, you have to use the `tctl` tool on the same node -where the auth server is running, i.e. `teleport` was started with -`--roles=auth` . - A cluster administrator must create account entries for every Teleport user with [`tctl users add`](../setup/reference/cli.mdx). Every Teleport User must be associated with a list of one or more machine-level OS usernames it can authenticate as during a login. This list is called "user mappings". diff --git a/docs/pages/database-access/guides/gui-clients.mdx b/docs/pages/database-access/guides/gui-clients.mdx index e6ca98ccf4417..2be158f86072f 100644 --- a/docs/pages/database-access/guides/gui-clients.mdx +++ b/docs/pages/database-access/guides/gui-clients.mdx @@ -18,11 +18,9 @@ Ensure that your environment includes the following: - A running Teleport cluster. For details on how to set this up, see one of our [Getting Started](/docs/getting-started) guides. -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=). +- The `tsh` client tool version >= (=teleport.version=). ```code - $ tctl version - # Teleport v(=teleport.version=) go(=teleport.golang=) $ tsh version # Teleport v(=teleport.version=) go(=teleport.golang=) ``` @@ -36,14 +34,11 @@ Ensure that your environment includes the following: - A running Teleport cluster. For details on how to set this up, see our Enterprise [Getting Started](/docs/enterprise/getting-started) guide. -- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=), - which you can download by visiting the +- The `tsh` client tool version >= (=teleport.version=), which you can download + by visiting the [customer portal](https://dashboard.gravitational.com/web/login). ```code - $ tctl version - # Teleport v(=teleport.version=) go(=teleport.golang=) - $ tsh version # Teleport v(=teleport.version=) go(=teleport.golang=) ``` @@ -55,13 +50,10 @@ Ensure that your environment includes the following: - A Teleport Cloud account. If you do not have one, visit the [sign up page](https://goteleport.com/signup/) to begin your free trial. -- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=). - To download these tools, visit the [Downloads](/docs/cloud/downloads) page. +- The `tsh` client tool version >= (=cloud.version=). To download these tools, + visit the [Downloads](/docs/cloud/downloads) page. ```code - $ tctl version - # Teleport v(=cloud.version=) go(=teleport.golang=) - $ tsh version # Teleport v(=cloud.version=) go(=teleport.golang=) ``` diff --git a/docs/pages/database-access/guides/redis-cluster.mdx b/docs/pages/database-access/guides/redis-cluster.mdx index 09acc9111687e..fbb68c6841305 100644 --- a/docs/pages/database-access/guides/redis-cluster.mdx +++ b/docs/pages/database-access/guides/redis-cluster.mdx @@ -31,10 +31,19 @@ This guide will help you to: ## Prerequisites -- Teleport version `9.0` or newer. - Redis version `6.0` or newer. + - `redis-cli` installed and added to your system's `PATH` environment variable. +- A host where you will run the Teleport Database Service. Teleport version 9.0 + or newer must be installed. + + See [Installation](../../installation.mdx) for details. + +(!docs/pages/includes/user-client-prereqs.mdx!) + +(!docs/pages/includes/tctl.mdx!) + Redis `7.0` and RESP3 (REdis Serialization Protocol) are currently not supported. diff --git a/docs/pages/database-access/reference/cli.mdx b/docs/pages/database-access/reference/cli.mdx index 32ffa6d602995..1dd0f9ddb0e84 100644 --- a/docs/pages/database-access/reference/cli.mdx +++ b/docs/pages/database-access/reference/cli.mdx @@ -3,6 +3,20 @@ title: Database Access CLI Reference description: CLI reference for Teleport Database Access. --- +This reference shows you how to run common commands for managing Teleport +Database Access, including: + +- The `teleport` daemon command, which is executed on the host where you + will run the Teleport Database Service. + +- The `tctl` administration tool, which you use to manage `db` resources that + represent databases known to your Teleport cluster. + + (!docs/pages/includes/tctl.mdx!) + +- The `tsh` client tool, which end-users run in order to access databases in + your cluster. + ## teleport db start Starts Teleport Database Service agent. diff --git a/docs/pages/database-access/reference/configuration.mdx b/docs/pages/database-access/reference/configuration.mdx index 76705be84823e..3cdf32e3a035c 100644 --- a/docs/pages/database-access/reference/configuration.mdx +++ b/docs/pages/database-access/reference/configuration.mdx @@ -164,3 +164,28 @@ spec: command: ["hostname"] period: 1m0s ``` + +You can create a new `db` resource by running the following commands, which +assume that you have created a YAML file called `db.yaml` with your configuration: + + + +```code +# Log in to your Teleport cluster. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser +# Create the resource +$ tctl create -f db.yaml +``` + + + + +```code +# Log in to your Teleport cluster +$ tsh login --proxy=mytenant.teleport.sh --user=myuser +# Create the resource +$ tctl create -f db.yaml +``` + + diff --git a/docs/pages/desktop-access/getting-started.mdx b/docs/pages/desktop-access/getting-started.mdx index 4ad651efb5ca6..27bacf4f08229 100644 --- a/docs/pages/desktop-access/getting-started.mdx +++ b/docs/pages/desktop-access/getting-started.mdx @@ -30,6 +30,10 @@ This guide requires you to have: You can reuse an existing server running any other Teleport instance. +- The `tctl` administration tool version >= (=teleport.version=) + + (!docs/pages/includes/tctl.mdx!) + ## Step 1/7. Create a restrictive service account Teleport requires a service account to connect to your Active Directory domain. diff --git a/docs/pages/desktop-access/reference/cli.mdx b/docs/pages/desktop-access/reference/cli.mdx index a0c46de18d583..a244da40c8353 100644 --- a/docs/pages/desktop-access/reference/cli.mdx +++ b/docs/pages/desktop-access/reference/cli.mdx @@ -3,7 +3,9 @@ title: Desktop Access CLI Reference description: CLI reference for Teleport Desktop Access. --- -# Desktop Access CLI Reference +The following `tctl` commands are used to manage Teleport Desktop Access. + +(!docs/pages/includes/tctl.mdx!) Generate a join token for a Windows Desktop Service: diff --git a/docs/pages/desktop-access/troubleshooting.mdx b/docs/pages/desktop-access/troubleshooting.mdx index ef5831cf36e27..5be26057a0fbc 100644 --- a/docs/pages/desktop-access/troubleshooting.mdx +++ b/docs/pages/desktop-access/troubleshooting.mdx @@ -45,7 +45,27 @@ This means that the host does not trust the Teleport CA. First, make sure that you [import the Teleport CA into Group Policy](./getting-started.mdx#create-another-gpo-and-import-the-teleport-ca). Note that if the Teleport CA was rotated since the last import, you will have to fetch the -new CA using `tctl auth export --type=windows >user-ca.cer` +new CA using the following command: + + + +```code +# Log in to your Teleport cluster so you can use tctl remotely. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser +$ tctl auth export --type=windows >user-ca.cer +``` + + + + +```code +# Log in to your Teleport cluster so you can use tctl remotely. +$ tsh login --proxy=mytenant.teleport.sh --user=myuser +$ tctl auth export --type=windows >user-ca.cer +``` + + If that doesn't help, log into the target host directly, open PowerShell and run `gpupdate.exe /force`. This forces a Group Policy sync and should pick up diff --git a/docs/pages/enterprise/hsm.mdx b/docs/pages/enterprise/hsm.mdx index b1edac7522235..d75c7688f47a9 100644 --- a/docs/pages/enterprise/hsm.mdx +++ b/docs/pages/enterprise/hsm.mdx @@ -9,7 +9,13 @@ This guide will show you how to set up the Teleport Auth Server to use a hardwar ## Prerequisites - Teleport v(=teleport.version=) Enterprise (self-hosted). + +- The `tctl` administration tool version >= (=teleport.version=). + + (!docs/pages/includes/tctl.mdx!) + - An HSM reachable from your Teleport auth server. + - The PKCS#11 module for your HSM.
diff --git a/docs/pages/enterprise/workflow/ssh-approval-mattermost.mdx b/docs/pages/enterprise/workflow/ssh-approval-mattermost.mdx index ec82bcbd46069..1ef27186c5a39 100644 --- a/docs/pages/enterprise/workflow/ssh-approval-mattermost.mdx +++ b/docs/pages/enterprise/workflow/ssh-approval-mattermost.mdx @@ -34,6 +34,7 @@ This guide assumes that you have: Teleport Cloud requires that plugins connect through the Proxy Service (`mytenant.teleport.sh:443`). Open Source and Enterprise installations can connect to the Auth Service (`auth.example.com:3025`) directly. +(!docs/pages/includes/tctl.mdx!) ### Setting up Mattermost to work with the bot diff --git a/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx b/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx index 6e8e734dfdf84..a177164365529 100644 --- a/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx +++ b/docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx @@ -23,6 +23,7 @@ This guide assumes that you have: Teleport Cloud requires that plugins connect through the Proxy Service (`mytenant.teleport.sh:443`). Open Source and Enterprise installations can connect to the Auth Service (`auth.example.com:3025`) directly. +(!docs/pages/includes/tctl.mdx!) ### Create a user and role for access diff --git a/docs/pages/includes/user-client-prereqs.mdx b/docs/pages/includes/user-client-prereqs.mdx index fbdc1cefb65b9..a6d0af660552b 100644 --- a/docs/pages/includes/user-client-prereqs.mdx +++ b/docs/pages/includes/user-client-prereqs.mdx @@ -1,9 +1,12 @@ -- The `tsh` client tool version >= (=teleport.version=). +- The `tctl` and `tsh` client tools version >= (=teleport.version=). ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + $ tsh version # Teleport v(=teleport.version=) go(=teleport.golang=) ``` @@ -18,11 +21,14 @@ -- The `tsh` client tool version >= (=teleport.version=), which you can download - by visiting the +- The `tctl` and `tsh` client tools version >= (=teleport.version=), which you + can download by visiting the [customer portal](https://dashboard.gravitational.com/web/login). ```code + $ tctl version + # Teleport v(=teleport.version=) go(=teleport.golang=) + $ tsh version # Teleport v(=teleport.version=) go(=teleport.golang=) ``` diff --git a/docs/pages/kubernetes-access/controls.mdx b/docs/pages/kubernetes-access/controls.mdx index 1974e4b7ad920..2b621ffe47887 100644 --- a/docs/pages/kubernetes-access/controls.mdx +++ b/docs/pages/kubernetes-access/controls.mdx @@ -120,10 +120,26 @@ spec: Create or update this role using `tctl`: + + ```code +# Log in to your Teleport cluster so you can use tctl remotely. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser $ tctl create -f member.yaml ``` + + + +```code +# Log in to your Teleport cluster so you can use tctl remotely. +$ tsh login --proxy=mytenant.teleport.sh --user=myuser +$ tctl create -f member.yaml +``` + + + Assign this role to a user in OIDC or SAML connector: diff --git a/docs/pages/kubernetes-access/guides/cicd.mdx b/docs/pages/kubernetes-access/guides/cicd.mdx index 9c3e70e41a2a7..c8a231ede8c4c 100644 --- a/docs/pages/kubernetes-access/guides/cicd.mdx +++ b/docs/pages/kubernetes-access/guides/cicd.mdx @@ -40,14 +40,35 @@ spec: Generate a `kubeconfig` using the `jenkins` user and its roles using [`tctl auth sign`](../../setup/reference/cli.mdx#tctl-auth-sign): + + +```code +# Log in to your Teleport cluster so you can use tctl remotely. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser +# Create a new local user for Jenkins +$ tctl users add jenkins --roles=robot +# Creates a token for 25hrs +$ tctl auth sign --user=jenkins --format=kubernetes --out=kubeconfig --ttl=25h +``` + + + + ```code +# Log in to your Teleport cluster so you can use tctl remotely. +$ tsh login --proxy=mytenant.teleport.sh --user=myuser # Create a new local user for Jenkins $ tctl users add jenkins --roles=robot # Creates a token for 25hrs $ tctl auth sign --user=jenkins --format=kubernetes --out=kubeconfig --ttl=25h +``` + + -# The credentials have been written to kubeconfig +Verify that these credentials have been written to kubeconfig: +```code $ cat kubeconfig # apiVersion: v1 # clusters: diff --git a/docs/pages/machine-id/getting-started.mdx b/docs/pages/machine-id/getting-started.mdx index 374a19c77ad63..02ca07c09f4ad 100644 --- a/docs/pages/machine-id/getting-started.mdx +++ b/docs/pages/machine-id/getting-started.mdx @@ -15,11 +15,11 @@ Here's an overview of what you will do: ## Prerequisites -Before using Machine ID, you will need an existing Teleport cluster or a -Teleport Cloud account. +- A host that you wish to assign an identity to using Machine ID. -If you have not set up a Teleport cluster before, follow the -[Getting started](https://goteleport.com/docs/getting-started) guide. +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +(!/docs/pages/includes/tctl.mdx!) TLS Routing support will be added to Machine ID in [Teleport diff --git a/docs/pages/setup/guides/ssh-key-extensions.mdx b/docs/pages/setup/guides/ssh-key-extensions.mdx index 018ab83b27955..435cbe470f80a 100644 --- a/docs/pages/setup/guides/ssh-key-extensions.mdx +++ b/docs/pages/setup/guides/ssh-key-extensions.mdx @@ -15,10 +15,26 @@ Teleport supports exporting user SSH certificates with configurable key extensio In order to export the Teleport CA, execute the following command: + + ```code +# Log in to your Teleport cluster so you can use tctl remotely. +# You can also run tctl on your Auth Service host. +$ tsh login --proxy=teleport.example.com --user=myuser $ tctl auth export --type=user | sed 's/^cert-authority //g' ``` + + + +```code +# Log in to your Teleport cluster so you can use tctl remotely. +$ tsh login --proxy=mytenant.teleport.sh --user=myuser +$ tctl auth export --type=user | sed 's/^cert-authority //g' +``` + + + Next, follow the instructions in the guide below to import your Teleport CA into GitHub: [Managing your organization's SSH certificate authorities](https://docs.github.com/en/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities) diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index efdc5669a6aab..85dd59181af5e 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -704,53 +704,89 @@ creating new user roles or connecting Trusted Clusters. -By default, `tctl` connects to a local Auth Service, meaning that it will fail -if you attempt to run `tctl` on a non-`auth` host. +When running `tctl` commands, administrators must authenticate to a Teleport +cluster. This can be done in three ways: -`tctl` can also connect to a remote Auth Service if the `--identity` and -`--auth-server` flags are used. An identity file for use with `--identity` -can be exported with `tctl auth sign` or `tsh login --out=`. +### 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` only authenticates using this method if an identity file is not provided. - Note that when a `tctl` command is run locally on an Auth Service, the audit + 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 properly audit admin actions at scale, it is important to limit direct SSH - access to the Auth Service with + To provide an accurate audit trail, it is important to limit direct SSH access + to the Auth Service with [Access Controls](../../access-controls/introduction.mdx) and ensure that - admins use `tctl` remotely with the `--identity` flag instead. + admins use `tctl` remotely instead. -The `TELEPORT_CONFIG_FILE` environment variable indicates where the Teleport -configuration file is. +### 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`. -If you're connecting to a remote Teleport cluster through a `tsh` session and -have a file named `/etc/teleport.yaml` on your machine set the `TELEPORT_CONFIG_FILE` -to `""`. Otherwise `tctl` will attempt to connect to a Teleport cluster on the -machine, which could result in the error, +`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`. -You will need to download the Enterprise version of Teleport from the -[customer portal](https://dashboard.gravitational.com/web/login) to run `tctl` -commands in Teleport Cloud. +When running `tctl` commands, administrators must authenticate to a Teleport +cluster. This can be done in two ways: -You must log in to your cluster before you can run `tctl` commands. -```code -$ tsh login --proxy=mytenant.teleport.sh -$ tctl status -``` +### 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: -The `TELEPORT_CONFIG_FILE` environment variable indicates where the Teleport -configuration file is. +- `TELEPORT_CONFIG_FILE` is blank +- No file exists at `/etc/teleport.yaml` -If you have a file named `/etc/teleport.yaml` on your local machine, set the -`TELEPORT_CONFIG_FILE` to `""`. Otherwise `tctl` will attempt to connect to a -Teleport cluster on the machine, which could result in the error, +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`.