Jump to content

Unbound: Difference between revisions

From Official NixOS Wiki
m Add intro
Resolving issues with example config
 
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Expansion}}
[https://www.nlnetlabs.nl/projects/unbound/about/ Unbound] is a DNS server. Quoting the official project page:
Unbound is a DNS server. Quoting the official project page:


Unbound is a validating, recursive, caching DNS resolver. It is designed to be fast and lean and incorporates modern features based on open standards.<ref>https://www.nlnetlabs.nl/projects/unbound/about/</ref>
Unbound is a validating, recursive, caching DNS resolver. It is designed to be fast and lean and incorporates modern features based on open standards.
 
== Minimal configuration. DNS resolver ==
 
In this case our DNS queries are not encrypted upstream because the internet root name servers do not support DNS-over-TLS (DoT) or DNS-over-HTTPS (DoH).


== Example configuration ==
<syntaxhighlight lang="nixos">
<syntaxhighlight lang="nixos">
services.unbound = {
services.unbound = {
    enable = true;
  enable = true;
    settings = {
  # next line is optional (RFC7816)
      server = {
  settings.server.qname-minimisation = true;
        # When only using Unbound as DNS, make sure to replace 127.0.0.1 with your ip address
};
        # When using Unbound in combination with pi-hole or Adguard, leave 127.0.0.1, and point Adguard to 127.0.0.1:PORT
</syntaxhighlight>
        interface = [ "127.0.0.1" ];
 
        port = 5335;
Test if it's working
        access-control = [ "127.0.0.1 allow" ];
 
        # Based on recommended settings in https://docs.pi-hole.net/guides/dns/unbound/#configure-unbound
<syntaxhighlight>
        harden-glue = true;
$ nslookup nixos.org localhost
        harden-dnssec-stripped = true;
$ systemctl status unbound.service
        use-caps-for-id = false;
$ cat /etc/unbound/unbound.conf
        prefetch = true;
</syntaxhighlight>
        edns-buffer-size = 1232;
 
If during the configuration our computer stops resolving DNS and we lose connectivity, we can manually set the line <code>nameserver 9.9.9.9</code> doing <code>sudo nano /etc/resolv.conf</code>. Now we can rebuild our system.


        # Custom settings
== DNS forwarder with blocklists ==
        hide-identity = true;
 
        hide-version = true;
In this configuration we are using DoT to reach Quad9 and Cloudflare public DNS resolvers, in addition, we are filtering the results with a list that blocks adds and improves privacy and security (as Pi-hole does).
      };
 
      forward-zone = [
<syntaxhighlight lang="nixos">
        # Example config with quad9
services.unbound = {
        {
  enable = true;
          name = ".";
 
          forward-addr = [
  settings.server = {
            "9.9.9.9#dns.quad9.net"
    # Our Unbound server IP
            "149.112.112.112#dns.quad9.net"
    interface = [ "192.168.1.2" ];
          ];
    # IPs allowed to query
          forward-tls-upstream = true;  # Protected DNS
    access-control = [ "192.168.1.0/24 allow" ];
        }
    # Enable RPZ
      ];
     module-config = "'respip validator iterator'";
     };
   };
   };
  settings.rpz = [{
    name = "hageziPro";
    url = "https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/rpz/pro.txt";
  }];
  settings.forward-zone = [{
    name = ".";
    forward-tls-upstream = true;
    forward-addr = [
      "9.9.9.9@853#dns.quad9.net"
      "149.112.112.112@853#dns.quad9.net"
      "1.1.1.1@853#cloudflare-dns.com"
      "1.0.0.1@853#cloudflare-dns.com"
    ];
  }];
};
</syntaxhighlight>
</syntaxhighlight>


== Further reading ==


 
* [https://www.nlnetlabs.nl/projects/unbound/about/ Official project page]
[[Category:Applications]]
* https://unbound.docs.nlnetlabs.nl/en/latest/
* [https://wiki.archlinux.org/title/Unbound ArchWiki page]
[[Category:Networking]]
[[Category:Networking]]
[[Category:Server]]
[[Category:Server]]
[[Category:DNS]]

Latest revision as of 03:50, 30 March 2026

Unbound is a DNS server. Quoting the official project page:

Unbound is a validating, recursive, caching DNS resolver. It is designed to be fast and lean and incorporates modern features based on open standards.

Minimal configuration. DNS resolver

In this case our DNS queries are not encrypted upstream because the internet root name servers do not support DNS-over-TLS (DoT) or DNS-over-HTTPS (DoH).

services.unbound = {
  enable = true;
  # next line is optional (RFC7816)
  settings.server.qname-minimisation = true;
};

Test if it's working

$ nslookup nixos.org localhost
$ systemctl status unbound.service
$ cat /etc/unbound/unbound.conf

If during the configuration our computer stops resolving DNS and we lose connectivity, we can manually set the line nameserver 9.9.9.9 doing sudo nano /etc/resolv.conf. Now we can rebuild our system.

DNS forwarder with blocklists

In this configuration we are using DoT to reach Quad9 and Cloudflare public DNS resolvers, in addition, we are filtering the results with a list that blocks adds and improves privacy and security (as Pi-hole does).

services.unbound = {
  enable = true;

  settings.server = {
    # Our Unbound server IP
    interface = [ "192.168.1.2" ];
    # IPs allowed to query
    access-control = [ "192.168.1.0/24 allow" ];
    # Enable RPZ
    module-config = "'respip validator iterator'";
  };

  settings.rpz = [{
    name = "hageziPro";
    url = "https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/rpz/pro.txt";
  }];

  settings.forward-zone = [{
    name = ".";
    forward-tls-upstream = true;
    forward-addr = [
      "9.9.9.9@853#dns.quad9.net"
      "149.112.112.112@853#dns.quad9.net"
      "1.1.1.1@853#cloudflare-dns.com"
      "1.0.0.1@853#cloudflare-dns.com"
    ];
  }];
};

Further reading