From 896d0054b3bcadb5dcd4ba63055f5641197bca78 Mon Sep 17 00:00:00 2001
From: Brian Joerger <bjoerger@gravitational.com>
Date: Thu, 20 May 2021 17:20:25 -0700
Subject: [PATCH] Update tctl docs to include new global flags and remote
 functionality. (#6771)

---
 docs/pages/cli-docs.mdx  | 22 +++++++++++++++++++---
 tool/tctl/common/tctl.go |  5 +++--
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/pages/cli-docs.mdx b/docs/pages/cli-docs.mdx
index 786eaf82b6a..5ba194385be 100644
--- a/docs/pages/cli-docs.mdx
+++ b/docs/pages/cli-docs.mdx
@@ -532,9 +532,7 @@ registered devices using [`tsh mfa ls`](cli-docs.mdx#tsh-mfa-ls).
 
 ## tctl
 
-`tctl` is an admin CLI tool used to administer a Teleport cluster. It connects
-to an Auth Server, meaning that it must be run on the same host with the role
-`auth` . If you run `tctl` on a non- `auth` node it will show an error.
+`tctl` is a CLI tool used to administer a Teleport cluster. 
 
 `tctl` allows a cluster administrator to manage all resources in a cluster
 including nodes, users, tokens, and certificates.
@@ -542,12 +540,30 @@ including nodes, users, tokens, and certificates.
 `tctl` can also be used to modify the dynamic configuration of the cluster, like
 creating new user roles or connecting trusted clusters.
 
+By default, `tctl` connects to a local Auth server, meaning it will fail if you 
+attempt to run `tctl` on a non-`auth` host.
+
+`tctl` can also connect to a remote Auth server 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>`.
+
+<Admonition type="note">
+  Note that when a `tctl` command is run locally on an Auth server, the audit logs will 
+  show that it was performed by the Auth server itself. To properly audit admin actions
+  at scale, it is important to limit direct ssh access to the Auth server with 
+  [Access Controls](./access-controls/introduction.mdx) and ensure that admins use `tctl` 
+  remotely with the `--identity` flag instead.
+</Admonition>
+
 ### tctl Global Flags
 
 | Name | Default Value(s) | Allowed Value(s) | Description |
 | - | - | - | - |
 | `-d, --debug` | none | none | Enable verbose logging to stderr |
 | `-c, --config` | `/etc/teleport.yaml` | **string** filepath | Path to a configuration file |
+| `--auth-server` | none | `host:port` | Attempts to connect to specific auth/proxy address(es) instead of local auth [127.0.0.1:3025] |
+| `-i, --identity` | none | **string** filepath | Path to an identity file. Must be provided to make remote connections to auth. An identity file can be exported with 'tctl auth sign' |
+| `--insecure` | none | none | When specifying a proxy address in --auth-server, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker |
 
 ### tctl  help
 
diff --git a/tool/tctl/common/tctl.go b/tool/tctl/common/tctl.go
index ba8fc815ff9..4e08b4ced8c 100644
--- a/tool/tctl/common/tctl.go
+++ b/tool/tctl/common/tctl.go
@@ -119,9 +119,10 @@ func Run(commands []CLICommand) {
 	app.Flag("config-string",
 		"Base64 encoded configuration string").Hidden().Envar(defaults.ConfigEnvar).StringVar(&ccf.ConfigString)
 	app.Flag("auth-server",
-		fmt.Sprintf("Address of the auth server or the proxy [%v]. Can be supplied multiple times", defaults.AuthConnectAddr().Addr)).
+		fmt.Sprintf("Attempts to connect to specific auth/proxy address(es) instead of local auth [%v]", defaults.AuthConnectAddr().Addr)).
 		StringsVar(&ccf.AuthServerAddr)
-	app.Flag("identity", "Path to the identity file exported with 'tctl auth sign'").
+	app.Flag("identity",
+		"Path to an identity file. Must be provided to make remote connections to auth. An identity file can be exported with 'tctl auth sign'").
 		Short('i').
 		StringVar(&ccf.IdentityFilePath)
 	app.Flag("insecure", "When specifying a proxy address in --auth-server, do not verify its TLS certificate. Danger: any data you send can be intercepted or modified by an attacker.").