Correct how Unique Peer Hostnames matches names (#1054)

* docs: correct how Unique Peer Hostnames matches names The DNS label used for collision matching is built from the part of the hostname before the first dot, so web.prod and web.staging collide. Ephemeral peers always get the IP-based suffix by default, and lose it when the setting is on. A peer that already carries a suffix keeps it until it is renamed away and back. * docs: say what a rejected registration does A registration with a hostname another peer already uses fails and no peer is created, for ephemeral peers as well. * docs: tighten the Unique Peer Hostnames wording A rejected peer can join again under any hostname no other peer uses, including its own once the holder is deleted. * docs: say where the Unique Peer Hostnames setting lives Account-wide, off by default, in the Clients tab of Settings. Adds a screenshot of the section. * docs: make the ephemeral-peer bullet hold on its own * docs: the toggle prevents duplicate DNS labels, not duplicate hostnames Existing labels are compared with their suffix, so a hostname that other peers only hold with a suffixed label can still register. * docs: the rename check is on the DNS label too * docs: word the rename suffix and toggle intro by DNS label * docs: DNS labels are always unique; the toggle changes the outcome of a taken label * docs: the toggle also drops the ephemeral default suffix The sentence on label uniqueness said the toggle only changes what happens when a label is taken; it also removes the suffix ephemeral peers get by default, as the ephemeral bullet says. * docs: say what the suffix keeps unique and what it hides The DNS name is what stays unique; the shared hostname is what the suffix hides. * docs: state that no new peer gets a suffix with the toggle on A free label is used as-is; a taken one fails the registration. * docs: remove repeated statements from Unique Peer Hostnames Each fact now appears once: the taken-label rule in the first bullet (with the --hostname remedy), the ephemeral bullet reduced to what it adds, and the uniqueness restatement dropped. * docs: state the toggle's limit in plain words * docs: one term for DNS names, and the toggle limit with existing peers The section switched between DNS name and DNS label; it now says DNS name throughout. The note that suffixed names do not block a new peer moves to the paragraph about existing peers. * docs: make Unique Peer Hostnames easier to follow Says which peer keeps the plain DNS name and that the suffix goes on the DNS name only, states the matching rule before the toggle rules, lists both ways to let a rejected machine join, and gives the delete and rename steps with concrete names. On the DNS overview, the collision sentence moves below the v0.11.0 note it was reading as. * docs: safer rejoin advice and the default ephemeral suffix on the DNS page A different hostname can still collide, so the rejoin step asks for a hostname whose DNS name is free; the DNS overview says the ephemeral suffix applies by default. * docs: state each toggle-on outcome on the DNS overview A taken DNS name is rejected, every other new peer, ephemeral peers included, registers with its plain name, and existing suffixes stay.
2026-10-25 05:59:05 +01:00 · 2026-10-22 10:06:46 +02:00
parent d350ca7634
commit 6e4dd27ea6
3 changed files with 16 additions and 9 deletions
@@ -18,12 +18,12 @@ 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.
 <Note>
 Available on both NetBird Cloud and self-hosted versions running v0.11.0 or later.
 </Note>
 By default, a peer that registers with a hostname whose DNS name another peer already has gets an IP-based suffix, such as `my-server-12-7.netbird.cloud`, and so does every ephemeral peer, even one whose DNS name no other peer has. With the `Reject Hostname Collisions` toggle on (Settings > Clients, under [Unique Peer Hostnames](/manage/settings/clients#unique-peer-hostnames)), a peer whose DNS name another peer already has is rejected, and every other new peer, ephemeral peers included, registers with its plain name. Peers that already have a suffix keep it.
 ## How NetBird Handles DNS
 NetBird gives you centralized control over DNS resolution for all peers in your network, solving common challenges with split-horizon DNS, private networks, and secure name resolution.
@@ -31,17 +31,24 @@ See [Lazy Connections](/manage/peers/lazy-connection) for how activation works,
 ## 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.
+Two machines in one account can register with the same hostname, for example similar VMs that a provisioning tool all named `laptop`. By default both register, and each gets its own DNS name: the peer that registers first gets `laptop.netbird.cloud`, and the second gets the last two octets of its NetBird IP added, so with the IP `100.64.12.7` it becomes `laptop-12-7.netbird.cloud`. The suffix goes on the DNS name only; both peers still show as `laptop` in the dashboard. If you rename a peer to `laptop` while another peer has `laptop.netbird.cloud`, the renamed peer also gets a suffix. By default, [ephemeral peers](/manage/peers/register-machines-using-setup-keys#ephemeral-peers) get the suffix even when no other peer uses their hostname.
-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:
+The suffix gives each peer its own DNS name, but it also hides that two machines share a hostname. If you want such a registration to fail loudly instead, enable the `Reject Hostname Collisions` toggle under `Unique Peer Hostnames` in the `Clients` tab of [Settings](https://app.netbird.io/settings). The setting applies to the whole account and is off by default.
- 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.
+<p>
- Renaming a peer in the dashboard or through the API to a name another peer already uses fails with the same error.
+    <img src="/docs-static/img/manage/settings/unique-peer-hostnames.png" alt="Unique Peer Hostnames section of the Clients settings tab, with the Reject Hostname Collisions toggle switched off" className="imagewrapper"/>
- Ephemeral peers are treated exactly like other peers.
+</p>
-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`.
+Whether the toggle is on or off, two hostnames collide when they produce the same DNS name. To build the DNS name, NetBird takes the part of the hostname before the first dot, lowercases it, and replaces each run of characters that are not valid in DNS with a single `-` (non-ASCII characters are first converted to punycode). So `Laptop` and `laptop` collide, so do `my_laptop` and `my-laptop`, and so do `web.prod` and `web.staging`, which both become `web`.
-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 <name>`.
+With the toggle on:
 - No new peer gets a suffix, ephemeral peers included. A peer whose DNS name is free registers with it; a peer whose DNS name another peer in the account already has fails to register, and no peer is created, so nothing appears in the peer list. The client reports `peer with hostname "laptop" is already registered`, stops retrying, and stays disconnected until someone runs `netbird up` on that machine again: either with a hostname whose DNS name is free (`netbird up --hostname <name>`), or after deleting the peer that holds the name.
 - Renaming a peer in the dashboard or through the API to a name whose DNS name another peer already has fails with the same error.
 Enabling the toggle does not touch existing peers: DNS names that already carry a suffix keep it, and a registered peer is not checked for collisions when it logs in again, even if it now reports a hostname whose DNS name another peer has; it keeps the DNS name it already had. The toggle only blocks DNS names that are already taken, so a peer that already has a suffixed name, such as `laptop-12-7`, doesn't block a new `laptop`.
 Deleting a peer frees its DNS name but does not change the others: if you delete the `laptop` that holds `laptop.netbird.cloud`, the other one keeps `laptop-12-7.netbird.cloud`. To give it the plain name, rename it to another name and then back to `laptop`; saving the same name does not change its DNS name.
 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.