From f8b739cc76042f0be7e0c89794526a6bd7af6410 Mon Sep 17 00:00:00 2001 From: Brian Joerger Date: Thu, 6 May 2021 16:49:11 -0700 Subject: [PATCH 1/5] Update tctl docs to include new global flags. --- docs/pages/cli-docs.mdx | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/pages/cli-docs.mdx b/docs/pages/cli-docs.mdx index 786eaf82b6a16..f7fedd978b07d 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 an admin 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,28 @@ 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` node. + +However it can also connect to a remote auth server if an identity file and Auth/Proxy +server IP address are provided. + + + 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 close off direct access to the Auth server and ensure + that admins connect remotely using identity files instead. + + ### 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 | **string** IP | `tctl` attempts to connect to a specific auth/proxy address instead of local auth | +| `-i, --identity` | none | **string** filepath | Path to an identity file, must be provided to make remote connections to auth | +| `-i, --insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments | ### tctl help From ff857d7acc63be0ad5c1edec825913bc95b8eda9 Mon Sep 17 00:00:00 2001 From: Brian Joerger Date: Thu, 6 May 2021 19:55:10 -0700 Subject: [PATCH 2/5] Resolve comments. --- docs/pages/cli-docs.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/cli-docs.mdx b/docs/pages/cli-docs.mdx index f7fedd978b07d..822aaf3f1049f 100644 --- a/docs/pages/cli-docs.mdx +++ b/docs/pages/cli-docs.mdx @@ -543,12 +543,12 @@ 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` node. -However it can also connect to a remote auth server if an identity file and Auth/Proxy +However it can also connect to a remote Auth server if an identity file and Auth/Proxy server IP address are provided. 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 + show that it was performed by the Auth server itself. To properly audit admin actions at scale, it is important to close off direct access to the Auth server and ensure that admins connect remotely using identity files instead. @@ -561,7 +561,7 @@ server IP address are provided. | `-c, --config` | `/etc/teleport.yaml` | **string** filepath | Path to a configuration file | | `--auth-server` | none | **string** IP | `tctl` attempts to connect to a specific auth/proxy address instead of local auth | | `-i, --identity` | none | **string** filepath | Path to an identity file, must be provided to make remote connections to auth | -| `-i, --insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments | +| `--insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments | ### tctl help From a3c8b78fdca9ad92d783ccf9e44b49b4c7702bc6 Mon Sep 17 00:00:00 2001 From: Brian Joerger Date: Fri, 7 May 2021 11:17:01 -0700 Subject: [PATCH 3/5] Resolve comments. --- docs/pages/cli-docs.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/pages/cli-docs.mdx b/docs/pages/cli-docs.mdx index 822aaf3f1049f..358cadb3271a4 100644 --- a/docs/pages/cli-docs.mdx +++ b/docs/pages/cli-docs.mdx @@ -543,14 +543,15 @@ 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` node. -However it can also connect to a remote Auth server if an identity file and Auth/Proxy -server IP address are provided. +However `tctl` can also connect to a remote Auth server if the `--identity` and +`--auth-server` flags are used. 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 close off direct access to the Auth server and ensure - that admins connect remotely using identity files instead. + 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. ### tctl Global Flags @@ -559,7 +560,7 @@ server IP address are provided. | - | - | - | - | | `-d, --debug` | none | none | Enable verbose logging to stderr | | `-c, --config` | `/etc/teleport.yaml` | **string** filepath | Path to a configuration file | -| `--auth-server` | none | **string** IP | `tctl` attempts to connect to a specific auth/proxy address instead of local auth | +| `--auth-server` | none | `host:port` | `tctl` attempts to connect to a specific auth/proxy address instead of local auth | | `-i, --identity` | none | **string** filepath | Path to an identity file, must be provided to make remote connections to auth | | `--insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments | From 28afd880d90111791a5710fdea7164139b53415d Mon Sep 17 00:00:00 2001 From: Brian Joerger Date: Fri, 7 May 2021 13:05:10 -0700 Subject: [PATCH 4/5] Resolve comment. --- docs/pages/cli-docs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/cli-docs.mdx b/docs/pages/cli-docs.mdx index 358cadb3271a4..a78f2b298fa92 100644 --- a/docs/pages/cli-docs.mdx +++ b/docs/pages/cli-docs.mdx @@ -532,7 +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. +`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. From 69d364bc77f6700cc6b94e4283440d26f0fd2595 Mon Sep 17 00:00:00 2001 From: Brian Joerger Date: Fri, 14 May 2021 16:17:16 -0700 Subject: [PATCH 5/5] Resolve comments --- docs/pages/cli-docs.mdx | 13 +++++++------ tool/tctl/common/tctl.go | 5 +++-- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/pages/cli-docs.mdx b/docs/pages/cli-docs.mdx index a78f2b298fa92..5ba194385bea3 100644 --- a/docs/pages/cli-docs.mdx +++ b/docs/pages/cli-docs.mdx @@ -541,10 +541,11 @@ including nodes, users, tokens, and certificates. 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` node. +attempt to run `tctl` on a non-`auth` host. -However `tctl` can also connect to a remote Auth server if the `--identity` and -`--auth-server` flags are used. +`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=`. Note that when a `tctl` command is run locally on an Auth server, the audit logs will @@ -560,9 +561,9 @@ However `tctl` can also connect to a remote Auth server if the `--identity` and | - | - | - | - | | `-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` | `tctl` attempts to connect to a specific auth/proxy address instead of local auth | -| `-i, --identity` | none | **string** filepath | Path to an identity file, must be provided to make remote connections to auth | -| `--insecure` | none | none | Do not verify server's certificate and host name. Use only in test environments | +| `--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 ba8fc815ff9bf..4e08b4ced8c64 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.").