Edit tctl instructions to clarify remote login (#13078)

Backports #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.
gravitational · Jun 6, 2022 · 1856205 · 1856205
1 parent 71c5d8a
commit 1856205
Show file tree

Hide file tree

Showing 23 changed files with 297 additions and 77 deletions.
diff --git 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
@@ -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:

diff --git 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
@@ -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.

diff --git 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:
+
+<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.

diff --git 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)
 
-<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
 

diff --git 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
@@ -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
@@ -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!)
+
 <Admonition type="note" title="Note">
   Redis `7.0` and RESP3 (REdis Serialization Protocol) are currently not supported.
 </Admonition>

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

diff --git 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.
 
 <Details scope={["cloud", "oss"]} opened={true} scopeOnly={true} title="Compabitility Warning">

diff --git 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
@@ -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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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

Expand Down