From 0562a517ad099f97125924984ec3128082a2f937 Mon Sep 17 00:00:00 2001
From: Pascal Fischer <32096965+pascal-fischer@users.noreply.github.com>
Date: Fri, 16 Oct 2026 17:30:37 +0200
Subject: [PATCH] add docs for hostname collision setting (#1051)
---
src/pages/manage/dns/index.mdx | 2 ++
src/pages/manage/settings/clients.mdx | 20 +++++++++++++++++++-
2 files changed, 21 insertions(+), 1 deletion(-)
diff --git a/src/pages/manage/dns/index.mdx b/src/pages/manage/dns/index.mdx
index f822d5a9..598c577c 100644
--- a/src/pages/manage/dns/index.mdx
+++ b/src/pages/manage/dns/index.mdx
@@ -18,6 +18,8 @@ NetBird provides centralized DNS management to help your peers resolve domain na
Starting with [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird automatically assigns a domain name to each peer in a private `netbird.cloud` space. You can access machines using names like `my-server.netbird.cloud` instead of IP addresses.
+When two peers in an account share a hostname, the second one gets an IP-based suffix such as `my-server-12-7.netbird.cloud` by default. You can make such registrations fail instead with the [Unique Peer Hostnames](/manage/settings/clients#unique-peer-hostnames) setting.
+
Available on both NetBird Cloud and self-hosted versions running v0.11.0 or later.
diff --git a/src/pages/manage/settings/clients.mdx b/src/pages/manage/settings/clients.mdx
index ef70039d..938c2b76 100644
--- a/src/pages/manage/settings/clients.mdx
+++ b/src/pages/manage/settings/clients.mdx
@@ -1,5 +1,5 @@
export const description =
- 'Configure account-wide client behavior: automatic updates, lazy connections, and exposing services from the CLI.'
+ 'Configure account-wide client behavior: automatic updates, lazy connections, exposing services from the CLI, and unique peer hostnames.'
# Client Settings
@@ -29,6 +29,24 @@ Instead of maintaining always-on connections, NetBird can activate peer connecti
See [Lazy Connections](/manage/peers/lazy-connection) for how activation works, inactivity thresholds, and per-client overrides.
+## Unique Peer Hostnames
+
+Two machines in one account can register with the same hostname, for example similar VMs that a provisioning tool all named `laptop`. Every peer still needs its own DNS name, so by default NetBird keeps the registration and adds the last two octets of the peer's NetBird IP to the DNS label: a second `laptop` that gets the IP `100.64.12.7` becomes `laptop-12-7.netbird.cloud`. Renaming a peer to a name another peer already uses gets the same suffix.
+
+The suffix keeps every peer reachable, but it also hides the duplicate. If you want a registration with a duplicate hostname to fail loudly instead, enable the `Reject Hostname Collisions` toggle. With the toggle on:
+
+- A peer registering with a hostname that another peer in the account already uses is rejected. The client reports `peer with hostname "laptop" is already registered`, stops retrying, and stays disconnected until it logs in again with a different hostname.
+- Renaming a peer in the dashboard or through the API to a name another peer already uses fails with the same error.
+- Ephemeral peers are treated exactly like other peers.
+
+Collisions are matched on the DNS label, not the raw hostname. The label is the hostname lowercased with characters that are not valid in DNS replaced by `-`, so `Laptop` and `laptop` collide, and so do `my_laptop` and `my-laptop`.
+
+Enabling the toggle does not touch existing peers: labels that already carry a suffix keep it, and a peer logging in again under its own name is not a collision. Deleting a peer frees its name for the next registration. To let a rejected peer join, give the machine a unique hostname or start the client with one: `netbird up --hostname `.
+
+Keep the toggle off if your fleet registers machines with identical hostnames on purpose, such as autoscaled VMs or containers that join through a [setup key](/manage/peers/register-machines-using-setup-keys). The default suffix exists for that case, and with the toggle on every such machine after the first fails to join.
+
+This setting is available on NetBird Cloud and on self-hosted management servers running v0.81.0 or later. In the API it is the `peer_hostname_collision_rejected` field of the [account settings](/ipa/resources/accounts).
+
## Agent Network-focused view
Accounts using [Agent Network](/agent-network) see an additional `Agent Network focused view` toggle. When enabled, the dashboard shows only the Agent Network-related sections and hides parts that are not relevant for it, such as Networks, DNS, and Reverse Proxy. Disable it to bring back the full dashboard.