docs: task class: improve_docs — add an faq entry to node-identities.md (#22565)
* docs: update docs/netdata-how-to-rename-a-node * docs: Execution completed * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com> Co-authored-by: Fotis Voutsas <fotis@netdata.cloud> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
nedi-app[bot] committed
May 27, 2026 at 13:48 UTC
ee019fdaff3bc24de2668023375f64e47a252c0a
1 file changed
+33
docs/learn/node-identities.md
+33
@@ -293,6 +293,39 @@ Changes apply immediately. Ephemerality is stored as a host label and propagates
293
294
</details>
295
296
+<details>
297
+<summary>How do I rename a node?</summary>
298
+
299
+A node's display name is determined by the `hostname` setting in `netdata.conf` under the `[global]` section. To rename a node, edit `netdata.conf` and set:
300
+
301
+```ini
302
+[global]
303
+ hostname = my-new-node-name
304
+```
305
+
306
+Use the [`edit-config` script](/docs/netdata-agent/configuration/README.md#edit-configuration-files) to safely edit configuration files, then [restart Netdata](/docs/netdata-agent/start-stop-restart.md).
307
+
308
+:::note
309
+
310
+Changing the hostname does **not** change the Machine GUID, Node ID, or Claimed ID. The node remains the same entity in Netdata Cloud and on Parent nodes. Historical metrics are preserved because they are keyed by Machine GUID, not hostname.
311
+
312
+:::
313
+
314
+:::warning
315
+
316
+**Do not use `NETDATA_HOSTNAME` as an environment variable to set the hostname.**
317
+
318
+`NETDATA_HOSTNAME` is an output variable set by the Netdata daemon at runtime for use by plugins and scripts — it is not an input configuration. To override a node's name within Netdata, use the `hostname` setting in `netdata.conf`. If `hostname` is not set, Netdata falls back to the system/container hostname.
319
+
320
+:::
321
+
322
+The updated hostname propagates to Parent nodes and Netdata Cloud on the next connection.
323
+
324
+For virtual nodes, see [Does renaming a virtual node change its identity?](#does-renaming-a-virtual-node-change-its-identity).
325
+
326
+</details>
327
+
328
+<a id="does-renaming-a-virtual-node-change-its-identity"></a>
329
<details>
330
<summary>Does renaming a virtual node change its identity?</summary>
331