{"id":15148398,"url":"https://github.com/anudeepnd/pihole-unbound","last_synced_at":"2025-04-09T16:07:14.004Z","repository":{"id":41062840,"uuid":"132985080","full_name":"anudeepND/pihole-unbound","owner":"anudeepND","description":"Guide to setup Unbound recursive DNS resolver with Pi-Hole. With additional configs for speed and security!! 🚀🔒","archived":false,"fork":false,"pushed_at":"2021-06-13T13:04:29.000Z","size":65,"stargazers_count":341,"open_issues_count":3,"forks_count":27,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-09T16:06:59.425Z","etag":null,"topics":["adblock","dns","dns-server","dnssec","pi-hole","privacy","raspberry-pi","recursive-server","unbound"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anudeepND.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-11T03:35:24.000Z","updated_at":"2025-04-01T23:13:09.000Z","dependencies_parsed_at":"2022-08-26T08:31:49.520Z","dependency_job_id":null,"html_url":"https://github.com/anudeepND/pihole-unbound","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anudeepND%2Fpihole-unbound","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anudeepND%2Fpihole-unbound/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anudeepND%2Fpihole-unbound/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anudeepND%2Fpihole-unbound/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anudeepND","download_url":"https://codeload.github.com/anudeepND/pihole-unbound/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065286,"owners_count":21041871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adblock","dns","dns-server","dnssec","pi-hole","privacy","raspberry-pi","recursive-server","unbound"],"created_at":"2024-09-26T13:03:30.518Z","updated_at":"2025-04-09T16:07:13.979Z","avatar_url":"https://github.com/anudeepND.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Set up Pi-hole as truly self-contained DNS resolver.\n### What is unbound?\n[Unbound](https://www.nlnetlabs.nl/projects/unbound/about/) is a validating, recursive, caching DNS resolver developed by NLnet Labs, VeriSign Inc., Nominet, and Kirei.\n\n### Setting up Pi-hole as a recursive DNS server solution\nInstall the Unbound recursive DNS resolver:\n```\nsudo apt install unbound\n```\nFor recursively querying a host that is not cached as an address, the resolver needs to start at the top of the server tree and query the root servers, to know where to go for the top level domain for the address being queried. Unbound comes with default builtin hints. Remember to update this file every 6 months.\n```\nwget -O root.hints https://www.internic.net/domain/named.root\nsudo mv root.hints /var/lib/unbound/\n```\n\n### Configure `unbound`\n\nEdit the config file by  `sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf`:\nAnd add the folowing contents:\n\n```yaml\nserver:\n\n    # The  verbosity  number, level 0 means no verbosity, only errors.\n    # Level 1 gives operational information. Level  2  gives  detailed\n    # operational  information. Level 3 gives query level information,\n    # output per query.  Level 4 gives  algorithm  level  information.\n    # Level 5 logs client identification for cache misses.  Default is\n    # level 1.\n    verbosity: 0\n    \n    interface: 127.0.0.1\n    port: 5335\n    do-ip4: yes\n    do-udp: yes\n    do-tcp: yes\n    \n    # May be set to yes if you have IPv6 connectivity\n    do-ip6: no\n\n    # You want to leave this to no unless you have *native* IPv6. With 6to4 and\n    # Terredo tunnels your web browser should favor IPv4 for the same reasons\n    prefer-ip6: no\n    \n    # Use this only when you downloaded the list of primary root servers!\n    # Read  the  root  hints from this file. Make sure to \n    # update root.hints evry 5-6 months.\n    root-hints: \"/var/lib/unbound/root.hints\"\n    \n    # Trust glue only if it is within the servers authority\n    harden-glue: yes\n    \n    # Ignore very large queries.\n    harden-large-queries: yes\n    \n    # Require DNSSEC data for trust-anchored zones, if such data is absent, the zone becomes BOGUS\n    # If you want to disable DNSSEC, set harden-dnssec stripped: no\n    harden-dnssec-stripped: yes\n    \n    # Number of bytes size to advertise as the EDNS reassembly buffer\n    # size. This is the value put into  datagrams over UDP towards\n    # peers. The actual buffer size is determined by msg-buffer-size\n    # (both for TCP and UDP).\n    edns-buffer-size: 1232\n    \n    # Rotates RRSet order in response (the pseudo-random \n    # number is taken from Ensure privacy of local IP \n    # ranges the query ID, for speed and thread safety).  \n    # private-address: 192.168.0.0/16\n    rrset-roundrobin: yes\n    \n    # Time to live minimum for RRsets and messages in the cache. If the minimum\n    # kicks in, the data is cached for longer than the domain owner intended,\n    # and thus less queries are made to look up the data. Zero makes sure the\n    # data in the cache is as the domain owner intended, higher values,\n    # especially more than an hour or so, can lead to trouble as the data in\n    # the cache does not match up with the actual data anymore\n    cache-min-ttl: 300\n    cache-max-ttl: 86400\n    \n    # Have unbound attempt to serve old responses from cache with a TTL of 0 in\n    # the response without waiting for the actual resolution to finish. The\n    # actual resolution answer ends up in the cache later on. \n    serve-expired: yes\n    \n    # Harden against algorithm downgrade when multiple algorithms are\n    # advertised in the DS record.\n    harden-algo-downgrade: yes\n    \n    # Ignore very small EDNS buffer sizes from queries.\n    harden-short-bufsize: yes\n    \n    # Refuse id.server and hostname.bind queries\n    hide-identity: yes\n    \n    # Report this identity rather than the hostname of the server.\n    identity: \"Server\"\n    \n    # Refuse version.server and version.bind queries\n    hide-version: yes\n    \n    # Prevent the unbound server from forking into the background as a daemon\n    do-daemonize: no\n    \n    # Number  of  bytes size of the aggressive negative cache.\n    neg-cache-size: 4m\n    \n    # Send minimum amount of information to upstream servers to enhance privacy\n    qname-minimisation: yes\n    \n    # Deny queries of type ANY with an empty response.\n    # Works only on version 1.8 and above\n    deny-any: yes\n\n    # Do no insert authority/additional sections into response messages when\n    # those sections are not required. This reduces response size\n    # significantly, and may avoid TCP fallback for some responses. This may\n    # cause a slight speedup\n    minimal-responses: yes\n    \n    # Perform prefetching of close to expired message cache entries\n    # This only applies to domains that have been frequently queried\n    # This flag updates the cached domains\n    prefetch: yes\n    \n    # Fetch the DNSKEYs earlier in the validation process, when a DS record is\n    # encountered. This lowers the latency of requests at the expense of little\n    # more CPU usage.\n    prefetch-key: yes\n    \n    # One thread should be sufficient, can be increased on beefy machines. In reality for \n    # most users running on small networks or on a single machine, it should be unnecessary\n    # to seek performance enhancement by increasing num-threads above 1.\n    num-threads: 1\n\n    # more cache memory. rrset-cache-size should twice what msg-cache-size is.\n    msg-cache-size: 50m\n    rrset-cache-size: 100m\n   \n    # Faster UDP with multithreading (only on Linux).\n    so-reuseport: yes\n    \n    # Ensure kernel buffer is large enough to not lose messages in traffix spikes\n    so-rcvbuf: 4m\n    so-sndbuf: 4m\n    \n    # Set the total number of unwanted replies to keep track of in every thread.\n    # When it reaches the threshold, a defensive action of clearing the rrset\n    # and message caches is taken, hopefully flushing away any poison.\n    # Unbound suggests a value of 10 million.\n    unwanted-reply-threshold: 100000\n    \n    # Minimize logs\n    # Do not print one line per query to the log\n    log-queries: no\n    # Do not print one line per reply to the log\n    log-replies: no\n    # Do not print log lines that say why queries return SERVFAIL to clients\n    log-servfail: no\n    # Do not print log lines to inform about local zone actions\n    log-local-actions: no\n    # Do not print log lines that say why queries return SERVFAIL to clients\n    logfile: /dev/null\n    \n    # Ensure privacy of local IP ranges\n    private-address: 192.168.0.0/16\n    private-address: 169.254.0.0/16\n    private-address: 172.16.0.0/12\n    private-address: 10.0.0.0/8\n    private-address: fd00::/8\n    private-address: fe80::/10\n```\n### Check unbound config file for errors\nThis is optional. Check the config file for errors by `unbound-checkconf  /etc/unbound/unbound.conf.d/pi-hole.conf` it should return `no errors in in /etc/unbound/unbound.conf.d/pi-hole.conf`. \n\nStart unbound service and check whether the domain is resolving. The first query will be slow but the subsequent queries will resolve under 1ms.\n```\nsudo service unbound start\ndig github.com @127.0.0.1 -p 5335\n```\n      \n### Test validation\nYou can test DNSSEC validation using\n```\ndig sigfail.verteiltesysteme.net @127.0.0.1 -p 5335\ndig sigok.verteiltesysteme.net @127.0.0.1 -p 5335\n```\nThe first command should give a status report of `SERVFAIL` and no IP address.\nThe second should give `NOERROR` plus an IP address.\n\n### Configure Pi-hole\nConfigure Pi-hole to use unbound as your recursive DNS server:\n\n![screenshot at 2018-04-18](https://i.imgur.com/M0Yh8dw.png)\n\nClick save.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanudeepnd%2Fpihole-unbound","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanudeepnd%2Fpihole-unbound","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanudeepnd%2Fpihole-unbound/lists"}