pi-hole / docs

The official Pi-hole documentation

Network-wide ad blocking via your own Linux hardware

The Pi-hole® is a DNS sinkhole that protects your devices from unwanted content without installing any client-side software.

• Easy-to-install: our dialogs walk you through the simple installation process in less than ten minutes
• Resolute: content is blocked in non-browser locations, such as ad-laden mobile apps and smart TVs
• Responsive: seamlessly speeds up the feel of everyday browsing by caching DNS queries
• Lightweight: runs smoothly with minimal hardware and software requirements
• Robust: a command-line interface that is quality assured for interoperability
• Insightful: a beautiful responsive Web Interface dashboard to view and control your Pi-hole
• Versatile: can optionally function as a DHCP server, ensuring all your devices are protected automatically
• Scalable: capable of handling hundreds of millions of queries when installed on server-grade hardware
• Modern: blocks ads over both IPv4 and IPv6
• Free: open source software that helps ensure you are the sole person in control of your privacy

---

One-Step Automated Install

Those who want to get started quickly and conveniently may install Pi-hole using the following command:

curl -sSL https://install.pi-hole.net | bash

Alternative Install Methods

Piping to bash is controversial, as it prevents you from reading code that is about to run on your system. Therefore, we provide these alternative installation methods which allow code review before installation:

Method 1: Clone our repository and run

git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole
cd "Pi-hole/automated install/"
sudo bash basic-install.sh

Method 2: Manually download the installer and run

wget -O basic-install.sh https://install.pi-hole.net
sudo bash basic-install.sh

Method 3: Using Docker to deploy Pi-hole

Please refer to the Pi-hole docker repo to use the Official Docker Images.

Post-install: Make your network take advantage of Pi-hole

Once the installer has been run, you will need to configure your router to have DHCP clients use Pi-hole as their DNS server. This router configuration will ensure that all devices connecting to your network will have content blocked without any further intervention.

If your router does not support setting the DNS server, you can use Pi-hole's built-in DHCP server; be sure to disable DHCP on your router first (if it has that feature available).

As a last resort, you can manually set each device to use Pi-hole as their DNS server.

---

Pi-hole is free but powered by your support

There are many reoccurring costs involved with maintaining free, open-source, and privacy-respecting software; expenses which our volunteer developers pitch in to cover out-of-pocket. This is just one example of how strongly we feel about our software and the importance of keeping it maintained.

Make no mistake: your support is absolutely vital to help keep us innovating!

Donations

Donating using our Sponsor Button is extremely helpful in offsetting a portion of our monthly expenses:

Alternative support

If you'd rather not donate (which is okay!), there are other ways you can help support us:

• GitHub Sponsors
• Patreon
• Hetzner Cloud affiliate link
• Digital Ocean affiliate link
• Stickermule earn a $10 credit after your first purchase
• Amazon US affiliate link
• Spreading the word about our software and how you have benefited from it

Contributing via GitHub

We welcome everyone to contribute to issue reports, suggest new features, and create pull requests.

If you have something to add - anything from a typo through to a whole new feature, we're happy to check it out! Just make sure to fill out our template when submitting your request; the questions it asks will help the volunteers quickly understand what you're aiming to achieve.

You'll find that the install script and the debug script have an abundance of comments, which will help you better understand how Pi-hole works. They're also a valuable resource to those who want to learn how to write scripts or code a program! We encourage anyone who likes to tinker to read through it and submit a pull request for us to review.

---

Getting in touch with us

While we are primarily reachable on our Discourse User Forum, we can also be found on various social media outlets.

Please be sure to check the FAQs before starting a new discussion, as we do not have the spare time to reply to every request for assistance.

• Frequently Asked Questions
• Feature Requests
• Reddit
• Twitter

---

Breakdown of Features

Faster-than-light Engine

FTLDNS is a lightweight, purpose-built daemon used to provide statistics needed for the Web Interface, and its API can be easily integrated into your own projects. As the name implies, FTLDNS does this all very quickly!

Some of the statistics you can integrate include:

• Total number of domains being blocked
• Total number of DNS queries today
• Total number of ads blocked today
• Percentage of ads blocked
• Unique domains
• Queries forwarded (to your chosen upstream DNS server)
• Queries cached
• Unique clients

Access the API via telnet, the Web (admin/api.php) and Command Line (pihole -c -j). You can find out more details over here.

The Command-Line Interface

The pihole command has all the functionality necessary to fully administer the Pi-hole, without the need for the Web Interface. It's fast, user-friendly, and auditable by anyone with an understanding of bash.

Some notable features include:

• Whitelisting, Blacklisting, and Regex
• Debugging utility
• Viewing the live log file
• Updating Ad Lists
• Querying Ad Lists for blocked domains
• Enabling and Disabling Pi-hole
• ... and many more!

You can read our Core Feature Breakdown for more information.

The Web Interface Dashboard

This optional dashboard allows you to view stats, change settings, and configure your Pi-hole. It's the power of the Command Line Interface, with none of the learning curve!

Some notable features include:

• Mobile-friendly interface
• Password protection
• Detailed graphs and doughnut charts
• Top lists of domains and clients
• A filterable and sortable query log
• Long Term Statistics to view data over user-defined time ranges
• The ability to easily manage and configure Pi-hole features
• ... and all the main features of the Command Line Interface!

There are several ways to access the dashboard:

1. http://pi.hole/admin/ (when using Pi-hole as your DNS server)
2. http://<IP_ADDRESS_OF_YOUR_PI_HOLE>/admin/

docs's Issues

Enable a few more Markdownlint rules

• MD0040: code blocks must have a language specified (when we don't want a lang, we can use text)
• MD0045: images must have an alt text

Docs - changed URL for Cloudflare

In the documentation about upstream providers, there is a link to More information on Cloudflare DNS. This just points to an app installation page.

It should probably be changed to point to https://cloudflare-dns.com/dns/#explanation which is an actual explanation on how Cloudflare DNS works.

(If I understood the first thing about Github, I'd make this change myself, but I don't, so I can't).

FTL's NAMES_FROM_NETDB option needs documentation

FTL's NAMES_FROM_NETDB option (pi-hole/FTL#784) has no documentation yet in

https://docs.pi-hole.net/ftldns/configfile/

group Table Schema in database doesn't match documentation. Not sure which one should be corrected?

Versions

Pi-hole version is v5.1.2 (Latest: v5.1.2)
AdminLTE version is v5.1.1 (Latest: v5.1.1)
FTL version is v5.2 (Latest: v5.2)

Platform

• OS and version: Linux Mint 20 Ulyana

• Platform: iMac

Expected behavior

info to match.

Actual behavior / bug

documentation say NOT unique --> https://docs.pi-hole.net/database/gravity/groups/

Label	Type	Uniqueness enforced	Content
id	integer	Yes	Unique ID for database operations
enabled	boolean	No	Flag whether domains in this group should be used (0 = disabled, 1 = enabled)
name	text	No	Mandatory group name
description	text	No	Optional field for arbitrary user comments

group Table Schema says UNIQUE

CREATE TABLE "group"
(
	id INTEGER PRIMARY KEY AUTOINCREMENT,
	enabled BOOLEAN NOT NULL DEFAULT 1,
	name TEXT UNIQUE NOT NULL,
	date_added INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
	date_modified INTEGER NOT NULL DEFAULT (cast(strftime('%s', 'now') as int)),
	description TEXT
)

Steps to reproduce

1. go to --> https://docs.pi-hole.net/database/gravity/groups/

2. check first Table on page.

3. See

   Label	Type	Uniqueness enforced	Content
   name	text	No	Mandatory group name

4. open /etc/pihole/gravity.db in DB Browser

5. check group Table Schema

6. see included pic

Debug Token

• URL: https://tricorder.pi-hole.net/z5sfkyhqsw

Screenshots

Update Alternative Support links for donations and sponsorships.

We need to add GitHub Sponsorships and look at adding Hetzner (replace Digital Ocean?).

This should also be addressed with README.md's on the various other organization repositories.

Add No Agenda / Curry & Dvorak to podcasts

Coverage page hasn't had any new items added to it for a long time.

Need trailing / on https://pi-hole.net/ for two links to docs.pi-hole.net.

The button under 4. Block ads everywhere, even on the go, leading to https://docs.pi-hole.net/guides/vpn/overview, breaks other links on the documents site. As an example, the 'Installation' link under the 'overview' that the page brings you to should be https://docs.pi-hole.net/guides/vpn/installation/, but instead is https://docs.pi-hole.net/guides/installation/, missing the 'vpn' portion of the link. Same with other links on the page, though I didn't explore too much -- 'Benchmarking' just above the openVPN section links as https://docs.pi-hole.net/benchmark/ instead of https://docs.pi-hole.net/guides/benchmark/, as an example.

This should be resolved if the link on the main page is changed to have the trailing / at the end of the link.

I also noticed the same issue with the button for 3. Use Pi-hole as your DNS server.

I'm sorry if this is the wrong place to post this, as it's not an issue with the documentation itself, but I didn't know where to report an issue with the main page.

Affiliate link for UNIXstickers.com is broken

On the documentation homepage: https://docs.pi-hole.net/ the Alternative support section has a link for UNIXstickers.com which is not redirecting correctly. Currently it goes to a referralcandy site

Update guide for Unbound

Hello
Followed the guide and found a few things that were causing me issues. But with a bit of support and some searches I've found some answers and would like to see the guide updated so others don't have to struggle.

Was unable to get unbound stats with this command
sudo unbound-control stats_noreset
Solution was to add to the unbound config file

remote-control:
    control-enable: yes

I found unbound extremly slow compared to a couple other dnscrypt and cloudflare https guides but posts mentioned it took some time to build your cache and it should speed up. Well after a month and seeing response times ranging from 200 to 1100 ms i started doing some searches and found this reddit post

https://www.reddit.com/r/pihole/comments/d9j1z6/unbound_as_recursive_dns_server_slow_performance/

level 1
Khaare
27 points ·
3 months ago
Silver2

One thing that guide doesn't tell you is to completely turn off caching in your pi-hole instance, as well as DNSSEC validation (required to completely turn off caching). When you're using unbound you're relying on that for DNSSEC validation and caching, and pi-hole doing those same things are just going to waste time validating DNSSEC twice and confusing unbound's cache by not passing through commonly requested entries. This was the most impactful change I made on my setup.

Setting it up to serve expired entries turned out to be a big time-save as well. Most recursive replies are actually already in the cache, but the TTL has expired. By serving the expired entry and then refreshing the cache entry instead of waiting for the refresh to be completed before replying you retain the cache speedup. An alternative is to set the minimum TTL to something like 3600 seconds, but I found just serving expired entries to work a little better. This didn't really have any impact on the perceived speed, DNS is really fast already, but it did make the tests I ran look nicer.

(I run archlinux arm on my pi, and I think the location of the configuration files are slightly different from the default pi-hole locations, so you might find them somewhere else).

You can turn off DNSSEC in the admin-interface under settings->DNS.

In /etc/dnsmasq.d/01-pihole.conf make sure it contains:

cache-size=0

The file says it shouldn't be modified and to use other configuration files instead, but you're not allowed to duplicate keys so you're forced to either edit or remove the existing entry anyway ¯_(ツ)_/¯

You could also tune your unbound cache. Here's the relevant part from my /etc/unbound/unbound.conf:

server:
    # These options should be added to the existing server configuration,
    # overwriting existing values if they're there.

    # This refreshes expiring cache entries if they have been accessed with
    # less than 10% of their TTL remaining
    prefetch: yes

    # This attempts to reduce latency by serving the outdated record before
    # updating it instead of the other way around. Alternative is to increase
    # cache-min-ttl to e.g. 3600.
    cache-min-ttl: 0
    serve-expired: yes
    # I had best success leaving this next entry unset.
    # serve-expired-ttl: 3600 # 0 or not set means unlimited (I think)

    # Use about 2x more for rrset cache, total memory use is about 2-2.5x
    # total cache size. Current setting is way overkill for a small network.
    # Judging from my used cache size you can get away with 8/16 and still
    # have lots of room, but I've got the ram and I'm not using it on anything else.
    # Default is 4m/4m
    msg-cache-size: 128m
    rrset-cache-size: 256m

When you're looking at unbound's stats, they only show recursive replies. It doesn't take into account cached replies, which should be the majority of the replies. There average response time also seems inflated due to a few requests taking much longer than they should, probably due to the connection temporarily failing due to packet loss or something similar, which DNS is fairly prone to. These hiccups are mostly completely unnoticed by humans and programs alike, but they do inflate the stats quite a bit in my experience.

Using unbound in recursive mode it's going to be slower than other DNS servers for entries that aren't cached. It has to do potentially multiple lookups against name servers that could be anywhere in the world, while commercial DNS servers run with giant caches that in all probability already contain the entries you're looking for. However, the cache of your local unbound server shouldn't take long to get up to speed, and even when it's missing some entries now and then it shouldn't be noticeable to users. Cached entries should be served in 1ms at most from an instance running on your local network, which beats any other DNS, and makes unbound faster most of the time, slower every now and then, but you shouldn't notice any difference in day-to-day use anyway.

---

After adjusting the piholes dns cache to 0 and adding to my config file its now blazing fast
I'm still learning so i am not 100% sure i did the config file correctly but it all seems to pass the tests

Here's my config file

server:
    # These options should be added to the existing server configuration,
    # overwriting existing values if they're there.

    # This refreshes expiring cache entries if they have been accessed with
    # less than 10% of their TTL remaining
    prefetch: yes

    # This attempts to reduce latency by serving the outdated record before
    # updating it instead of the other way around. Alternative is to increase
    # cache-min-ttl to e.g. 3600.
    cache-min-ttl: 0
    serve-expired: yes
    # I had best success leaving this next entry unset.
    # serve-expired-ttl: 3600 # 0 or not set means unlimited (I think)

    # Use about 2x more for rrset cache, total memory use is about 2-2.5x
    # total cache size. Current setting is way overkill for a small network.

    # Judging from my used cache size you can get away with 8/16 and still
    # have lots of room, but I've got the ram and I'm not using it on anything else.
    # Default is 4m/4m
    msg-cache-size: 128m
    rrset-cache-size: 256m


    # If no logfile is specified, syslog is used
    # logfile: "/var/log/unbound/unbound.log"
    verbosity: 0

    port: 5353
    do-ip4: yes
    do-udp: yes
    do-tcp: yes

    # May be set to yes if you have IPv6 connectivity
    do-ip6: no

    # Use this only when you downloaded the list of primary root servers!
    root-hints: "/var/lib/unbound/root.hints"

    # Trust glue only if it is within the servers authority
    harden-glue: yes

    # Require DNSSEC data for trust-anchored zones, if such data is absent, the zone becomes BOGUS
    harden-dnssec-stripped: yes

    # Don't use Capitalization randomization as it known to cause DNSSEC issues sometimes
    # see https://discourse.pi-hole.net/t/unbound-stubby-or-dnscrypt-proxy/9378 for further details
    use-caps-for-id: no

    # Reduce EDNS reassembly buffer size.
    # Suggested by the unbound man page to reduce fragmentation reassembly problems
    edns-buffer-size: 1472

    # Perform prefetching of close to expired message cache entries
    # This only applies to domains that have been frequently queried

    # prefetch: yes

    # One thread should be sufficient, can be increased on beefy machines. In reality for most users running on small networks or on a single machine it should be unne$
    num-threads: 1

    # Ensure kernel buffer is large enough to not lose messages in traffic spikes
    so-rcvbuf: 1m

    # Ensure privacy of local IP ranges
    private-address: 192.168.0.0/16
    private-address: 169.254.0.0/16
    private-address: 172.16.0.0/12
    private-address: 10.0.0.0/8
    private-address: fd00::/8
    private-address: fe80::/10

    remote-control:
        control-enable: yes

Switch to GitHub Actions CI

So that everything is controlled through the repo settings including secrets.

I can make a PR but I don't know how to test it...

References:

• https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-static-site-generators-with-python

Broken links when opening VPN overview from https://pi-hole.net/

Versions

N/A

Platform

N/A

Expected behavior

After navigating to the VPN docs from https://pi-hole.net/, clicking navigation links works.

Actual behavior / bug

After following the link from https://pi-hole.net/ to https://docs.pi-hole.net/guides/vpn/overview , all of the links for the VPN section are broken.

Adding a trailing slash to the url (e.g. https://docs.pi-hole.net/guides/vpn/overview/ fixes the links.

Steps to reproduce

Steps to reproduce the behavior:

1. Go to https://pi-hole.net/
2. Click on the "PI-HOLE + VPN" button in section 4.
3. Click on any of the navigation links under "Pi-Hole and OpenVPN Server"
4. See error

Debug Token

N/A

Screenshot

None

Additional context

None

Documentation:

Not so much on the code. I am newly installing pihole in a cloud machine along with openvpn. The documentation that talks about firewall setting:

https://docs.pi-hole.net/guides/vpn/firewall/

is very misleading. Let say if I follow "Option 2: Explicitly allow what can be accessed within the VPN", you will notice that somewhere down, the documentation indicate to execute "iptables -P INPUT DROP"

That executing locks me out of the node. Luckily I figured out on how to launch a web-based terminal from the cloud website. I have deleting/creating nodes over and over until I finally figured out the iptables command the lock me out. On top of that, I still could not use pihole through VPN tunner. So i truly need the proper firewall setup to make this to work.

Thank you guys for the hardwork.

Add hint to section "Blocking Https Advertisement Assets" that it is only needed for Pihole version < 4.0

WARNING: I'm not 100% sure about this. So please excuse me if this issue was a mistake/is wrong.

As far as I have understood it, as of version 4.0 of Pi-hole there is no need to execute the iptables commands listet in the "Blocking Https Advertisement Assets" section here.
Reason as to why I think this is an issue: The edit "Update: 2018-08-06" in the top post

Website: 404 not found when browsing PIHLOE+VPN install docs

Steps to reproduce

1. On main page https://pi-hole.net/ scroll and click PI-HOLE+VPN button
2. On the overview page, scroll to the bottom and click the Next link Installation

Result

404 Not Found (the link takes you to https://docs.pi-hole.net/guides/installation/)

Expected

The OpenVPN installation docs at https://docs.pi-hole.net/guides/vpn/installation/

Env

Ubuntu 18.04
Firefox 79.0

Custom upstream DNS servers can be on non-standard ports

https://github.com/pi-hole/docs/blob/master/docs/guides/upstream-dns-providers.md

Add verbiage to Custom DNS to note that upstream can be on #<port> notation.

See if we can use another plugin for redirects

Currently we redirect via a frontmatter entry which adds moot pages in the dist folder. It might be possible to use another plugin to prevent this behavior and keep the redirects in the config file.

Theme improvements

Some things I noticed while playing around with the repo

1. I'm not sure if we really use Font Awesome; if not we should find a way to disable it - EDIT: it seems it's included for the social icons which is an overkill IMO, but an upstream issue, see squidfunk/mkdocs-material#1364
2. We should inline or at least combine extra CSS and material CSS which imports the fonts - EDIT upstream issue
3. IMHO the main text font-size (14px) is too small; we should use the default .8rem
4. Might be worth either preconnecting or at least DNS prefetching api.github.com - EDIT upstream issue but we could just add the template partial and modify it

Some of these issues (1, 4) we might need to report upstream for everyone to benefit

Gravity 'Script Location' link broken

/doc/core/pihole-command.md has a link under Gravity > Script Location labelled "/opt/pihole/gravity.sh" which has an incorrect URL.

The URL is:

"https://github.com/pi-hole/pi-hole/blob/master/advanced/Scripts/gravity.sh"

but should be:

"https://github.com/pi-hole/pi-hole/blob/master/gravity.sh"

undocumented settings in pihole-FTL.conf

Versions

Pi-hole version is v5.3.1 (Latest: v5.3.1)
AdminLTE version is v5.5 (Latest: v5.5)
FTL version is v5.8.1 (Latest: v5.8.1)

1. looking at the startup messages from pihole-FTL, comparing the reported settings with the documentation.

following settings are undocumented (https://docs.pi-hole.net/ftldns/configfile/)

undocumented

#PARSE_ARP_CACHE=
#REPLY_ADDR4=
#REPLY_ADDR6=

following debug options are undocumented

undocumented

#DEBUG_STATUS=
#DEBUG_EDNS0=
#DEBUG_CLIENTS=
#DEBUG_ALIASCLIENTS=
#DEBUG_EVENTS=
#DEBUG_HELPER=
#DEBUG_EXTRA=

2. Not all debug settings are reported when starting pihole-FTL (for example DEBUG_EXTBLOCKED, see here

3. When enabling DEBUG_EXTBLOCKED=true, the list of enabled / disabled debug settings is no longer listed in the log.

expected (not all possible settings are reported), added to the log: none
`
[2021-05-22 09:38:46.162 29557M] *****************************

[2021-05-22 09:38:46.163 29557M] * Debugging enabled *
[2021-05-22 09:38:46.163 29557M] * DEBUG_DATABASE NO *
[2021-05-22 09:38:46.164 29557M] * DEBUG_NETWORKING NO *
[2021-05-22 09:38:46.164 29557M] * DEBUG_LOCKS NO *
[2021-05-22 09:38:46.164 29557M] * DEBUG_QUERIES NO *
[2021-05-22 09:38:46.165 29557M] * DEBUG_FLAGS NO *
[2021-05-22 09:38:46.165 29557M] * DEBUG_SHMEM NO *
[2021-05-22 09:38:46.166 29557M] * DEBUG_GC NO *
[2021-05-22 09:38:46.166 29557M] * DEBUG_ARP NO *
[2021-05-22 09:38:46.166 29557M] * DEBUG_REGEX NO *
[2021-05-22 09:38:46.167 29557M] * DEBUG_API NO *
[2021-05-22 09:38:46.167 29557M] * DEBUG_OVERTIME NO *
[2021-05-22 09:38:46.168 29557M] * DEBUG_STATUS NO *
[2021-05-22 09:38:46.168 29557M] * DEBUG_CAPS NO *
[2021-05-22 09:38:46.168 29557M] * DEBUG_DNSMASQ_LINES NO *
[2021-05-22 09:38:46.169 29557M] * DEBUG_VECTORS NO *
[2021-05-22 09:38:46.169 29557M] * DEBUG_RESOLVER NO *
[2021-05-22 09:38:46.170 29557M] * DEBUG_EDNS0 NO *
[2021-05-22 09:38:46.170 29557M] * DEBUG_CLIENTS NO *
[2021-05-22 09:38:46.171 29557M] * DEBUG_ALIASCLIENTS NO *
[2021-05-22 09:38:46.171 29557M] * DEBUG_EVENTS NO *
[2021-05-22 09:38:46.172 29557M] * DEBUG_HELPER NO *
[2021-05-22 09:38:46.172 29557M] * DEBUG_EXTRA NO *
[2021-05-22 09:38:46.173 29557M] *****************************
`

Add caveats and VPN warnings to unbound documentation.

See https://www.reddit.com/r/pihole/comments/ctzl64/unbound_upstream_not_resolving_some_fqdns/exu9zdf

Move all images in the `images` root folder

Creating any subfolders to make organization better.

Pihole Unbound install documentation has location of (unbound) pihole.conf wrong.

Versions

[root@pihole ~]# pihole -v
Pi-hole version is v5.2.4 (Latest: v5.2.4)
AdminLTE version is v5.3.2 (Latest: v5.3.2)
FTL version is v5.6 (Latest: v5.6)
[root@pihole ~]#

Platform

Centos 7 LXC container.

Expected behavior

Unbound will work.

Actual behavior / bug

Unbound Fails to startup:

Feb 02 18:24:11 pihole systemd[1]: Started Unbound recursive Domain Name Server.
Feb 02 18:24:11 pihole unbound[449]: [1612290251] unbound[449:0] notice: Start of unbound 1.6.6.
Feb 02 18:24:11 pihole unbound[449]: Feb 02 18:24:11 unbound[449:0] debug: increased limit(open files) from 1024 to 16566
Feb 02 18:24:11 pihole unbound[449]: Feb 02 18:24:11 unbound[449:0] debug: creating udp6 socket ::1 53
Feb 02 18:24:11 pihole unbound[449]: Feb 02 18:24:11 unbound[449:0] debug: creating tcp6 socket ::1 53
Feb 02 18:24:11 pihole unbound[449]: Feb 02 18:24:11 unbound[449:0] error: can't bind socket: Address already in use for ::1 port 53 (len 28)
Feb 02 18:24:11 pihole unbound[449]: Feb 02 18:24:11 unbound[449:0] fatal error: could not open ports
Feb 02 18:24:11 pihole systemd[1]: unbound.service: main process exited, code=exited, status=1/FAILURE
Feb 02 18:24:11 pihole systemd[1]: Unit unbound.service entered failed state.
Feb 02 18:24:11 pihole systemd[1]: unbound.service failed.

[

Steps to reproduce

systemctl start unbound

Additional context

Used:
https://docs.pi-hole.net/guides/dns/unbound/
To install unbound.

Loaded pihole.conf into /etc/unbound/unbound.conf.d/pihole.conf as per docs

Should be:

/etc/unbound/conf.d/pihole.conf

Unbound documentation error

In the section that talks about the /etc/unbound/unbound.conf.d/pi-hole.conf file, it shows:

    # Use this only when you downloaded the list of primary root servers!
    # If you use the default dns-root-data package, unbound will find it automatically
    #root-hints: "/var/lib/unbound/root.hints"

Why is this commented out when the step right before generating this config file is to manually download the root.hints file?

Unbound private-address seems to cause querry issues

Versions

unbound 1.9.0

Platform

Rasberry Pi 3B+

Expected behaviour

Answer the DNS queries with an IP-address.

Actual behaviour / bug

I had problems with some DNS queries. After reducing the private-address to my local address range the problems were gone.
The IP-addresses with problems are in the range 172.30 to 172.31. It seems like the default private range was from 169.254 to 192.168.

Steps to fix

Reducing the private-address to your local used ranges.

Screenshots

Answer with default private-address:

Answer after reducing to my locale private-address (192.168.2.0 to 192.168.2.2):

Revisit the upstream DNS providers page

See the PR discussion for context: #267 (review)

Regex blacklist patterns in non-default group not working for clients in default group

In raising this issue, I confirm the following (please check boxes, eg [X]) Failure to fill the template will close your issue:

• I have read and understood the contributors guide.
• The issue I am reporting can be replicated
• The issue I am reporting isn't a duplicate

How familiar are you with the codebase?:

2

---

[BUG] Expected Behaviour:
Blacklist regex patterns that are in a group other than the default group should be blocked for clients that are in the default group/no group

[BUG] Actual Behaviour:
Clients in the default group/no group can access domains that should be blocked by blacklist regex patterns in a group other than default

[BUG] Steps to reproduce:

1. create new regex blacklist pattern
2. create a new group
3. add new regex pattern to a group other than the default group - do not add the pattern to both the new group and the default group, just add it to the new group
4. try to access a domain that is blocked by the regex pattern with a client in the default group/not explicitly assigned to a group

This bug likely also appears for whitelisted regex patterns that are in the non-default group, though I haven't explicitly tested that situation.

---

I believe the queries to gravity's database for regex domains is a little too strict. The sql statement SELECT id from %s WHERE group_id IN (%s); in gravityDB_get_regex_client_groups selects only regex domains that match exactly the group of the client, even if the client is in the special "all groups" group with id 0.

I believe swapping out the linked line with something like the following would solve the problem:

if (strcmp(groups, "0") == 0) {
  // Client is in default group, allow all regex domains.
  if(asprintf(&querystr, "SELECT DISTINCT id from %s;", table) < 1)
  {
    logg("gravityDB_get_regex_client_groups(%s) - asprintf() error for client in default group", table);
    return false;
  }
} else {
  // Client belongs to a specific group or groups, select only those regex domains in the group(s).
  if(asprintf(&querystr, "SELECT id from %s WHERE group_id IN (%s);", table, groups) < 1)
  {
    logg("gravityDB_get_regex_client_groups(%s, %s) - asprintf() error", table, groups);
    return false;
  }
}

This template was created based on the work of udemy-dl.

Port current wiki pages to docs.pi-hole.net

See title. Creating an issue to label for Hacktoberfest.

Update guide for nginx

After following the nginx install guide I was still getting errors on the AdminLTE. It looks like when httplite is selected in the install script updates sudoers https://github.com/pi-hole/pi-hole/blob/e41c4b5bb691cea1f5b950d39518d8c404b5846e/automated%20install/basic-install.sh#L1696. Would it be possible to add updating the sudoers file to include the distributions nginx user?

Document hidden PIHOLE_SELINUX variable

In raising this issue, I confirm the following: {please fill the checkboxes, e.g: [X]}

• I have read and understood the contributors guide.
• The issue I am reporting can be replicated.
• The issue I am reporting isn't a duplicate (see FAQs, closed issues, and open issues).

How familiar are you with the the source code relevant to this issue?:

{Replace this with a number from 1 to 10. 1 being not familiar, and 10 being very familiar}

7

---

Expected behaviour:

{A detailed description of what you expect to see}

pihole update code for 5 release checks for SELinux and exits if it is enabled, however there is also a shell variable PIHOLE_SELINUX. If this is set pihole -up continues with SELinux either enabled or enabled and in enforcing mode. I understand there are issues with pihole as is with SELinux and have taken measures to let it function with SELinux enforcing to a degree I can live with.

IMHO this variable should be either mentioned by the installer in update mode or documented. I just stumbled upon it in your source code.

Actual behaviour:

pihole -up on 4->5 updates pihole and the webinterface but not FTL, and thus breaks itself.

{A detailed description and/or screenshots of what you do see}

Steps to reproduce:

pihole -up on any system with SELinux enabled.

{Detailed steps of how we can reproduce this}

export PIHOLE_SELINUX=true

pihole -up

Succes

pihole -up

Failure

Debug token provided by uploading pihole -d log:

{Alphanumeric token}

Troubleshooting undertaken, and/or other relevant information:

{Steps of what you have done to fix this}

• You must follow the template instructions. Failure to do so will result in your issue being closed.
• Please submit any feature requests here, so it is votable and trackable by the community.
• Please respect that Pi-hole is developed by volunteers, who can only reply in their spare time.
• Detail helps us understand and resolve an issue quicker, but please ensure it's relevant.
• This template was created based on the work of udemy-dl.

issue: warning: so-rcvbuf 1048576 was not granted <<Solved>>

Versions

• Pi-hole: v5.3.1
• AdminLTE: v5.5?
• FTL: v5.8.1

Platform

Ubuntu 20.04

Some people are getting the issue:
[1626249031] unbound[110586:0] warning: so-rcvbuf 1048576 was not granted. Got 425984. To fix: start with root permissions(linux) or sysctl bigger net.core.rmem_max(linux) or kern.ipc.maxsockbuf

so I i would add in the documentation:
run unbound from the cli
and if you receive the above error:
run sysctl -w net.core.rmem_max=1048576 from the cli

I know this is dumb and most linux pros know this. but alot of us are noobs like me
and scouring the internet for the answer. but none of them listed this as the fix.
most likely because the first part of the error states to run unbound as root.
which is probably not a good idea or it already is and that won't fix the problem.
idk like I said I'm a newb and still learning. and have no idea if they have it set to
run as root or not. But this fixed it for me, And alot of people don't know where to
look or how to find the answer. so I figured I'd ask you guys to add it to the
documentation for other linux retards like me. thx

Unbound Issues with raspbian light

It seems like https://docs.pi-hole.net/guides/unbound/ needs to be refreshed as unbound isnt working with the given confoguration on a clean raspbian light installation. When using the dig command a server timeout comes.

Ref NLnetLabs/unbound#237

Dependabot couldn't authenticate with https://pypi.python.org/simple/

Dependabot couldn't authenticate with https://pypi.python.org/simple/.

You can provide authentication details in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'.

View the update logs.

Wiki DNScrypt-Proxy v2

The wiki for DNScrypt v2 should be added
After activating DNScrypt, the settings "Use DNSSEC" in Pihole must be deactivated (unchecked).

see DNSCrypt/dnscrypt-proxy#956

Regards

Unbound install guide does not clearly state to install root.hints

The unbound install guide at https://docs.pi-hole.net/guides/unbound/ states the following:

"Optional: Download the list of primary root servers (serving the domain .). Unbound ships its own list but we can also download the most recent list and update it whenever we think it is a good idea. Note: there is no point in doing it more often then every 6 months."

After running sudo apt install unbound on Stretch, I verified that this file is not installed with the install command. This was also noted by a discourse user (https://discourse.pi-hole.net/t/unbound-will-not-start/14327).

Recommend changing this wording in the install guide to the following:

"Optional: Download the current list of primary root servers (serving the domain .). Unbound ships its own list but we can also download the most recent list andUpdate it whenever we think it is a good idea. Note: there is no point in doing it more often then every 6 months or so, as the file changes infrequently."

unbound have no uninstall/removal documentation

According to reddit something like this should be in the documentation

    Stop the service:
    sudo service unbound stop
    Remove unbound package:
    sudo apt remove unbound
    Remove configs and properties:
    sudo rm -r /var/lib/unbound/
    sudo rm -r /etc/unbound/
    Remove dependencies that are not needed anymore:
    sudo apt autoremove
    Clean up:
    sudo apt autoclean

Internal links not working without forward-slash in URL

Platform

Tested on Safari and Chrome on Mac OSX

Expected behavior

Navigate to https://docs.pi-hole.net/guides/vpn/overview
Click any link to another docs page
View page

Actual behavior / bug

Navigate to https://docs.pi-hole.net/guides/vpn/overview
Click any link to another docs page
receive 404 error

Steps to reproduce

Use, for example:
https://docs.pi-hole.net/guides/vpn/overview
Instead of:
https://docs.pi-hole.net/guides/vpn/overview/
(ie. omit final forward-slash)
Click link at the end of first paragraph: "this section of the tutorial"

Additional context

Relevant as the failing URL is linked from external pages, for example:
https://makezine.com/projects/raspberry-pi-network-ad-blocker/

Query database is missing new status types

https://docs.pi-hole.net/database/ftl/#supported-status-types

is missing the new types 12-14 introduced by

pi-hole/FTL#901

and

pi-hole/FTL@6bb025f

Add instructions to configure nftables firewall

The current documentation about prerequisites - firewalls describes how to use IPTables, FirewallD, and ufw. nftables is the "modern" version of IPTables and is not in the guide.

It would be nice to have official instructions for setting nftables up.

the comment column in the group table is named wrong in the documentation.

Versions

Pi-hole version is v5.1.2 (Latest: v5.1.2)
AdminLTE version is v5.1.1 (Latest: v5.1.1)
FTL version is v5.2 (Latest: v5.2)

Platform

• OS and version: Linux Mint

• Platform: iMac

Expected behavior

docs to match database.

Actual behavior / bug

column is not named correctly in documentation

what it is.

Label	Type	Uniqueness enforced	Content
id	integer	Yes	Unique ID for database operations
enabled	boolean	No	Flag whether domains in this group should be used (0 = disabled, 1 = enabled)
name	text	No	Mandatory group name
comment	text	No	Optional field for arbitrary user comments

what was expected

Label	Type	Uniqueness enforced	Content
id	integer	Yes	Unique ID for database operations
enabled	boolean	No	Flag whether domains in this group should be used (0 = disabled, 1 = enabled)
name	text	No	Mandatory group name
description	text	No	Optional field for arbitrary user comments

Steps to reproduce

Steps to reproduce the behavior:

1. Go to https://docs.pi-hole.net/database/gravity/groups/
2. look at first table on page
3. load gravity.db in DB Browser
4. check last column name and see it doesn't match.

Debug Token

• URL:

Screenshots

Table as shown in DB Browser

Additional context

Add any other context about the problem here.

Update Gravity DB documentation

I noticed that following the 5.2/5.3 update, there is a change to the adlist table schema:

sqlite> pragma table_info('adlist');
0|id|INTEGER|0||1
1|address|TEXT|1||0
2|enabled|BOOLEAN|1|1|0
3|date_added|INTEGER|1|cast(strftime('%s', 'now') as int)|0
4|date_modified|INTEGER|1|cast(strftime('%s', 'now') as int)|0
5|comment|TEXT|0||0
6|date_updated|INTEGER|0||0

The documentation for the database still only lists the 6 original labels.

Add log2ram

I think it makes sense to have an article about this since it helps increasing the SD card lifetime

https://github.com/azlux/log2ram

Documentation Issue: Dns-Over-HTTPs with Cloudflared

In raising this issue, I confirm the following: {please fill the checkboxes, e.g: [X]}

• I have read and understood the contributors guide.
• The issue I am reporting can be replicated.
• The issue I am reporting isn't a duplicate (see FAQs, closed issues, and open issues).

How familiar are you with the the source code relevant to this issue?:

N/A - Documentation Issue

---

Expected behaviour:

Documentation on Encrypted DNS via Cloudflared should use correct systemd paths, and provide update instructions.

Actual behaviour:

Documentation instructs users to update the system built-in unit store, instead of the user config store. No update instructions provided.

Steps to reproduce:

N/A - however, issues can be fixed by replacing the systemd unit /lib/systemd/system path with /etc/systemd/system/, which is the user-created store for systemd files.

Also, while this is slightly more of a documentation change request, there's no information on updating the cloudflared daemon. While not exactly elegant, something like this could be called as a cron job:

echo "Updating Cloudflared Daemon..."
wget -P /tmp https://bin.equinox.io/c/VdrWdbjqyF/cloudflared-stable-linux-arm.tgz
systemctl stop cloudflared
tar -C /opt/cloudflared -xzf /tmp/cloudflared-stable-linux-arm.tgz
systemctl start cloudflared
rm /tmp/cloudflared-stable-linux-arm.tgz
echo "Cloudflared update complete."

Debug token provided by uploading pihole -d log:

N/A

Troubleshooting undertaken, and/or other relevant information:

N/A

Add mkdocs-minify-plugin

https://github.com/byrnereese/mkdocs-minify-plugin

Not super familiar with mkdocs, but for production this should save a few bytes.

Docs refer to OpenVPN files which have moved in newer versions

According to https://github.com/OpenVPN/openvpn/blob/master/distro/systemd/README.systemd, as of OpenVPN v2.4, most/all configuration files were moved from /etc/openvpn/ to /etc/openvpn/server/.

A number of the pihole guide pages still refer to the old path:

docs/docs/guides/vpn/dual-VPN.md

Lines 5 to 10 in b7fc8aa

	You should have an existing OpenVPN server configured and running. We are going to use the original configuration file located at `/etc/openvpn/server.conf`.
	First, copy the file:
	```bash
	sudo cp /etc/openvpn/server.conf /etc/openvpn/server2.conf

docs/docs/guides/vpn/dynDNS.md

Line 4 in 4a6bb6c

vim /etc/openvpn/client-common.txt

docs/docs/guides/vpn/setup-openvpn-server.md

Line 17 in 4a6bb6c

vim /etc/openvpn/server.conf

docs/docs/guides/vpn/only-dns-via-vpn.md

Line 5 in a7d259a

Edit your `/etc/openvpn/server.conf` and remove (comment out) the following line:

docs/docs/guides/vpn/dual-operation.md

Line 12 in 95956c3

Edit your `/etc/openvpn/server.conf`:

... and more (listing them is tedious when it's easy to fix).

Caused me a bit of confusion when I first ran through the guide - spent about an hour scratching my head as to why my settings weren't applying or things were missing until I realised everything was under the server folder.

I'll raise a PR to fix this issue.

Errors and omissions in the OpenVPN pihole guide

Is it me or had this guide only just moved to https://docs.pi-hole.net/guides/vpn, I swear I was using it last week in a github wiki format, or was that a rehost?

I've noticed a few things.

1. In the firewall config guide, the bit on dropping https connections for improved speed isn't there (it was on the previous guide I used)
2. In the firewall section there is nothing about how to save the firewall config and load it at startup (I think there was in the previous guide)
3. In the VPN + Lan config section there is an inappropriate html tag in one of the code blocks push "dhcp-option DNS <b>192.168.2.123</b>"

Update docs pull request template.

We don't need DCO on documentation, nor the 15 checkboxes for this repo.

Also we need to review the Issue templates since they use the .github defaults and they aren't applicable to this repo.

Add Unbound as DoT guide

DoH is a dirty, ugly hack that friends don't let friends use.

Unbound can do DoT, so let's use that and write a guide for how to do it.

https://calomel.org/unbound_dns.html has some good information on how to set it up.

Issue with Cloudflared documentation

Hello,

It seems that there is an issue with the documentation related to Cloudflared installation.

I followed the manual, as usual, but when configuring Cloudflared using the automatic way, I get the following error message after running sudo cloudflared service install

Configuration file /etc/cloudflared/config.yml must contain entries for the tunnel to run and its associated credentials: tunnel: TUNNEL-UUID credentials-file: CREDENTIALS-FILE

I believe that this issue was introduced with the new version of cloudflared as I am familiar with the procedure and never got this message before. I am running cloudflared version 2020.10.2 (built 2020-10-21-1858 UTC).

Would it be possible to update the config.yml file as I am not sure what should be set there?

Easy-to-Install YouTube Link is Broken

The YouTube link on the Easy-to-Install section of the Overview is broken. The video has been deleted.

Known affected files:

• pi-hole/docs/docs/index.md
• pi-hole/pi-hole/README.md

dual operation page in the guide returns 404

In raising this issue, I confirm the following: {please fill the checkboxes, e.g: [X]}

• I have read and understood the contributors guide.
• The issue I am reporting can be replicated.
• The issue I am reporting isn't a duplicate (see FAQs, closed issues, and open issues).

How familiar are you with the the source code relevant to this issue?:

1

Expected behaviour:

The page should load.

Actual behaviour:

404 is returned.

Steps to reproduce:

Past this url into your browser's address bar and hit enter: https://docs.pi-hole.net/guides/vpn/dual-operation.md

Debug token provided by uploading pihole -d log:

xtni6hnctb

Troubleshooting undertaken, and/or other relevant information:

{Steps of what you have done to fix this}

• {Please delete this quoted section when opening your issue}
• You must follow the template instructions. Failure to do so will result in your issue being closed.
• Please submit any feature requests here, so it is votable and trackable by the community.
• Please respect that Pi-hole is developed by volunteers, who can only reply in their spare time.
• Detail helps us understand and resolve an issue quicker, but please ensure it's relevant.
• This template was created based on the work of udemy-dl.