diff --git a/NextDNS-Mode.md b/NextDNS-Mode.md index d9c0742..d3f5b86 100644 --- a/NextDNS-Mode.md +++ b/NextDNS-Mode.md @@ -172,4 +172,74 @@ Once you crafted your perfect config, simply run: `ctrld restart` in order for c [2.7.0-RELEASE][root@pfSense.home.arpa]/root: ``` +## DNS Steering Rules +Much like in the native app, you can steer DNS queries to different NextDNS Profiles based on: +- hostnames +- MAC addresses +- IP networks + +This is accomplished using [policies](https://github.com/Control-D-Inc/ctrld/blob/main/docs/config.md#policy). Let's take a look at an example config file. Before you panic, it's simpler (and more powerful) than it looks. + +``` +[listener] + [listener.0] + ip = '0.0.0.0' + port = 53 + + [listener.0.policy] + name = 'My Policy' + networks = [ + {'network.0' = ['upstream.0']}, + {'network.1' = ['upstream.1']} + ] + + rules = [ + { '*.cool.domain' = ['upstream.1']}, + { '*.in-addr.arpa' = ['upstream.1']} + ] + + macs = [ + {"14:54:4a:8e:08:2d" = ["upstream.1"]} + ] + +[network] + [network.0] + name = 'Main Subnets' + cidrs = ['10.0.0.0/24', '10.0.1.0/24'] + + [network.1] + name = 'Secret Subnet' + cidrs = ['10.0.99.0/24'] + +[upstream] + [upstream.0] + name = 'My NextDNS Resolver' + type = 'doh3' + endpoint = 'https://dns.nextdns.io/qwerty' + timeout = 5000 + + [upstream.1] + name = 'My Fancy Control D Resolver' + type = 'doh3' + endpoint = 'https://dns.controld.com/abcd1234' + timeout = 5000 + +``` + +Not all params are needed, and shown for illustrative purposes only. Let's go over the config section by section. +1. In the `[listener]` block we define our.... listener with an IP + port. +2. In the `[listener.0.policy]` block we define the policy of how DNS traffic should be routed, let's skip that over for a second. +3. In the `[network]` block we define our subnets if you want to leverage source IP based routing. If you do not, don't define any. +4. In the `[upstream]` block we define our DNS upstreams where DNS traffic should be sent. You should have at least one of these, but here we have 2. +5. Coming back to the `[listener.0.policy]` block. It strings together the defined `networks` and `upstreams`, as well as new concepts like `rules` and `macs` and defines which upstream should be used if there is a match. +6. The matching order is: rules => macs => networks + +So for example: +- A DNS query from `10.0.0.5` would be sent to `upstream.0`, while a query from `10.0.99.123` would be sent to `upstream.1` +- A DNS query for `my-host.cool.domain` from any subnet would be sent to `upstream.1` (since host rules match first) +- A DNS query from a device with MAC address `14:54:4a:8e:08:2d` from any subnet would be sent to `upstream.1` (since MAC rules match 2nd). +- All PTR queries would be sent to `upstream.1` + +You can find more [example configs](https://github.com/Control-D-Inc/ctrld/wiki/Example-Configurations) for different use cases in the Wiki. + That's all there is to it. If you spot any issues with this guide, let us know. \ No newline at end of file