Edit tctl instructions to clarify remote login (#12525)

* Edit tctl instructions to clarify remote login Closes #11464 - Ensure that all example tctl commands are accompanied either by instructions to log in to the cluster or the tctl.mdx partial. - Edit the guides in the Architecture section to remove notes that tctl can only be used locally to the Auth Service. - Edit the user-client-rereqs partial to mention tctl for all editions, since you can log in to tctl remotely for all editions. Not editing guides where: - tctl is run via kubectl exec - tctl is not mentioned in a code block, i.e., only in passing, and a reader isn't expected to run the command on their own while following the guide. - The user is already expected to run tctl on the Auth Service. The docker-compose Getting Started guide is an example of this. * Respond to PR feedback - Provide more context on authenticating with tctl in the CLI reference - Update the link to more information re: tctl in the architecture overview, and indicate that tctl users must authenticate. - Minor tweaks. * Respond to PR feedback - Rephrase the authentication paragraph in the Architecture Overview.
2026-09-24 16:17:11 +08:00 · 2022-05-26 15:11:27 +00:00
parent a2450423ba
commit 3ef5cd8ee9
24 changed files with 306 additions and 77 deletions
@@ -42,6 +42,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](
@@ -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:

+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ```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
 ```

+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```code
+# Log in to your cluster with tsh so you can use tctl.
+$ tsh login --user=myuser --proxy=mytenant.teleport.sh
+$ tctl get roles
+```
+
+</ScopedBlock>
+
 (!docs/pages/includes/backup-warning.mdx!)

 A role definition looks like this:
@@ -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.

@@ -82,10 +82,27 @@ version: v5

 To create an application resource, run:

+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ```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
 ```

+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```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
+```
+
+</ScopedBlock>
+
+
 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.
@@ -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:
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+```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
+```
+
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```code
+# Log in to your Teleport cluster.
+$ tsh login --proxy=mytenant.teleport.sh --user=myuser
+# Create the resource.
+$ tctl create -f app.yaml
+```
+
+</ScopedBlock>
+
 ## CLI

 This section shows CLI commands relevant for Application Access.
@@ -109,13 +109,6 @@ steps are explained in detail below the diagram.

 ![Teleport Everything](../../img/everything.svg)

-<Admonition
-  type="note"
-  title="Caution"
->
-  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.
-</Admonition>
-
 ### 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

@@ -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".

@@ -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=)
  ```
@@ -43,6 +43,8 @@ This guide will help you to:

 (!docs/pages/includes/user-client-prereqs.mdx!)

+(!docs/pages/includes/tctl.mdx!)
+
 <Admonition type="note" title="Note">
  Redis `7.0` and RESP3 (REdis Serialization Protocol) are currently not supported.
 </Admonition>
@@ -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.
@@ -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:
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+```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
+```
+
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```code
+# Log in to your Teleport cluster
+$ tsh login --proxy=mytenant.teleport.sh --user=myuser
+# Create the resource
+$ tctl create -f db.yaml
+```
+
+</ScopedBlock>
@@ -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.
@@ -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:

@@ -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:
+
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+```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
+```
+
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```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
+```
+
+</ScopedBlock>

 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
@@ -24,7 +24,13 @@ This guide is intended for Teleport Enterprise users.
 ## 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.

 <Admonition type="warning" scope={["cloud", "oss"]} opened={true} scopeOnly={true} title="Compatibility Warning">
@@ -78,10 +78,26 @@ the `user` role depending on the value returned for `group` within the claims.

 Create the connector:

-```bsh
+<ScopedBlock scope={["oss", "enterprise"]}>
+
+```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 oidc-connector.yaml
 ```

+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```code
+# Log in to your Teleport cluster so you can use tctl remotely
+$ tsh login --proxy=mytenant.teleport.sh --user=myuser
+$ tctl create oidc-connector.yaml
+```
+
+</ScopedBlock>
+
 ## Create Teleport Roles

 The next step is to define Teleport roles. They are created using the same
@@ -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

@@ -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

@@ -1,9 +1,12 @@
 <Tabs>
 <TabItem scope={["oss"]} label="Open Source">

- 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 @@
 <TabItem
  scope={["enterprise"]} label="Enterprise">

- 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=)
  ```
@@ -120,10 +120,26 @@ spec:

 Create or update this role using `tctl`:

+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ```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
 ```

+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```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
+```
+
+</ScopedBlock>
+
 Assign this role to a user in OIDC or SAML connector:

 <Tabs>
@@ -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):

+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ```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
+```

-#  The credentials have been written to kubeconfig
+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>

+```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
+```
+
+</ScopedBlock>
+
+Verify that these credentials have been written to kubeconfig:
+
+```code
 $ cat kubeconfig
 #   apiVersion: v1
 #   clusters:
@@ -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!)

 <Admonition type="note" title="Machine ID and TLS Routing">
 TLS Routing support will be added to Machine ID in [Teleport
@@ -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:

+<ScopedBlock scope={["oss", "enterprise"]}>
+
 ```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'
 ```

+</ScopedBlock>
+<ScopedBlock scope={["cloud"]}>
+
+```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'
+```
+
+</ScopedBlock>
+
 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)
@@ -740,53 +740,89 @@ creating new user roles or connecting Trusted Clusters.
 <Tabs>
 <TabItem scope={["enterprise", "oss"]} label="Self-Hosted">

-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=<output-path>`.
+### On a remote host with an identity file
+
+`tctl` can authenticate with a user-provided identity file. The Teleport Auth
+Service signs an identity file when a user runs `tctl auth sign` or
+`tsh login --out=<output-path>`, and the user can include the path to the
+identity file in the `--identity` flag when running `tctl` commands.
+  
+When using the `--identity` flag, the user must provide the `--auth-server` flag
+with the address of an Auth Service or Proxy Service so `tctl` knows which
+cluster to authenticate to.
+  
+### On the same host as the Teleport Auth Service
+
+If there is a Teleport configuration file on the host where `tctl` is run,
+`tctl` attempts to authenticate to the Auth Service named in the configuration
+file using an identity stored in its local backend.
+
+`tctl` only authenticates using this method if an identity file is not provided.

 <Admonition type="note">

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

 </Admonition>

-The `TELEPORT_CONFIG_FILE` environment variable indicates where the Teleport
-configuration file is.
+### On a remote host after running `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,
+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`.

 </TabItem>
 <TabItem scope={["cloud"]} label="Teleport Cloud">

-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

-The `TELEPORT_CONFIG_FILE` environment variable indicates where the Teleport
-configuration file is.
+`tctl` can authenticate with a user-provided identity file. The Teleport Auth
+Service signs an identity file when a user runs `tctl auth sign` or
+`tsh login --out=<output-path>`, and the user can include the path to the
+identity file in the `--identity` flag when running `tctl` commands.
+  
+When using the `--identity` flag, the user must alo provide the `--auth-server`
+flag with the address of an Auth Service or Proxy Service so `tctl` knows which
+cluster to authenticate to.

-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,
+### 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`.

 </TabItem>