diff --git a/public/docs-static/img/manage/settings/unique-peer-hostnames.png b/public/docs-static/img/manage/settings/unique-peer-hostnames.png new file mode 100644 index 00000000..440905fa Binary files /dev/null and b/public/docs-static/img/manage/settings/unique-peer-hostnames.png differ diff --git a/src/pages/manage/dns/index.mdx b/src/pages/manage/dns/index.mdx index 598c577c..3e9fbd92 100644 --- a/src/pages/manage/dns/index.mdx +++ b/src/pages/manage/dns/index.mdx @@ -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. - Available on both NetBird Cloud and self-hosted versions running v0.11.0 or later. +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. diff --git a/src/pages/manage/settings/clients.mdx b/src/pages/manage/settings/clients.mdx index 938c2b76..ff09f094 100644 --- a/src/pages/manage/settings/clients.mdx +++ b/src/pages/manage/settings/clients.mdx @@ -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. -- 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. +

+ Unique Peer Hostnames section of the Clients settings tab, with the Reject Hostname Collisions toggle switched off +

-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 `. +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 `), 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.