From 96914b5a31644a47d4f5183035f5cf9947df10d9 Mon Sep 17 00:00:00 2001 From: Zac Bergquist Date: Thu, 2 Jan 2025 14:53:57 -0700 Subject: [PATCH] docs: add caveat about changing an agentless node's hostname (#50620) Changing the hostname of a node resource will update in the web UI very quickly, but attempting to connect to the resource using it's new hostname will fail if the new hostname is not present in the node's host certificate. Closes #42315 --- .../openssh/openssh-agentless.mdx | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/pages/enroll-resources/server-access/openssh/openssh-agentless.mdx b/docs/pages/enroll-resources/server-access/openssh/openssh-agentless.mdx index 76c9ecbd8c987..f87f4bd76536f 100644 --- a/docs/pages/enroll-resources/server-access/openssh/openssh-agentless.mdx +++ b/docs/pages/enroll-resources/server-access/openssh/openssh-agentless.mdx @@ -69,7 +69,7 @@ In this setup, the Teleport SSH Service performs RBAC checks as well as audits a configured. This must be done *before* your Teleport cluster is upgraded to Teleport 14. If you are having issues registering OpenSSH nodes or need to upgrade your - Teleport cluster to Teleport 14 before registering all of your OpenSSH nodes, you can + Teleport cluster to Teleport 14 before registering all of your OpenSSH nodes, you can pass the `TELEPORT_UNSTABLE_UNLISTED_AGENT_DIALING` environment variable to your Proxy Service and set it to `yes`. This will allow connections to unregistered OpenSSH nodes but will be removed in Teleport v15. @@ -104,10 +104,19 @@ Change the command-line options to assign the following values: - Set to the address and port of your Teleport Proxy Service. - Set to the join token value. -Check that your new node is listed with `tsh ls` or in the Web UI. You can edit the -hostname and labels with `tctl edit nodes/`. If the hostname isn't unique, get the UUID -from `tctl nodes ls -v` and edit with `tctl edit nodes/`. After you've confirmed the node -was registered successfully you can delete the copied `teleport` binary. +Check that your new node is listed with `tsh ls` or in the Web UI. + +You can edit the node with `tctl edit nodes/` or +`tctl edit nodes/`. The node's UUID can be found in the output of +`tctl nodes ls -v`. Be careful when changing the node's hostname, as the +hostname is a principal embedded in the host certificate that was generated +with `teleport join openssh`. If you want to modify the node's hostname, +you should either change the hostname of the instance and re-run +`teleport join openssh`, or manually issue a new host certificate with +`tctl auth sign --format=openssh`. + +After you've confirmed the node was registered successfully you can delete the +copied `teleport` binary. ## Step 2/3. Generate an SSH client configuration @@ -327,7 +336,7 @@ host's SSH port.
-You can log in to a host in a trusted leaf cluster by placing the name of +You can log in to a host in a trusted leaf cluster by placing the name of the leaf cluster between the name of the node and the name of the root cluster: ```code