Skip to content

Commit 195c50a

Browse files
zmb3github-actions
authored and
github-actions
committed
docs: add caveat about changing an agentless node's hostname
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
1 parent b3f3f6b commit 195c50a

File tree

1 file changed

+15
-6
lines changed

1 file changed

+15
-6
lines changed

docs/pages/enroll-resources/server-access/openssh/openssh-agentless.mdx

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ In this setup, the Teleport SSH Service performs RBAC checks as well as audits a
6969
configured. This must be done *before* your Teleport cluster is upgraded to Teleport 14.
7070

7171
If you are having issues registering OpenSSH nodes or need to upgrade your
72-
Teleport cluster to Teleport 14 before registering all of your OpenSSH nodes, you can
72+
Teleport cluster to Teleport 14 before registering all of your OpenSSH nodes, you can
7373
pass the `TELEPORT_UNSTABLE_UNLISTED_AGENT_DIALING` environment variable to your
7474
Proxy Service and set it to `yes`. This will allow connections to unregistered
7575
OpenSSH nodes but will be removed in Teleport v15.
@@ -104,10 +104,19 @@ Change the command-line options to assign the following values:
104104
- <Var name="teleport.example.com:443" /> Set to the address and port of your Teleport Proxy Service.
105105
- <Var name="(=presets.tokens.first=)" /> Set to the join token value.
106106

107-
Check that your new node is listed with `tsh ls` or in the Web UI. You can edit the
108-
hostname and labels with `tctl edit nodes/<hostname>`. If the hostname isn't unique, get the UUID
109-
from `tctl nodes ls -v` and edit with `tctl edit nodes/<uuid>`. After you've confirmed the node
110-
was registered successfully you can delete the copied `teleport` binary.
107+
Check that your new node is listed with `tsh ls` or in the Web UI.
108+
109+
You can edit the node with `tctl edit nodes/<hostname>` or
110+
`tctl edit nodes/<UUID>`. The node's UUID can be found in the output of
111+
`tctl nodes ls -v`. Be careful when changing the node's hostname, as the
112+
hostname is a principal embedded in the host certificate that was generated
113+
with `teleport join openssh`. If you want to modify the node's hostname,
114+
you should either change the hostname of the instance and re-run
115+
`teleport join openssh`, or manually issue a new host certificate with
116+
`tctl auth sign --format=openssh`.
117+
118+
After you've confirmed the node was registered successfully you can delete the
119+
copied `teleport` binary.
111120

112121
## Step 2/3. Generate an SSH client configuration
113122

@@ -327,7 +336,7 @@ host's SSH port.
327336

328337
<Details title="Using trusted clusters?">
329338

330-
You can log in to a host in a trusted leaf cluster by placing the name of
339+
You can log in to a host in a trusted leaf cluster by placing the name of
331340
the leaf cluster between the name of the node and the name of the root cluster:
332341

333342
```code

0 commit comments

Comments
 (0)