Last updated on December 27, 2023

You need a Raspberry Pi with either Raspbian, Ubuntu Server or DietPi installed. For this guide we’re using Ubuntu Server as the operating system (use 64bit if you have Raspberry Pi 3 B+ or newer), but all commands and such should be similar with the other operating systems as well.

Useful tools before you start

SD Card Formatter – Whenever you need to format your SD card, use this tool.

Balena Etcher – Tool to flash the OS to your SD card.

Operating Systems

Raspberry Pi OS (desktop, lite)Recommended operating system for most users.
Ubuntu (desktop, server, core)Ubuntu is the most popular linux distribution.
DietPiMinmalistic OS for better performance or if you want to install only what you need.

Let’s begin

Download the image and insert the Raspberry Pi’s micro SD card into your computer meanwhile you wait for the download to finish. When the download is finished, download and run/install balenaEtcher:

Select the image you downloaded, then select the micro SD card in your computer and click on flash. When it is done you can remove the micro SD card from your computer and insert it into your Raspberry Pi and turn on the power. The Raspberry Pi will now boot up and you can log into it by finding the IP-address from your router and using a terminal. We recommend Termius as it is a really good and free terminal for all systems:

First time you log into it via SSH your username and password is the default for the operating system you installed showed to the right here.

On the first login you will be asked to change the password which we recommend that you do.

Operating systemUsernamePassword
Ubuntu Serverubuntuubuntu
RaspbianChosen upon first bootChosen when user is created on first boot

If you want to use DietPi follow the guide here:

And for information on how to enable encrypted DNS with DietPi and Unbound check out this page:

Setting up Pi-hole

Type in this in your terminal window:

curl -sSL | bash

When the installation is done open a browser window and type in your raspberry pi’s IP-address (example: to log into your pi-hole admin page. You can change the password by entering the following command:

pihole -a -p

If you want to remove the password, just hit enter after running the command above.

Setting up the DNS server

Open up a terminal window and choose one of the installs below (stubby or unbound). If you are concerned about privacy and don’t trust public DNS resolvers you should go with unbound. You may also install and run both if you want to have a backup, for example unbound as main DNS and then stubby through Cloudflare as secondary DNS. Both guides below uses different ports to make this possible for those that are interested in this.

Unbound (recommended)

Unbound is “a caching DNS resolver.” It directly communicates with the authoritative name servers and does the resolving itself, avoiding the need for a upstream resolver. It has very efficient caching and is generally quite fast.


For this guide you don’t need to think about public DNS resolvers as Unbound will become your private DNS resolver.

sudo apt install unbound -y

The main configuration file is /etc/unbound/unbound.conf.d/pihole.conf. You can open the file with:

sudo nano /etc/unbound/unbound.conf.d/pihole.conf

Paste in the follwing configuration in your pihole.conf file:

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

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

    cache-max-ttl: 14400
    cache-min-ttl: 600

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

    # You want to leave this to no unless you have *native* IPv6. With 6to4 and
    # Terredo tunnels your web browser should favor IPv4 for the same reasons
    prefer-ip6: no

    # 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"

    # Trust glue only if it is within the server's 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 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: 1232

    # 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 b>
    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: fd00::/8
    private-address: fe80::/10

## If you want to use DNS over TLS (encrypted DNS) uncomment the lines below with only one #
    ## TLS settings
    tls-upstream: yes
    tls-cert-bundle: "/etc/ssl/certs/ca-certificates.crt"

   # Increase privacy
    minimal-responses: yes

    # Enable round-robin balancing
    rrset-roundrobin: yes

    ssl-upstream: yes

    # Send minimum amount of information to upstream servers to enhance
    # privacy. Only sends minimum required labels of the QNAME and sets
    # QTYPE to NS when possible.

    # See RFC 7816 "DNS Query Name Minimisation to Improve Privacy" for
    # details.
  # Uncomment if the file /etc/unbound/unbound.conf.d/qname-minimisation.conf does not exist
#    qname-minimisation: yes

    hide-identity: yes
    hide-version: yes

    ## upstream resolver settings
    name: "."
    ## Cloudflare DNS
    forward-addr: # primary
    forward-addr: # secondary
    ## Quad 9 'secure' service - Filters, does DNSSEC, does ECS
    forward-addr: # primary
    forward-addr: # secondary
    ## Quad 9 'secure' service - Filters, does DNSSEC, doesn't send ECS
    forward-addr: # primary
    forward-addr: # secondary
    ## IPv6  Cloudflare DNS over TLS
    forward-addr: 2606:4700:4700::1111@853 # primary
    forward-addr: 2606:4700:4700::1001@853 # secondary
    ## IPv6  Quad 9 'secure' service - Filters, does DNSSEC, does ECS
    forward-addr: 2620:fe::11@853 # primary
    forward-addr: 2620:fe::fe:11@853 # secondary
    ## IPv6  Quad 9 'secure' service - Filters, does DNSSEC, doesn't send ECS
    forward-addr: 2620:fe::fe@853 # primary
    forward-addr: 2620:fe::9@853 # secondary

Save the file and restart your local recursive server for the changes to take effect and test that it’s operational:

sudo service unbound restart dig @ -p 5353

The first query may be quite slow, but subsequent queries, also to other domains under the same TLD, should be fairly quick.

Our next step is to ensure that Pi Hole’s faster-than-light (FTL) daemon adheres to the “edns-packet-max” limit we set in Rebound. To set this, we need to write a config file within the “/etc/dnsmasq.d” directory by using the command below.

sudo nano /etc/dnsmasq.d/99-edns.conf

You will want to add the following line within this file.


With the line added, you can save and quit by pressing CTRL + X, followed by Y, and then the ENTER key.

For those running Raspberry Pi OS Debian 11 (Bullseye) and newer, you must disable the “Unbound resolvconf” service that is automatically created during installation.

To disable the “Unbound resolvconf” service, use the following command in the terminal.

sudo systemctl disable --now unbound-resolvconf.service

Next, we must disable the “resolvconf_resolvers.conf” file so that it isn’t evoked by resolvconf itself.

sudo sed -Ei 's/^unbound_conf=/#unbound_conf=/' /etc/resolvconf.conf

For our configuration changes to take effect, you must restart the Unbound service.

sudo service unbound restart

You can test DNSSEC validation using

dig @ -p 5353

dig @ -p 5353

The first command should give a status report of SERVFAIL and no IP address. The second should give NOERROR plus an IP address.


Stubby is “an application that acts as a local DNS Privacy stub resolver (using DNS-over-TLS). Stubby encrypts DNS queries sent from a client machine (desktop or laptop) to a DNS Privacy resolver increasing end user privacy.” Stubby is basically an encryption stub that encrypts the DNS traffic between you and an upstream resolver.

For this guide, Cloudflare DNS is chosen, but you can choose whatever DNS provider you prefer/trust.

sudo apt install stubby -y

The main configuration file is /etc/stubby/stubby.yml. You can open the file with:

sudo nano /etc/stubby/stubby.yml

The following line makes stubby run as a stub resolver instead of a full recursive resolver, which is why it’s named stubby.


The following configuration make stubby send DNS queries encrypted with TLS. It will not send quries in plain text.


This following line requires a valid TLS certificate on the remote recursive resolver.


The following lines set the listen addresses for the stubby daemon. By default, IPv4 and IPv6 are both enabled.

- 0::1

Standard port is 53, but we’re going to change this to 5053. Edit the listen addresses so it looks like this:

- 0::1@5053

The following line make stubby query recursive resolvers in a round-robin fashion. If set to 0, Stubby will use each upstream server sequentially until it becomes unavailable and then move on to use the next.

round_robin_upstreams: 1

By default there are 3 recursive resolvers enabled in stubby configuration file. They are run by stubby developers and support DNS over TLS. You can choose to leave them enabled or disable them by putting an # in front.

Scroll down to the upstream_recursive_servers: section and add one of the following 3 texts above the other DNS servers.

1. Recommended IPv4

## CloudFlare malware blocking servers
  - address_data:
    tls_auth_name: ""
  - address_data:
    tls_auth_name: ""
## Quad 9 'secure' service - Filters, does DNSSEC, does ECS
  - address_data:
    tls_auth_name: ""
  - address_data:
    tls_auth_name: ""
## Quad 9 'secure' service - Filters, does DNSSEC, doesn't send ECS
  - address_data:
    tls_auth_name: ""
  - address_data:
    tls_auth_name: ""

2. Recommended IPv6

## Cloudflare servers
  - address_data: 2606:4700:4700::1111
    tls_auth_name: ""
  - address_data: 2606:4700:4700::1001
    tls_auth_name: ""
## Quad 9 'secure' service - Filters, does DNSSEC, does ECS
  - address_data: 2620:fe::11
    tls_auth_name: ""
  - address_data: 2620:fe::fe:11
    tls_auth_name: ""
## Quad 9 'secure' service - Filters, does DNSSEC, doesn't send ECS
  - address_data: 2620:fe::fe
    tls_auth_name: ""
  - address_data: 2620:fe::9
    tls_auth_name: ""

3. Standard DNS

# CloudFlare servers
  - address_data:
    tls_auth_name: ""
  - address_data:
    tls_auth_name: ""

4. Malware blocking

# CloudFlare servers
  - address_data:
    tls_auth_name: ""
  - address_data:
    tls_auth_name: ""

5. Malware and adult content blocking

# CloudFlare servers
  - address_data:
    tls_auth_name: ""
  - address_data:
    tls_auth_name: ""

Then find the following line:

round_robin_upstreams: 1

Change 1 to 0. This will make stubby always use CloudFlare DNS server. If CloudFlare is not available, stubby will use other DNS servers.

Save the file and restart stubby for the changes to take effect and test that it’s operational.

sudo systemctl restart stubby
dig @ -p 5053

You can test DNSSEC validation using

dig @ -p 5053
dig @ -p 5053

The first command should give a status report of SERVFAIL and no IP address. The second should give NOERROR plus an IP address.

Now that stubby or unbound is set up we can continue setting up pi-hole.

From the Pi-hole admin page go to settings and click on DNS and uncheck all the upstream servers on the left and type in the custom fields under upstream servers on the right as shown in the picture below.

For IPv4 field use:

For IPv6 field use: ::1#5353

Insert the port number you chose after the #. Remember to click save at the bottom of the page afterwards.


Now we should whitelist a couple of pages so that some everyday websites will function as normal.

First off you should take a look at pihole’s own list over commonly whitelisted domains and either add all or those you need:

If you’re lazy and don’t want to check out Pihole’s own list and copy and paste many times over, we’ve compiled one list of the most important domains here which will fix issues with the following services: Google (Maps, Youtube, etc), Microsoft (Windows, Office, Skype, etc), Spotify, Facebook, Plex, Sonarr, Dropbox, Apple (ID, Music, etc), NVIDIA GeForce Experience, Grand Theft Auto V Online, Epic Games Store, Slack, Mozilla Firefox Tracking Protection, Twitch. Just copy and paste in the code below in your terminal window on the Raspberry Pi.

pihole -w s{1..5}

We also recommend the whitelist from to be installed with automatic update. So continue with the following steps:

cd /opt/
sudo git clone

Make the script to run the script at 1AM on the last day of the week

sudo nano /etc/crontab

Add this line at the end of the file:
0 1 * * */7 root /opt/whitelist/scripts/

CTRL + X then Y and Enter

sudo python3 whitelist/scripts/


We recommend that you add the following adlists in addition to the default ones. Go into your Pi-hole admin page -> Group Management -> Adlists and add the lists you want.


OISD is a collection many adlists from accross the Internet, and all domains in this list are verified. There shouldn’t be any false positives in this list.

Block List Project

The Block List Project maintains many different blocking lists. We recommend at least adding the following lists: Ads, Fraud, Malware, Phising, Ransomware, Scam and Tracking.

# Ads

# Fraud

# Malware

# Phising

# Ransomware

# Scam

# Tracking

Developer Dan’s Hosts

Developer Dan’s Hosts is another popular list among people on the Internet. There are several lists which is maintained regularly, but we recommend adding the ads & tracking list.

The Firebog

The Firebog is a big blocklist collection with links to several lists. It is recommended to only add the lists with green check marks.

# Suspicious Lists

# Advertising Lists

# Tracking & Telemetry Lists

# Malicious Lists

# Other Lists

Phising Army

Phising Army is devoted to fight the criminals and provides protection against phising and malware sites, and so on. 91% of cyber attacks happens through email with links to malware and phising sites. We recommend using the extended blocklist that they provide.

YouTube ads

The following list will block some YouTube ads. The way YouTube changes how they serve ads makes it hard to block them all.

Regex Filters

We would also recommend that you add the regex filters from mmotti.

Add to Pi-Hole

curl -sSl | sudo python3

For more information visit mmotti’s github page.

The following regex must be manually added to be able to log into, Inside Telecom, Teknisk Ukeblad and Veier24.


Blocklist Pi-Hole update

Pi-Hole updates the domains to be blocked once a week. It is possible to change this configuration via the terminal:

sudo nano /etc/cron.d/pihole

It is recommended to change the default value of updateGravity to updating it daily. The line will look something like this

11 3   * * 7   root    PATH="$PATH:/usr/sbin:/usr/local/bin/" pihole updateGravity >/var/log/pihole/pihole_updateGravity.log || cat /var/log/pihole/pihole_updateGravity.log

We are only interested in the beginning of this line, in this example 11 3 * * 7. If you change the 7 to * here and save then Pi-Hole will update the blocklist daily. The line should then look like this:

11 3   * * *   root    PATH="$PATH:/usr/sbin:/usr/local/bin/" pihole updateGravity >/var/log/pihole/pihole_updateGravity.log || cat /var/log/pihole/pihole_updateGravity.log

For more information about how to configure crontab we recommend checking out the crontab guru from Cronitor.


That’s it. Now all you need to do to protect your network is to point your DNS in the LAN settings of your router towards the IP address of your pi-hole and your whole network will have increased privacy and be free of ads.

Updating Pi-hole

The web page of your Pi-hole will let you know if there are updates available. To update you log into the Raspberry Pi via SSH with your preferred Terminal and simply run this command:

pihole -up

Pi 4 MazePro Case

If you have Raspberry Pi 4 with the MazePro Case and want to use the power button on that case to also safely shutdown your Pi 4, then type in the following command and hit enter:

sudo echo "dtoverlay=gpio-shutdown" >> /boot/config.txt

Next reboot your Pi 4 for the changes to take effect.

PoE hat fan control

On Ubuntu Server 20.04 LTS the dtparams setting does not work, instead you need a udev rule to control the PoE hat fan. Log into your Raspberry Pi via SSH and run the following code to make sure it says “rpi-poe-fan”.

cat /sys/class/thermal/cooling_device0/type

Once you’ve confirmed that we will create a new udev rule. Start so by typing.:

sudo nano /etc/udev/rules.d/50-rpi-fan.rules

Then you can use this udev rule as an example:

# If the temp hits 60c, turn on the fan. Turn it off again when it goes back down to 55.
# If the temp hits 68c, higher RPM.
# If the temp hits 80c, higher RPM.
# If the temp hits 81c, highest RPM.

Save the file and exit the editor. The last thing you want to do is to apply the udev rules, do so by running the following command:

sudo udevadm control --reload-rules && sudo udevadm trigger

Accessing Pi-hole with HTTPS

If you have a domain and would like to access your pihole from outside your network with HTTPS, this is how you continue to set it up.

sudo apt install certbot
sudo certbot certonly --webroot -w /var/www/html -d

Enter your email address. Then hit A and press enter. And then hit N and press enter.

sudo cat /etc/letsencrypt/live/ \
/etc/letsencrypt/live/ | \
sudo tee /etc/letsencrypt/live/

Next, ensure the lighttpd user www-data can read the required certificates:

sudo chown www-data -R /etc/letsencrypt/live

Now, place the following into /etc/lighttpd/external.conf (again, making sure to subsitute for your FQDN):

$HTTP["host"] == "" {
  # Ensure the Pi-hole Block Page knows that this is not a blocked domain
  setenv.add-environment = ("fqdn" => "true")

  # Enable the SSL engine with a LE cert, only for this specific host
  $SERVER["socket"] == ":443" {
    ssl.engine = "enable"
    ssl.pemfile = "/etc/letsencrypt/live/" =  "/etc/letsencrypt/live/"
    ssl.honor-cipher-order = "enable"
    ssl.cipher-list = "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"
    ssl.use-sslv2 = "disable"
    ssl.use-sslv3 = "disable"       

  # Redirect HTTP to HTTPS
  $HTTP["scheme"] == "http" {
    $HTTP["host"] =~ ".*" {
      url.redirect = (".*" => "https://%0$0")

Finally, be sure to run sudo service lighttpd restart after this change has been made.


Setting up automatic updates on Ubuntu server

With Ubuntu 20.04 and later the unattended-upgrade should already be installed, but just to be sure you can run this code.

sudo apt install unattended-upgrades update-notifier-common

Next we’ll edit the unattended-upgrades config.

sudo nano /etc/apt/apt.conf.d/50unattended-upgrades

Find and remove the // in front of the following lines. On the automatic reboot time you may set whatever time you like. The default is 02:00.

// This option allows you to control if on a unclean dpkg exit
// unattended-upgrades will automatically run
//   dpkg --force-confold --configure -a
// The default is true, to ensure updates keep getting installed
Unattended-Upgrade::AutoFixInterruptedDpkg "true";

// Remove unused automatically installed kernel-related packages
// (kernel images, kernel headers and kernel version locked tools).
Unattended-Upgrade::Remove-Unused-Kernel-Packages "true";

// Do automatic removal of newly unused dependencies after the upgrade
Unattended-Upgrade::Remove-New-Unused-Dependencies "true";

// Do automatic removal of unused packages after the upgrade
// (equivalent to apt-get autoremove)
Unattended-Upgrade::Remove-Unused-Dependencies "true";

// Automatically reboot WITHOUT CONFIRMATION if
//  the file /var/run/reboot-required is found after the upgrade
Unattended-Upgrade::Automatic-Reboot "true";

// Automatically reboot even if there are users currently logged in
// when Unattended-Upgrade::Automatic-Reboot is set to true
Unattended-Upgrade::Automatic-Reboot-WithUsers "true";

// If automatic reboot is enabled and needed, reboot at the specific
// time instead of immediately
//  Default: "now"
Unattended-Upgrade::Automatic-Reboot-Time "02:00";

Type CTRL + X and then Y and enter to save the file.

Finally to enable the automatic upgrades, edit the 20auto-upgrades file as shown.

sudo nano /etc/apt/apt.conf.d/20auto-upgrades

By default this file has two lines as shown below.

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";

These lines allow you to determine how the upgrade will occur. The first line handles the update of the package lists while the second one initiates the automatic upgrades.

The value “1” enables the auto-update and the auto-upgrade respectively. If you want to disable it, set this value to “0”.

No changes are required here, just save and exit the file and then do a reboot before you continue.

sudo reboot