Skip to content

Commit

Permalink
Update DNS docs
Browse files Browse the repository at this point in the history
  • Loading branch information
braginini committed Feb 2, 2024
1 parent 7e2ebe7 commit b992ea6
Show file tree
Hide file tree
Showing 8 changed files with 47 additions and 33 deletions.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
80 changes: 47 additions & 33 deletions src/pages/how-to/manage-dns-in-your-network.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@
</div>
<br/><br/>

You don't need to design a network or configure [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol)
With NetBird, you don't need to worry about designing your private network or configuring [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol)
as it is automatically done in a single place - the NetBird Management service.
NetBird assigns and automatically distributes IP addresses to your peers.
Once peers have IPs, they can communicate with one another and establish direct encrypted WireGuard® tunnels.
You can use these IPs to access the services running on the connected peers (e.g., SSH).
Once your peers have their IP addresses, they can communicate with each other, establish direct encrypted WireGuard® tunnels,
and access services running on connected peers, such as SSH.
Even though we trust our memory capacity, there is a limit to what we can remember,
especially when it comes to IP addresses like this one, 100.128.185.34.

Expand All @@ -21,61 +21,70 @@ Besides accessing machines by their domain names, you can configure NetBird to u
control what nameservers a specific [peer group](/how-to/manage-network-access#groups) should use, and set up split DNS.

<Note>
Nameservers feature is available in NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later.
Nameservers feature is available in NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later on both
cloud and self-hosted versions.
</Note>

## Concepts
## Core concepts
### Local resolver
To minimize the number of changes in your system, NetBird will spin up a local DNS resolver.

This local resolver will be responsible for queries to the domain names of peers registered in your network and forwarding queries to upstream nameservers you configure in the system.

#### Nameserver
Nameserver is an upstream DNS server for name resolution, if a query comes and is not a peer domain name, it will be resolved by one of the upstream servers. You can assign private and public IPs and custom ports. Remember that you might need a network route for private addresses to allow peers to connect to it.
#### Match domains
By default, when creating nameserver groups without match domains, implies that the nameservers will resolve all DNS queries. For some cases, you might want to deploy a split horizon configuration for private or specific domains, Match domains allow you to route queries of names, matching them to specific nameservers. This is useful when you have an internal DNS configuration that only internal servers can resolve.
To minimize system changes, NetBird runs a local embedded DNS resolver on each peer.
This resolver handles queries for domain names of registered peers in your network and forwards queries to upstream nameservers that you configure in the system.

### Nameserver
A nameserver is an upstream DNS server responsible for name resolution. If a query is not related to a peer domain name,
it will be resolved by one of the upstream servers. You can assign private and public IPs, as well as custom ports for your nameservers.
Ensure that network routes for private addresses are set up to allow peers to connect to them, when configuring private nameservers.

### Match domains
When creating nameserver groups without match domains, it implies that the nameservers will resolve all DNS queries.
For specific cases, you may want to deploy a split horizon configuration for private or specific domains.
Match domains allow you to route queries to specific nameservers, which is useful for internal DNS configurations
that only internal servers can resolve.
<Note>
Only MacOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with only match domains. For a better experience, we recommend setting at least a nameserver group without match domains to be applied to the `All` group.
Only MacOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with match domains.
For a better experience, we recommend setting at least one nameserver group without match domains to be applied to the `All` group.
</Note>
#### Mark match domains as search domains
Marking a match domain as search domains configures the peers to use only hostnames to perform FQDN queries. e.g. `ping host-a` instead of `ping host-a.netbird.cloud`.
Marking a match domain as a search domain configures peers to use only hostnames to perform FQDN queries, e.g., `ping host-a` instead of `ping host-a.netbird.cloud`.
<Note>
Marking a match domains as search domains feature is available in NetBird [v0.24.0](https://github.com/netbirdio/netbird/releases) or later.
Marking a match domains as a search domain feature is available in NetBird [v0.24.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
#### Distribution groups
Distribution defines that peers that belong to groups set in this field will receive the nameserver configuration.

### Distribution groups
Distribution groups define which peers will receive the nameserver configuration.
They are particularly useful when using private nameservers to link routing peers and clients of the private servers.
<Note>
When using private nameservers, you may use these groups to link routing peers and clients of the private servers.
</Note>

## Managing nameserver groups
A nameserver group defines up to 2 nameservers to resolve DNS to a set of peers in distribution groups.
A nameserver group defines up to 2 nameservers to resolve DNS to a set of peers in the distribution groups.

### Creating a nameserver group
Access the `DNS` tab and click the `Add Nameserver` button to create a new nameserver.
Access the `DNS` tab, the `Namservers` section and click `Add Nameserver`.
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-add-button.png" alt="high-level-dia" className="imagewrapper"/>
</p>
That will open a nameserver selection configuration screen where you can choose between using three predefined public
nameservers or using a custom setup.

#### Selecting predefined nameservers
### Selecting predefined nameservers
If you choose a predefined public nameserver option, you can select the following nameservers:
- [Google DNS servers](https://developers.google.com/speed/public-dns/docs/using)
- [Cloudflare DNS servers](https://one.one.one.one/dns/)
- [Quad9 DNS servers](https://www.quad9.net/)
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-selection-view-open.png" alt="high-level-dia" width="300" className="imagewrapper"/>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-selection-view-open.png" alt="high-level-dia" className="imagewrapper"/>
</p>

After selecting one of the three options, you need to assign a peer group for which this nameserver will be effective.
In the example below, we chose the "All" group:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-all-group.png" alt="high-level-dia" width="300" className="imagewrapper"/>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-all-group.png" alt="high-level-dia" className="imagewrapper"/>
</p>

#### Creating custom nameservers
You can also configure a custom nameserver by clicking the `Add custom` button. Now you can enter the details of your nameserver.
### Creating custom nameservers
You can also configure a custom nameserver by clicking `Add custom`. Now you can enter the details of your custom nameserver.

In the example below, we are creating a nameserver with the following information:

Expand All @@ -84,37 +93,42 @@ In the example below, we are creating a nameserver with the following informatio
- Add at least one nameserver: `192.168.0.32` with port `53`
- Distribution group: `Remote developers`
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-custom.png" alt="high-level-dia" width="300" className="imagewrapper"/>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-custom.png" alt="high-level-dia" className="imagewrapper"/>
</p>

### Creating a nameserver for specific domains
Sometimes we want to forward DNS queries to specific nameservers but only for particular domains that match a setting.
Sometimes one may want to forward DNS queries to specific nameservers but only for particular domains that match a setting.
Taking the example of custom nameservers above, you could select a match mode for only domains listed there.
Below you can see the same nameserver setup but only for the `berlinoffice.com` domain:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-resolver.png" alt="high-level-dia" width="300" className="imagewrapper"/>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-resolver.png" alt="high-level-dia" className="imagewrapper"/>
</p>

<Note>
Only MacOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with only match domains. For a better experience, we recommend setting at least a nameserver group without match domains to be applied to the `All` group.
</Note>

### Distributing the settings with groups
You can select as many distribution groups as you want for your nameserver setup. Keep in mind to link them to peers and, if required, to add access control rules when using private nameservers.
### Distributing DNS settings with groups
You can select as many distribution groups as you want for your nameserver setup.
Keep in mind to link them to peers and, if required, to add access control rules when using private nameservers.
### Adding remote private DNS servers
To add a private DNS server that is running behind routing peers, you need to create resources to ensure communication between your nameserver clients can communicate. In the Berlin office example from previous steps, we have a peer from the `Office network` that can route traffic to the `192.168.0.32` IP, so we need to ensure that a similar network route exists:
To add a private DNS server that is running behind routing peers, you need to create resources to ensure communication between your nameserver clients.
In the Berlin office example from previous steps, we have a peer from the `Office network` that can route traffic to the `192.168.0.32` IP,
so we need to ensure that a similar network route exists:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-route.png" alt="high-level-dia" className="imagewrapper"/>
</p>

Then we need to confirm that an access rule exists to connect `Remote developers` to `Office network` group:
Then we need to confirm that an access rule exists to connect `Remote developers` to `Office network` group allowing port `UDP 53`:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-rule.png" alt="high-level-dia" className="imagewrapper"/>
</p>

## Testing configuration
### Querying records
DNS configuration has evolved in the last few years, and each operating system might expose its nameserver configuration differently. Unfortunately, tools like `nslookup` or `dig` didn't get updated to match these OS configurations, and in many cases, they won't use the same servers as your browser to query domain names.
DNS configuration has evolved in the past few years, and each operating system might expose its nameserver configuration differently.
Unfortunately, tools like `nslookup` or `dig` didn't get updated to match these OS configurations, and in many cases,
they won't use the same servers as your browser to query domain names.

For these cases, we listed some tools to support your checks:
#### MacOS
Expand Down

0 comments on commit b992ea6

Please sign in to comment.