From b206715a1920790b9a6cdcb8a9df92334a11a59b Mon Sep 17 00:00:00 2001 From: Paul Gottschling <paul.gottschling@goteleport.com> Date: Fri, 6 May 2022 17:18:11 -0400 Subject: [PATCH 1/2] Make the Adding Nodes guide more usable See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide. --- docs/pages/setup/admin/adding-nodes.mdx | 141 ++++++++++++------------ 1 file changed, 73 insertions(+), 68 deletions(-) diff --git a/docs/pages/setup/admin/adding-nodes.mdx b/docs/pages/setup/admin/adding-nodes.mdx index 36078da99a633..3651a56a6377d 100644 --- a/docs/pages/setup/admin/adding-nodes.mdx +++ b/docs/pages/setup/admin/adding-nodes.mdx @@ -1,5 +1,5 @@ --- -title: Adding Nodes to the Cluster +title: Adding Nodes to your Cluster description: How to add Nodes to your Teleport cluster --- @@ -9,7 +9,7 @@ This guide explains how to add Teleport Nodes to your cluster. (!docs/pages/includes/edition-prereqs-tabs.mdx!) -- A Linux server that you will use to host your Teleport Node +- A Linux server that you will use to host your Teleport Node. (!docs/pages/includes/tctl.mdx!) @@ -57,8 +57,9 @@ by executing [`tctl auth rotate`](../reference/cli.mdx#tctl-auth-rotate). </Notice> -Retrieve the CA pin of the Auth Service <ScopedBlock scope="cloud"> by running the following -command on your local machine</ScopedBlock>: +On you local machine, retrieve the CA pin of the Auth Service <ScopedBlock +scope="cloud"> by running the following command on your local +machine</ScopedBlock>: ```code $ export CA_PIN=$(tctl status | awk '/CA pin/{print $3}') @@ -77,15 +78,14 @@ Once a Node joins, it receives a host certificate signed by the cluster's Auth Service. To receive a host certificate upon joining a cluster, a new Teleport host must present an **invite token**. -An invite token also defines which role a new host can assume within a cluster: -`auth`, `proxy`, `node`, `app`, `kube`, or `db`. +An invite token also defines which role a new host can assume within a cluster +(e.g., `auth`, `proxy`, `node`, or `kube`). Administrators can generate tokens as they are needed. A token can be used multiple times until its time to live (TTL) expires. -Use the `tctl` tool <ScopedBlock scope="cloud">on your local -machine</ScopedBlock> to generate a new token. In the following example, a new -token is created with a TTL of five minutes: +On your local machine, use the `tctl` tool to generate a new token. In the +following example, a new token is created with a TTL of five minutes: ```code # Generate a short-lived invite token for a new node: @@ -98,18 +98,20 @@ $ tctl tokens ls # Token Type Expiry Time # ------------------------ ----------- --------------- # (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC - -# ... or revoke an invite token before it's used: -$ tctl tokens rm (=presets.tokens.first=) ``` -If you want to provide your own token, you can do so using the `--token` flag: +<Details title="Tokens with known values"> + +Rather than automatically generating a token, you can create one with a known +value by using the `--token` flag: ```code $ tctl nodes add --ttl=5m --roles=node,proxy --token=secret-value # The invite token: secret-value ``` +</Details> + <Details scope={["oss","enterprise"]} title="An insecure alternative: static tokens" scopeOnly={true} opened> <Admonition type="warning"> Use short-lived tokens instead of long-lived static tokens. @@ -134,79 +136,56 @@ auth_service: ### Start your Node with the invite token and CA pin -<Tabs> -<TabItem scope={["oss", "enterprise"]} scopeOnly={true} label="Self Hosted"> - -Execute one of the following commands on a new Node to add it to a cluster. -Supply the invite token and CA pin you retrieved earlier: +Execute the following commands on your local machine, then copy the output. ```code -$ sudo teleport start \ - --roles=node \ - --token=(=presets.tokens.first=) \ - --ca-pin=(=presets.ca_pin=) \ - --auth-server=10.12.0.6:3025 +$ echo "export CA_PIN=${CA_PIN?}" +$ echo "export INVITE_TOKEN=${INVITE_TOKEN?}" ``` -</TabItem> -<TabItem scope={["cloud"]} scopeOnly={true} label="Teleport Cloud"> -Execute the following command on a new Node to add it to a cluster. Replace -`mytenant.teleport.sh` with the domain name of your Teleport Cloud tenant. -Supply the invite token and CA pin you retrieved earlier: +Paste the output into a terminal on the host where you will run your Node so you +can use the `CA_PIN` and `INVITE_TOKEN` variables to start Teleport. + +<ScopedBlock scope={["oss", "enterprise"]}> + +Still on the host where you will run your Node, assign the address of your Auth +Service to an environment variable, including the domain name (or IP address) +and port: ```code -$ sudo teleport start \ - --roles=node \ - --token=(=presets.tokens.first=) \ - --ca-pin=(=presets.ca_pin=) \ - --auth-server=https://mytenant.teleport.sh:443 +$ export ADDR=teleport.example.com:3025 ``` -</TabItem> -</Tabs> +</ScopedBlock> +<ScopedBlock scope={["cloud"]}> -As new Nodes come online, they start sending ping requests every few seconds to -the Auth Service. This allows users to explore cluster membership and size: +Still on the host where you will run your Node, assign the address of your +Teleport Cloud tenant to an environment variable, including the domain name (or +IP address) and port `443`: ```code -$ tctl nodes ls - -Node Name Node ID Address Labels ---------- ------- ------- ------ -turing d52527f9-b260-41d0-bb5a-e23b0cfe0f8f 10.1.0.5:3022 distro:ubuntu -dijkstra c9s93fd9-3333-91d3-9999-c9s93fd98f43 10.1.0.6:3022 distro:debian +$ export ADDR=mytenant.teleport.sh:443 ``` -{/* TODO: This lengthy Details box should be a subsection. Using the Details box -as a workaround until we have a way to control the visibility of subsections -using the scope switcher */} +</ScopedBlock> -<ScopedBlock scope={["oss", "enterprise"]}> +<Details title="Alternative: Connect to the Proxy Service via Teleport Node Tunneling" scope={["oss", "enterprise"]} scopeOnly opened={false}> -### Teleport Node Tunneling +If you plan to use Teleport Node Tunneling, which we will explain below, set +`ADDR` to the domain name (or IP address) and `web_listen_addr` port of your +Teleport Proxy Service. -Teleport Node Tunneling lets you add a remote Node to an existing Teleport Cluster through a tunnel. -This can be useful for IoT applications or for managing a couple of servers in a different network. +Teleport Node Tunneling lets you add a remote Node to an existing Teleport +Cluster through a reverse tunnel. This is useful when the Auth Service is +inaccessible from the network where the Node is running, e.g., for IoT +applications. + +<Notice type="note"> -<Admonition type="note"> We recommend setting up a [Trusted Cluster](../admin/trustedclusters.mdx) if you have workloads split across different networks or clouds. -</Admonition> - -To connect a Node to your cluster via Node Tunneling, use `tctl` to create a -single-use token for a Node. Instead of supplying the IP of the Auth Service for -the `--auth-server` flag, you will use the URL of the Proxy Service. -In the example below, we've replaced the auth server IP with the Proxy's web -endpoint `teleport-proxy.example.com:3080`. - -```code -$ tctl tokens add --type=node | grep -oP '(?<=token:\s).*' > token.file - -# This will save the token to a file. -# Run this on the new node to join the cluster: -$ sudo teleport start --roles=node --token=/path/to/token.file --auth-server=teleport-proxy.example.com:3080 -``` +</Notice> Using the ports in Teleport's default configuration, the Node needs to be able to talk to ports `3080` and `3024` on the Proxy Service. Port `3080` is used to @@ -242,13 +221,39 @@ DEBU [PROC:1] Setup Proxy: Reverse tunnel proxy and web proxy listen on the s uses a round-robin or a similar balancing algorithm. Do not use sticky load balancing algorithms (a.k.a. "session affinity") with Teleport Proxy Service instances. </Admonition> -</ScopedBlock> +</Details> + +Execute the following command on your Node to add it to a cluster: + +```code +$ sudo teleport start \ + --roles=node \ + --token=${INVITE_TOKEN?} \ + --ca-pin=${CA_PIN?} \ + --auth-server=${ADDR?} +``` + +As new Nodes come online, they start sending ping requests every few seconds to +the Auth Service. This allows users to explore cluster membership and size. + +Run the following command on your local machine to see all of the Teleport Nodes +in your cluster: + +```code +$ tctl nodes ls + +Node Name Node ID Address Labels +--------- ------- ------- ------ +turing d52527f9-b260-41d0-bb5a-e23b0cfe0f8f 10.1.0.5:3022 distro:ubuntu +dijkstra c9s93fd9-3333-91d3-9999-c9s93fd98f43 10.1.0.6:3022 distro:debian +``` ## Step 3/3. Revoke an invitation Tokens used for joining Nodes to a cluster can be revoked before they are used. -Run the following command to create a token for a new Proxy Service. +Run the following command on your local machine to create a token for a new +Proxy Service. ```code $ tctl nodes add --ttl=5m --roles=proxy From efe04b2b566f2a3271555606541ea12df12da8c8 Mon Sep 17 00:00:00 2001 From: Paul Gottschling <paul.gottschling@goteleport.com> Date: Fri, 20 May 2022 15:00:15 -0400 Subject: [PATCH 2/2] Respond to PR feedback Also remove some erroneous command output --- docs/pages/setup/admin/adding-nodes.mdx | 27 +++++++++++++------------ 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/pages/setup/admin/adding-nodes.mdx b/docs/pages/setup/admin/adding-nodes.mdx index 3651a56a6377d..74428405b366e 100644 --- a/docs/pages/setup/admin/adding-nodes.mdx +++ b/docs/pages/setup/admin/adding-nodes.mdx @@ -63,11 +63,6 @@ machine</ScopedBlock>: ```code $ export CA_PIN=$(tctl status | awk '/CA pin/{print $3}') - -# Cluster staging.example.com -# User CA never updated -# Host CA never updated -# CA pin (=presets.ca_pin=) ``` ### Generate a token @@ -100,7 +95,7 @@ $ tctl tokens ls # (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC ``` -<Details title="Tokens with known values"> +<Details title="Provide your own token value"> Rather than automatically generating a token, you can create one with a known value by using the `--token` flag: @@ -110,6 +105,14 @@ $ tctl nodes add --ttl=5m --roles=node,proxy --token=secret-value # The invite token: secret-value ``` +The value of `--token` should be cryptographically secure. For example, you can +create an SHA256 hash to reduce the risk that a malicious actor will produce +a token with the same value as yours: + +```code +$ head -n 1 /dev/random | sha256sum +``` + </Details> <Details scope={["oss","enterprise"]} title="An insecure alternative: static tokens" scopeOnly={true} opened> @@ -136,16 +139,14 @@ auth_service: ### Start your Node with the invite token and CA pin -Execute the following commands on your local machine, then copy the output. +Execute the following commands on the host where you will run your Node so you +can use the `CA_PIN` and `INVITE_TOKEN` variables to start Teleport. ```code -$ echo "export CA_PIN=${CA_PIN?}" -$ echo "export INVITE_TOKEN=${INVITE_TOKEN?}" +$ export CA_PIN=$<CA pin> +$ export INVITE_TOKEN=<invite token> ``` -Paste the output into a terminal on the host where you will run your Node so you -can use the `CA_PIN` and `INVITE_TOKEN` variables to start Teleport. - <ScopedBlock scope={["oss", "enterprise"]}> Still on the host where you will run your Node, assign the address of your Auth @@ -253,7 +254,7 @@ dijkstra c9s93fd9-3333-91d3-9999-c9s93fd98f43 10.1.0.6:3022 distro Tokens used for joining Nodes to a cluster can be revoked before they are used. Run the following command on your local machine to create a token for a new -Proxy Service. +Proxy Service: ```code $ tctl nodes add --ttl=5m --roles=proxy