Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Raspberry Pi workshop - Pi-hole Network-Wide Ad Blocker

Introduction to Pi-hole and Network-Wide Ad Blocking

Welcome to this in-depth guide on setting up Pi-hole, a powerful network-wide ad blocker, using your Raspberry Pi. In today's digital age, online advertisements are ubiquitous. While some are harmless, many can be intrusive, track your online behavior, consume bandwidth, slow down page loading times, and even serve as vectors for malware. Pi-hole offers an elegant and effective solution to reclaim your browsing experience by blocking these ads at the network level, meaning all devices connected to your network can benefit without needing individual ad-blocking software.

This guide is designed for university students and anyone interested in learning about network-level ad blocking, DNS, and practical Raspberry Pi projects. We will delve deep into the concepts, provide verbose explanations, and guide you through hands-on workshops to solidify your understanding.

What is Pi-hole?

Pi-hole is a free, open-source software application that acts as a DNS sinkhole. It is designed to run on low-power devices like the Raspberry Pi. Its primary function is to block advertisements and internet trackers before they even reach your devices. Instead of relying on browser extensions that work on a per-device, per-browser basis, Pi-hole protects your entire network. This includes smartphones, tablets, smart TVs, gaming consoles, and any other device that connects to your home network.

The name "Pi-hole" comes from its common deployment on a Raspberry "Pi" and its function of sending unwanted domain requests into a "black hole," effectively preventing them from resolving.

How Pi-hole Works (DNS Sinkhole)

To understand Pi-hole, you first need a basic understanding of the Domain Name System (DNS). DNS is like the internet's phonebook. When you type a website address like www.example.com into your browser, your device needs to find the server's IP address (e.g., 93.184.216.34) to connect to it. Your device sends a DNS query to a DNS server, which then responds with the corresponding IP address.

Pi-hole integrates itself into this process. You configure your network (or individual devices) to use the Raspberry Pi running Pi-hole as their DNS server. Here’s a simplified step-by-step of what happens:

DNS Query Initiated:
Your device (e.g., laptop, smartphone) attempts to access a domain, say ads.annoyingcompany.com, which is embedded in a webpage you are visiting.
Query Sent to Pi-hole:
Instead of going to your ISP's DNS server or a public DNS server like Google's (8.8.8.8) directly, the DNS query is sent to your Pi-hole.
Pi-hole Checks Blocklists:
Pi-hole maintains lists of known ad-serving and tracking domains (these are called "blocklists" or "adlists"). It checks if ads.annoyingcompany.com is present in any of these lists.
Domain Blocked (Sinkholed):
- If the domain is found on a blocklist, Pi-hole "sinkholes" the request. This means it typically responds with a non-routable IP address (like 0.0.0.0 or the IP address of the Pi-hole itself, depending on the configuration) or an NXDOMAIN (Non-Existent Domain) response.
- Your device receives this response and, because it cannot connect to the ad server, the advertisement is not downloaded or displayed. The space where the ad would have appeared might be blank or simply not load.
Domain Allowed (Forwarded):
- If the domain is not on a blocklist (e.g., www.google.com), Pi-hole forwards the query to an upstream DNS resolver of your choice (like Google, Cloudflare, Quad9, or even your own recursive resolver like unbound).
- The upstream resolver finds the correct IP address and sends it back to Pi-hole.
- Pi-hole then relays this IP address back to your device.
- Your device connects to the intended website as usual.

This entire process happens very quickly, often in milliseconds, so it doesn't noticeably slow down your internet browsing. In fact, by blocking resource-heavy ads and trackers, it can often speed up page loading times.

Benefits of Using Pi-hole

Implementing Pi-hole on your network offers several significant advantages:

Network-Wide Blocking:
Protects all devices on your network without needing client-side software. This is especially useful for devices where ad-blockers are not easily installed, like smart TVs or IoT devices.
Improved Performance:
Web pages can load faster because browsers don't have to download and render ad content. This also saves bandwidth, which can be critical for users with metered internet connections.
Enhanced Privacy:
Blocks tracking domains, reducing the amount of data that advertisers and data brokers can collect about your online activities.
Reduced Malware Risk:
Some ads can be malicious (malvertising), leading to malware infections. Pi-hole can block the domains serving these malicious ads.
Increased Battery Life:
On mobile devices, less data downloaded means less processing and network activity, which can contribute to longer battery life.
Customizable:
You have full control over the blocklists. You can add more lists, create whitelists for domains you don't want blocked, and blacklist specific domains manually.
Educational:
Setting up and managing Pi-hole is a great way to learn about networking, DNS, Linux, and the Raspberry Pi itself.
Insightful Dashboard:
The web interface provides detailed statistics and logs about your network's DNS queries, showing you what's being blocked and which devices are making the most requests.

Limitations and Considerations

While Pi-hole is highly effective, it's important to be aware of its limitations:

DNS-Level Blocking Only:
Pi-hole blocks domains. It cannot block ads served from the same domain as the content (e.g., YouTube ads, Facebook sponsored posts, Twitch ads that are embedded directly). For these, browser extensions are still more effective.
"Broken" Websites:
Occasionally, overly aggressive blocklists might block domains required for a website or service to function correctly. This can usually be resolved by identifying and whitelisting the necessary domain(s) through the Pi-hole query log.
HTTPS Ads:
Pi-hole doesn't decrypt HTTPS traffic. It blocks based on the domain name request before the HTTPS connection is established. This is generally fine, as most ads are served from distinct domains.
Mobile Devices Off Your Network:
Pi-hole only protects devices when they are connected to your local network where Pi-hole is running. When your mobile devices are on cellular data or other Wi-Fi networks, they are not protected by your Pi-hole (unless you set up a VPN to route traffic through your home network).
Maintenance:
While generally low-maintenance, Pi-hole and the underlying Raspberry Pi OS will require occasional updates. Blocklists also benefit from periodic updates.
Single Point of Failure:
If your Raspberry Pi running Pi-hole goes down, your network might lose DNS resolution capabilities, effectively cutting off internet access for devices configured to use it. Redundancy can be set up (e.g., a second Pi-hole) but is more advanced.

Workshop Introduction to Network Traffic Analysis

Before we dive into setting up Pi-hole, let's get a feel for the kind of traffic our devices generate, especially concerning advertisements and trackers. This workshop will use your computer's built-in developer tools in a web browser.

Objective

To observe network requests made by a web page, specifically identifying requests related to advertisements and trackers.

Tools Needed:

A computer with a modern web browser (e.g., Chrome, Firefox, Edge).
An internet connection.

Steps:

Choose a Website:
Open your web browser and navigate to a website you know typically has a lot of advertisements. News websites or some free content sites are often good examples. For this workshop, let's try visiting a site like speedtest.net (which often has ads) or a major news outlet's homepage.
Open Developer Tools:
- Chrome/Edge:
  Right-click anywhere on the page and select "Inspect" or "Inspect Element." Alternatively, press Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (macOS).
- Firefox:
  Right-click anywhere on the page and select "Inspect" or "Inspect Element." Alternatively, press Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (macOS).
Navigate to the "Network" Tab:
In the developer tools panel that opens, look for a tab labeled "Network." Click on it.
Reload the Page:
With the Network tab open, reload the webpage you are on (press F5 or Ctrl+R / Cmd+R). You should see the Network tab populate with a list of all the resources the browser is fetching: HTML files, CSS stylesheets, JavaScript files, images, fonts, and, importantly, requests to third-party servers.
Analyze the Requests:
- Domain Column:
  Look at the "Domain" or "Host" column. You'll see requests to the primary domain of the website you're visiting, but also many requests to other domains.
- Identifying Ad/Tracker Domains:
  Try to spot domains that sound like they belong to advertising networks or analytics companies. Names like doubleclick.net, google-analytics.com, ads.pubmatic.com, scorecardresearch.com, adservice.google.com are common examples.
- Filter by Type:
  Some developer tools allow you to filter requests by type (e.g., JS, CSS, Img, XHR). You can also often use a filter box to search for keywords like "ad," "track," or parts of known ad-serving domains.
- Size and Time:
  Notice the size of some of these ad-related resources and the time they take to load. This contributes to page load times and bandwidth consumption.
(Optional) Use a Browser Ad Blocker for Comparison:
- If you have a browser-based ad blocker (like uBlock Origin), try enabling it and reloading the page with the Network tab still open.
- Observe the difference in the number of requests, particularly to third-party ad/tracker domains. Many of these should now be blocked or absent.

Observations and Learning:

You'll likely be surprised by the sheer number of requests made to third-party domains, many of which are for ads or tracking.
This exercise demonstrates visually what Pi-hole aims to prevent at a network level. Pi-hole would intercept the DNS lookups for these ad-serving domains and prevent your browser from even attempting to download their content.
Consider the privacy implications of so many different entities collecting data about your browsing habits.

This initial exploration should give you a better appreciation for the problem Pi-hole solves. In the following sections, we will guide you through setting up your Raspberry Pi and installing Pi-hole to block these unwanted requests for all devices on your network.

1. Prerequisites and Hardware Setup

Before we can embark on our Pi-hole journey, we need to gather the necessary hardware and software components. Ensuring you have the right tools from the outset will make the setup process smoother and more enjoyable. This section details everything you'll need and how to assemble your Raspberry Pi.

Required Hardware

The Raspberry Pi is a credit-card-sized computer that forms the heart of our Pi-hole setup. While various models exist, most are suitable for running Pi-hole, as it's not a very resource-intensive application.

Raspberry Pi (Model Recommendations)

Raspberry Pi 3B, 3B+, 4B, or 5:
These models offer a good balance of performance and features (like built-in Wi-Fi and Ethernet) for Pi-hole. They have enough processing power and RAM to handle DNS requests for a typical home network without issues.
- Raspberry Pi 4B/5:
  Offers more RAM options (2GB, 4GB, 8GB) and faster processing. While 1GB or 2GB is more than sufficient for Pi-hole, these models provide more headroom if you plan to run other services on the same Pi in the future. The Pi 5 is the latest and most powerful.
- Raspberry Pi 3B/3B+:
  Perfectly capable for Pi-hole. If you have one of these, it will work wonderfully.
Raspberry Pi Zero W/WH/2W:
These are smaller, lower-power models.
- Pi Zero W/WH:
  Can run Pi-hole, but performance might be slightly slower for very busy networks or if you have very large blocklists due to its single-core processor and less RAM. It connects via Wi-Fi (W model) or requires a USB Ethernet adapter.
- Pi Zero 2 W:
  A significant upgrade over the original Pi Zero W, featuring a quad-core processor. It's an excellent, power-efficient choice for Pi-hole, especially if you prefer a smaller form factor.
Older Models (Pi 1, Pi 2):
These can also run Pi-hole, but performance might be a limiting factor on busy networks. If you have one lying around, it's worth trying, but for a new purchase, a Pi 3 or newer is recommended.

For this workshop, any Raspberry Pi from the 3B onwards, or a Pi Zero 2 W, will provide an excellent experience. We generally recommend using a model with a built-in Ethernet port for the most stable network connection, although Wi-Fi can also work.

microSD Card (Size and Class Recommendations)

The microSD card acts as the hard drive for your Raspberry Pi, storing the operating system, Pi-hole software, and its logs.

Size:
- A 16GB card is generally sufficient for Pi-hole. Raspberry Pi OS Lite (which we'll recommend) doesn't take up much space, and Pi-hole itself is also lightweight.
- A 32GB card provides more breathing room for logs (especially if you enable extensive logging) and future projects.
- Larger cards (64GB+) are usually overkill for a dedicated Pi-hole but won't hurt.
Class/Speed:
- Class 10 / U1 / A1:
  This is the minimum recommended speed. A faster card (e.g., U3 / A2) can lead to quicker boot times and slightly snappier performance during OS operations like updates, but won't significantly impact Pi-hole's DNS resolution speed once it's running.
- Endurance:
  Consider a "High Endurance" microSD card if available and within budget. These cards are designed for constant read/write operations (like logging) and tend to last longer in such applications, reducing the risk of card corruption. However, a good quality standard card is usually fine, especially if you manage logging settings.

Recommendation:

A reputable brand (SanDisk, Samsung, Kingston, etc.) 16GB or 32GB Class 10/U1/A1 microSD card.

Power Supply

The Raspberry Pi is sensitive to its power supply. Using an inadequate or unstable power supply is a common source of problems, leading to instability, SD card corruption, and unexpected reboots.

Official Raspberry Pi Power Supply:
This is highly recommended as it's designed specifically for the Pi model you have and guarantees the correct voltage and amperage.
Third-Party Power Supply:
If using a third-party supply, ensure it meets the requirements for your Pi model:
- Raspberry Pi 5:
  Requires a 5V, 5A USB-C power supply (preferably one supporting Power Delivery if you intend to use power-hungry peripherals).
- Raspberry Pi 4B:
  Requires a 5V, 3A USB-C power supply.
- Raspberry Pi 3B/3B+:
  Requires a 5V, 2.5A Micro USB power supply.
- Raspberry Pi Zero W/WH/2W:
  Requires a 5V, 1.2A-2A Micro USB power supply (though the Pi 3B+'s 2.5A supply will work fine).

Do not use a standard smartphone charger unless you verify its output specifications match your Pi's requirements. Many phone chargers don't provide stable enough power or sufficient amperage, especially under load.

Ethernet Cable (Recommended) or Wi-Fi Dongle

For a DNS server like Pi-hole, a stable network connection is crucial.

Ethernet Cable:
This is the highly recommended option. A wired connection is generally more reliable, faster, and has lower latency than Wi-Fi. Connect the Raspberry Pi directly to your router or a network switch. Any standard Cat 5e or Cat 6 Ethernet cable will do.
Wi-Fi Dongle:
If your Raspberry Pi model doesn't have built-in Wi-Fi (e.g., some older Pi 1 or Pi 2 models, or if you want to use a different Wi-Fi adapter than the built-in one) or if a wired connection is absolutely impossible, you can use Wi-Fi.
- Most newer Pis (3B, 3B+, 4B, 5, Zero W, Zero 2 W) have built-in Wi-Fi.
- If you need a dongle, ensure it's compatible with Raspberry Pi OS.

Note: While Wi-Fi can work, any instability in the Wi-Fi connection can lead to DNS resolution failures for your entire network. An Ethernet connection is strongly preferred for reliability.

(Optional) Case for Raspberry Pi

A case is not strictly necessary for functionality but is highly recommended:

Protection:
Protects the Raspberry Pi from physical damage, dust, and accidental short circuits (e.g., from loose metallic objects).
Aesthetics:
Keeps your setup tidy.
Cooling:
Some cases come with heat sinks or even small fans, which can be beneficial for more powerful models like the Pi 4B or Pi 5, especially if they are in an enclosed space or running multiple services. Pi-hole itself is not very CPU-intensive, so passive cooling (heat sinks) is usually sufficient for Pi 3/4 models. The Pi 5 generally benefits from active cooling.

There are many types of cases available, from simple plastic enclosures to more elaborate ones with active cooling. Choose one that fits your Pi model and preferences.

Required Software

You'll need a few software tools on your main computer (Windows, macOS, or Linux) to prepare the microSD card and connect to the Raspberry Pi.

Raspberry Pi Imager

This is the official tool from the Raspberry Pi Foundation for writing operating system images to microSD cards. It's user-friendly and available for Windows, macOS, and Ubuntu.

Download:
Get it from the official Raspberry Pi website: https://www.raspberrypi.com/software/

SSH Client

SSH (Secure Shell) is a network protocol that allows you to securely access and control your Raspberry Pi remotely from another computer over the network. This is how we'll do most of the configuration, so you won't need a dedicated monitor, keyboard, or mouse connected to the Pi after the initial setup (this is called running it "headless").

Windows:
- PuTTY:
  A popular free SSH client. (Download: https://www.putty.org/)
- Windows PowerShell / Command Prompt:
  Modern versions of Windows 10/11 have a built-in OpenSSH client. You can simply type ssh in PowerShell or Command Prompt.
macOS:
The Terminal app (found in /Applications/Utilities/) has a built-in SSH client.
Linux:
Most Linux distributions have a built-in SSH client available in the terminal.

Web Browser

You'll need a web browser (Chrome, Firefox, Edge, Safari, etc.) to access the Pi-hole web admin interface once it's installed.

Assembling Your Raspberry Pi

If you bought your Raspberry Pi as a bare board, you might need to do some minimal assembly.

(If using a case):
Check the instructions for your specific case. Some cases require you to place the Pi inside before or after attaching heat sinks.
(If using heat sinks):
Many Raspberry Pi kits come with small adhesive heat sinks for the main CPU and sometimes other chips (like the RAM or USB controller).
- Ensure the surface of the chips is clean (use an isopropyl alcohol wipe if necessary and let it dry).
- Peel the backing off the adhesive tape on the heat sink.
- Carefully align and press the heat sink onto the corresponding chip. Apply gentle, firm pressure for a few seconds.
- For a Raspberry Pi 4B/5, the largest chip is the CPU, and it definitely benefits from a heat sink.
Insert the Raspberry Pi into its Case (if applicable):
Follow the case instructions. Usually, it involves snapping the Pi into place or securing it with small screws. Ensure ports are aligned correctly with the openings in the case.
Do NOT insert the microSD card yet.
We will prepare it with the OS in the next section.
Do NOT connect the power supply yet.

Your Raspberry Pi is now physically assembled and ready for the software setup.

Workshop Verifying Your Hardware Components

This workshop is a simple checklist and familiarization exercise to ensure you have everything ready before proceeding.

Objective:

To physically inspect and confirm all necessary hardware components for the Pi-hole setup.

Materials:

Your Raspberry Pi board
microSD card
Power supply for your Pi model
Ethernet cable (if using a wired connection)
(Optional) Raspberry Pi case
(Optional) Heat sinks

Steps:

Unpack and Inspect the Raspberry Pi:
- Carefully take the Raspberry Pi out of its anti-static bag.
- Visually inspect the board for any obvious physical damage (e.g., bent pins, broken components). It's rare, but good to check.
- Identify the key components:
  - CPU (the largest black square chip, usually centrally located)
  - RAM (often a chip near or under the CPU on some models)
  - USB ports
  - Ethernet port (if your model has one)
  - HDMI port(s)
  - Power input connector (Micro USB or USB-C)
  - microSD card slot (usually on the underside of the board)
  - GPIO pins (the row(s) of pins along one edge – we won't use these for Pi-hole, but good to know what they are).
Inspect the microSD Card:
- Confirm its capacity (e.g., 16GB, 32GB) and speed class (e.g., Class 10, U1, A1).
- Ensure it's a microSD card, not a full-size SD card (though many come with an adapter).
Inspect the Power Supply:
- Verify that the connector type matches your Raspberry Pi (Micro USB or USB-C).
- Check the output rating printed on the power supply (e.g., 5V, 3A). Confirm it meets the requirements for your specific Raspberry Pi model. Using an underpowered supply is a common source of instability.
Inspect the Ethernet Cable:
- Ensure it's an Ethernet cable (RJ45 connectors) and not a phone cable (RJ11 - smaller connector).
- Check that the cable is not visibly damaged (e.g., frayed, broken clips).
(If using) Inspect the Case and Heat Sinks:
- Ensure the case is designed for your specific Raspberry Pi model (e.g., a Pi 3 case won't fit a Pi 4 due to port layout changes).
- If you have heat sinks, identify which chip each one is for (usually the largest for the CPU).
Prepare Your Workspace:
- Choose a clean, well-lit, static-free area to work.
- Have your main computer (for imaging the SD card) nearby.

Confirmation:

By the end of this workshop, you should have:

Positively identified all your hardware components.
Confirmed compatibility (e.g., power supply voltage/amperage, case model).
A basic understanding of where key parts are on the Raspberry Pi.

This simple check helps prevent issues down the line, such as trying to use an incompatible power supply or discovering a component is missing. With your hardware verified, you're ready to prepare the operating system.

2. Preparing the Operating System for Raspberry Pi

With the hardware ready, the next crucial step is to install an operating system (OS) onto the microSD card. The Raspberry Pi Foundation provides its own official OS, Raspberry Pi OS (formerly known as Raspbian), which is a derivative of Debian Linux. This OS is optimized for the Raspberry Pi hardware and is the recommended choice for most projects, including Pi-hole.

Understanding Raspberry Pi OS

Raspberry Pi OS comes in a few variations, primarily differing in the included software and whether they have a graphical desktop environment.

Raspberry Pi OS Lite vs. Desktop

Raspberry Pi OS with desktop environment:
This version includes a full graphical user interface (GUI), similar to what you'd find on a Windows or macOS computer. It comes with pre-installed applications like a web browser, office suite, programming tools, and games. While user-friendly for general desktop use, the GUI consumes more system resources (CPU, RAM, disk space).
Raspberry Pi OS Lite:
This version is a minimal image without a desktop environment. Interaction with the OS is done entirely through the command-line interface (CLI). This makes it much more lightweight:
- Smaller download size:
  Faster to download.
- Less disk space usage:
  Leaves more space on the microSD card for your applications and data.
- Lower resource consumption:
  Uses less RAM and CPU, which is ideal for a server application like Pi-hole that runs continuously in the background.
- Reduced attack surface:
  Fewer installed packages and running services can mean fewer potential security vulnerabilities.

Why Lite is Preferred for Pi-hole

For running Pi-hole, Raspberry Pi OS Lite is highly recommended. Here's why:

Efficiency:
Pi-hole runs as a background service and doesn't require a graphical interface. The resources saved by not running a desktop environment can be better utilized by Pi-hole or other services you might run.
Stability:
Server applications benefit from a lean OS. Fewer components mean fewer potential points of failure or conflict.
Headless Operation:
We will be managing the Raspberry Pi remotely via SSH. A desktop environment on the Pi itself is unnecessary for this. The Pi-hole admin interface is web-based and accessed from any browser on your network.
Learning:
Working with the command line is a valuable skill for anyone interested in Linux, servers, or more advanced computing.

While you can install Pi-hole on the desktop version of Raspberry Pi OS, the Lite version is the more professional and efficient choice for this type of application.

Downloading Raspberry Pi Imager

The easiest and recommended way to write Raspberry Pi OS to your microSD card is by using the Raspberry Pi Imager.

Go to the official Raspberry Pi software page: https://www.raspberrypi.com/software/
Download the Raspberry Pi Imager for your operating system (Windows, macOS, or Ubuntu).
Install the Imager on your computer by running the downloaded installer and following the on-screen prompts.

Choosing Your Raspberry Pi OS Image

When you open Raspberry Pi Imager, you'll be able to select the OS.

Click on "CHOOSE OS".
Select "Raspberry Pi OS (other)".
You will see options like:
- "Raspberry Pi OS Lite (32-bit)"
- "Raspberry Pi OS Lite (64-bit)"
- (And the full desktop versions)

32-bit vs. 64-bit:

For Pi-hole, Raspberry Pi OS Lite (32-bit) is perfectly adequate and often recommended for maximum compatibility and slightly lower memory usage on Pis with less RAM (like the Pi Zero W or older models). It works on all Raspberry Pi models capable of running Pi-hole.
Raspberry Pi OS Lite (64-bit) can be used if you have a 64-bit capable Raspberry Pi (Pi 3, Pi 4, Pi 5, Zero 2 W). For Pi-hole itself, the performance difference is negligible. However, if you plan to run other 64-bit specific applications on the same Pi in the future, choosing the 64-bit OS might be beneficial. For simplicity and broad compatibility for just Pi-hole, 32-bit Lite is a safe bet.

For this guide, we will proceed with Raspberry Pi OS Lite (32-bit) unless you have a specific reason to choose 64-bit.

Writing the OS to the microSD Card using Raspberry Pi Imager

This is where the Raspberry Pi Imager shines with its user-friendly interface.

Standard OS Installation

Insert microSD Card:
Insert your microSD card into an SD card reader connected to your computer. If your microSD card came with an adapter, you might need to use that.
Launch Raspberry Pi Imager:
Open the Raspberry Pi Imager application.
Choose Raspberry Pi Device (Optional but Recommended):
- Click "CHOOSE DEVICE".
- Select your specific Raspberry Pi model (e.g., "Raspberry Pi 4", "Raspberry Pi Zero 2 W"). This helps the Imager suggest compatible OS versions. If your model isn't listed, you can choose "No filtering".
Choose Operating System:
- Click "CHOOSE OS".
- Navigate to "Raspberry Pi OS (other)".
- Select "Raspberry Pi OS Lite (32-bit)" (or your preferred version).
Choose Storage:
- Click "CHOOSE STORAGE".
- Select your microSD card from the list. Be very careful here! Make sure you select the correct drive, as all data on the selected drive will be erased. The Imager usually shows the drive size, which can help you identify it.
(Optional but Highly Recommended) Pre-configuring Advanced Options:
Before clicking "WRITE", click the gear icon (⚙️) in the bottom-right corner of the Imager window. This opens the "Advanced options" menu, which is extremely useful for a headless setup:
- Set hostname:
  - Check the box.
  - Enter a hostname for your Pi. For example, pihole. This will make it accessible on your network as pihole.local (if your network supports mDNS/Bonjour). Default is raspberrypi.
- Enable SSH:
  - Check the box.
  - Select "Use password authentication".
- Set username and password:
  - Check the box.
  - The default username for Raspberry Pi OS is pi. It's strongly recommended to change this default username for better security. For example, you could use admin or a custom username.
  - Enter a strong password and confirm it. Do not use the default password "raspberry" if you don't change the username pi. Remember this password; you'll need it to log in.
- Configure wireless LAN (Optional):
  - If you plan to use Wi-Fi (and your Pi has Wi-Fi capabilities), check this box.
  - Enter your Wi-Fi network name (SSID).
  - Enter your Wi-Fi password.
  - Select your "Wireless LAN country" (important for regulatory compliance and channel selection).
  - Note: Even if you configure Wi-Fi here, we still recommend using Ethernet for Pi-hole if possible.
- Set locale settings:
  - Check the box.
  - Set your Time zone (e.g., Europe/London, America/New_York).
  - Set your Keyboard layout (e.g., us, gb).
- Persistent settings:
  - "Play sound when finished": Optional.
  - "Eject media when finished": Recommended, checked by default.
  - "Enable telemetry": Your choice. This sends anonymous usage data to the Raspberry Pi Foundation.
After configuring these advanced options, click "SAVE".
Write the Image:
- You are now back on the main Imager screen. Double-check that the OS and Storage selections are correct.
- Click the "WRITE" button.
- A warning will appear stating that all existing data on the selected storage device will be erased. Confirm that you've selected the correct drive and click "YES".
Writing and Verifying:
The Imager will now download the OS image (if not already cached), write it to the microSD card, and then verify the write. This process can take several minutes depending on the speed of your microSD card, internet connection (for download), and computer. Be patient.
Completion:
Once finished, the Imager will display a success message. You can now safely remove the microSD card from your computer.

Your microSD card is now flashed with Raspberry Pi OS Lite and pre-configured for headless SSH access!

Disk Preparation Architectures

For most Pi-hole users running on a microSD card, the standard single partition setup created by Raspberry Pi Imager is sufficient. However, it's good to be aware of other possibilities, especially regarding microSD card longevity and more complex setups.

Standard Single Partition (Default)

When Raspberry Pi Imager writes the OS, it typically creates two main partitions on the microSD card:

Boot Partition (/boot or /boot/firmware on newer OS versions): A small FAT32 partition containing the bootloader, kernel, and other files needed to start the Raspberry Pi. This partition is accessible by Windows, macOS, and Linux.
Root Partition (/): A larger ext4 (Linux filesystem) partition containing the main operating system, user files, applications (like Pi-hole), and logs. Windows cannot read ext4 partitions natively, but macOS and Linux can.

Pros:

Simplicity:
Easiest to set up; handled automatically by the Imager.
Sufficient for Pi-hole:
Pi-hole doesn't have extreme disk I/O requirements that necessitate complex partitioning.

Cons:

microSD Card Wear:
Constant writing of logs (if extensive logging is enabled) to the same partition as the OS can, over a very long time, contribute to wear on that area of the microSD card. This is a general concern with microSD cards, not specific to this layout.
Data Recovery:
If the root filesystem gets corrupted, recovering data can be more challenging if everything is on one partition.

Separate Partitions for OS and Data (e.g., logs)

An advanced approach involves creating separate partitions, for instance, one for the OS (/) and another for variable data like Pi-hole logs (/var/log) or perhaps the entire Pi-hole configuration directory (/etc/pihole).

Why Consider This?

Isolating Writes: If logs are written to a separate partition, it might help distribute wear on the microSD card, though the card's internal wear-leveling algorithms also play a significant role.
Easier OS Reinstallation: If you need to reinstall the OS, you could potentially do so while preserving the data on the separate partition (though backups are always better).
Filesystem Choice: You could theoretically use different filesystems or mount options for the data partition if needed (e.g., optimized for many small writes), but this is usually overkill for Pi-hole.

How to achieve this (conceptual steps, quite advanced for initial setup):

After initial OS installation, boot the Pi.
Use tools like fdisk or gparted (from another Linux system or by booting the Pi with a live USB OS) to shrink the root partition and create a new partition in the freed space. This is risky and can lead to data loss if not done carefully.
Format the new partition (e.g., as ext4).
Modify /etc/fstab to mount this new partition to the desired directory (e.g., /var/log or a custom data directory). This would involve moving existing data from /var/log to the new partition before mounting.

Pros:

Potentially better organization and wear distribution (debatable with modern microSD wear leveling).
Can make it easier to manage disk space for logs separately.

Cons:

Complexity:
Significantly more complex to set up and manage. Not recommended for beginners.
Risk of Errors:
Mistakes during partitioning can render the system unbootable.
Marginal Benefit for Pi-hole:
The actual benefit in terms of microSD card lifespan for a typical Pi-hole setup is often minimal compared to the added complexity. Good quality cards and sensible logging settings are more practical.

Using an External USB Drive for Logs/Data

A more practical approach to reduce wear on the microSD card, especially if you're concerned about log writes, is to mount an external USB flash drive or SSD and direct logs or other write-heavy data there.

Benefits for microSD Card Longevity:

USB flash drives (especially good quality ones) or small SSDs are generally more robust for frequent writes than typical microSD cards.
The OS on the microSD card experiences far fewer write operations, potentially extending its life.

How to achieve this (simplified steps):

Connect a USB drive to the Raspberry Pi.
Identify the USB drive (e.g., sudo fdisk -l might show it as /dev/sda1).
Format the USB drive (e.g., as ext4: sudo mkfs.ext4 /dev/sda1).
Create a mount point: sudo mkdir /mnt/usblogdrive.
Mount the drive: sudo mount /dev/sda1 /mnt/usblogdrive.
To make it permanent, add an entry to /etc/fstab. Use the drive's UUID for reliability (find with sudo blkid /dev/sda1). Example /etc/fstab entry: UUID=<your-drive-uuid> /mnt/usblogdrive ext4 defaults,nofail 0 2 (The nofail option is important so the Pi still boots if the USB drive is not connected).
Configure Pi-hole (or other services) to write logs to a directory on this mounted drive. For Pi-hole, you might need to:
- Stop Pi-hole FTL: sudo service pihole-FTL stop
- Move existing logs: sudo mv /var/log/pihole* /mnt/usblogdrive/ (and potentially sudo mv /var/log/lighttpd /mnt/usblogdrive/ if Lighttpd logs are also a concern)
- Create symbolic links: sudo ln -s /mnt/usblogdrive/pihole.log /var/log/pihole.log sudo ln -s /mnt/usblogdrive/pihole-FTL.log /var/log/pihole-FTL.log (And similarly for other log files or directories if desired).
- Alternatively, some applications allow configuring the log path directly. Pi-hole's FTL has a LOGFILE setting in /etc/pihole/pihole-FTL.conf.

Pros:

Significantly reduces write operations on the microSD card.
External drives can offer more storage space for extensive logging if needed.
Relatively straightforward to implement compared to re-partitioning the SD card.

Cons:

Requires an external USB drive (added cost and physical component).
The Pi needs to reliably mount the USB drive on boot. nofail in fstab helps, but physical connection issues could still occur.
Slightly more complex than the default setup.

Considerations for Hibernation

Hibernation (suspend-to-disk) is a power-saving state where the contents of RAM are saved to a persistent storage (like a hard drive or SSD), and the computer is then powered off. When turned back on, it restores its state from the saved image.

What is Hibernation? As described, it saves system state to disk and powers down.
Why it's usually not used/needed for servers like Pi-hole:
- Always-On Requirement: Pi-hole is a DNS server. For your network to have internet connectivity (or at least name resolution), Pi-hole needs to be running continuously. Hibernating it would make it unavailable, breaking DNS for your network.
- Low Power Consumption: Raspberry Pis are already very power-efficient. The energy savings from hibernating a Pi running only Pi-hole would be minimal and not worth the service interruption.
- Complexity: Setting up hibernation on Linux, especially on embedded devices like the Raspberry Pi, can be complex and isn't a standard feature.
Swap Space vs. Hibernation Partition:
- Swap Space: This is a portion of disk space used by the OS as virtual RAM when physical RAM is full. Raspberry Pi OS may create a small swap file by default. It's for active memory management, not for hibernation.
- Hibernation Partition/File: For hibernation, a dedicated swap partition or a sufficiently large swap file (at least the size of your RAM) is typically required to store the RAM image.

In summary for Pi-hole: Do not plan for or attempt to use hibernation. Pi-hole is intended to be an always-on service. The focus should be on reliable, continuous operation.

Recommendation for Pi-hole:

Stick with the standard single partition setup for simplicity, especially if you are new to Raspberry Pi or Linux. If microSD card longevity is a major concern long-term, consider redirecting logs to a USB drive later. For most users, a good quality microSD card will last for years running Pi-hole with default logging.

Workshop Preparing Your microSD Card with Raspberry Pi OS Lite

This workshop will guide you step-by-step through using Raspberry Pi Imager to flash Raspberry Pi OS Lite onto your microSD card, including the crucial pre-configuration steps.

Objective:

To create a bootable microSD card with Raspberry Pi OS Lite, configured for headless SSH access, a custom hostname, user, and (optionally) Wi-Fi.

Materials:

Computer with Raspberry Pi Imager installed.
microSD card (16GB or larger recommended).
microSD card reader.

Steps:

Connect microSD Card: Insert your microSD card into the card reader connected to your computer. Note the drive letter or name assigned to it by your OS (but be cautious, as we'll select it within Imager).
Launch Raspberry Pi Imager: Open the Raspberry Pi Imager application you installed earlier.
Select Raspberry Pi Model (Optional but good practice):
- Click the "CHOOSE DEVICE" button.
- A list of Raspberry Pi models will appear. Select the specific model you are using (e.g., "Raspberry Pi 4", "Raspberry Pi Zero 2 W"). If unsure or your exact sub-model isn't listed, you can skip this or choose a generic family member. This step mainly helps filter the OS list.
Select Operating System:
- Click the "CHOOSE OS" button.
- In the menu that appears, select "Raspberry Pi OS (other)".
- From the sub-menu, select "Raspberry Pi OS Lite (32-bit)". (If you have a strong reason and a compatible Pi, you can choose 64-bit, but 32-bit is fine for all.)
Select Storage:
- Click the "CHOOSE STORAGE" button.
- A list of available storage devices will appear. Carefully select your microSD card. Verify by its name and size. Choosing the wrong drive will erase its contents!
Configure Advanced Options (Crucial for Headless Setup):
- Before proceeding to write, click the gear icon (⚙️) located in the bottom-right corner of the Imager window. This opens the "Advanced options" dialog.
- Image customization options: Choose "to always use" or "for this session only". "For this session only" is fine.
- Set hostname:
  - Check the box: Set hostname
  - In the text field, enter pihole (or another hostname you prefer, like my-pi). Add .local to the end of the hostname you chose, so e.g. pihole.local. This will be the name your Pi uses on the network.
- Enable SSH:
  - Check the box: Enable SSH
  - Ensure "Use password authentication" is selected.
- Set username and password:
  - Check the box: Set username and password
  - Username: Change the default pi. Enter a new username, for example, rpadmin or your preferred admin username. Avoid using pi for better security.
  - Password: Enter a strong, unique password for this user. Re-enter it in the "Confirm password" field. Memorize this password or store it securely. You will need it to log in.
- Configure wireless LAN (Only if you MUST use Wi-Fi):
  - If you intend to use Wi-Fi for your Pi-hole (Ethernet is strongly recommended), check the box: Configure wireless LAN
  - SSID: Enter the name of your Wi-Fi network accurately.
  - Password: Enter your Wi-Fi password.
  - Wireless LAN country: Select your country from the dropdown list. This is important for regulatory reasons and correct Wi-Fi channel usage.
  - If you are using Ethernet, leave this section unchecked.
- Set locale settings:
  - Check the box: Set locale settings
  - Time zone: Select your correct time zone from the list (e.g., America/Los_Angeles, Europe/Berlin).
  - Keyboard layout: Select your keyboard layout (e.g., us, gb, de). This is important for typing correctly in the command line later.
- Click the "SAVE" button to apply these advanced options.
Review Selections and Start Writing:
- You will be back on the main Imager screen.
- Triple-check your selections:
  - Operating System: Should be "Raspberry Pi OS Lite (32-bit)" (or your choice).
  - Storage: Should be your microSD card.
- Click the "WRITE" button.
Confirm Overwrite:
- A warning dialog will appear: "All existing data on 'Your SD Card Name' will be erased. Are you sure you want to continue?"
- Verify again that this is indeed your microSD card.
- If you are absolutely sure, click "YES".
Writing and Verifying Process:
- Raspberry Pi Imager will now:
  1. Download the OS image (if it's the first time or an update is available).
  2. Write the image to the microSD card.
  3. Verify the written data.
- This process will take some time (5-20 minutes typically, depending on microSD card speed and your computer). Do not remove the card or close the Imager during this process. You'll see a progress bar.
Completion:
- Once the process is complete, you'll see a message like "Write Successful." It might also say something like "You can now remove the SD card from the reader."
- Click "CONTINUE". You can now close Raspberry Pi Imager.
- Safely eject the microSD card from your computer (use the "Eject" function in your OS if available, or wait a few seconds after the Imager says it's done).

Outcome:

You now have a microSD card with Raspberry Pi OS Lite installed. It's pre-configured with:

A custom hostname (e.g., pihole.local).
SSH enabled.
A custom user and password for SSH login.
(Optional) Wi-Fi credentials.
Correct locale and keyboard settings.

This card is ready to be inserted into your Raspberry Pi for its first boot! The pre-configuration significantly simplifies the initial setup, as we can directly connect via SSH without needing to attach a monitor or keyboard to the Pi.

3. Initial Raspberry Pi Configuration

With Raspberry Pi OS Lite successfully written to the microSD card and pre-configured with SSH enabled, we're ready to boot up the Pi for the first time and perform some essential initial configurations. This will all be done "headless" – without a monitor, keyboard, or mouse directly connected to the Raspberry Pi – using SSH from your main computer.

Booting Up Your Raspberry Pi for the First Time

Ensure Raspberry Pi is Powered Off: If you previously had it powered on for any reason, ensure it's completely off (disconnect the power supply).
Insert the microSD Card: Carefully insert the microSD card (that you just prepared) into the microSD card slot on your Raspberry Pi. It usually clicks into place or fits snugly. Ensure it's oriented correctly (typically, the contacts on the card face the contacts on the Pi's board).
Connect Network Cable (Highly Recommended): Connect one end of your Ethernet cable to the Raspberry Pi's Ethernet port and the other end to a free LAN port on your router or network switch. This provides the most stable network connection.
- If you configured Wi-Fi in Raspberry Pi Imager and are not using Ethernet, the Pi should attempt to connect to your Wi-Fi network automatically on boot.
Connect Power Supply: Connect the appropriate power supply to your Raspberry Pi's power input port (Micro USB or USB-C). Then, plug the power supply into a wall outlet.
Observe LEDs: The Raspberry Pi should now boot up. You'll typically see LEDs on the Pi light up:
- A red LED (PWR) indicates the Pi is receiving power. It should be solid.
- A green LED (ACT) indicates microSD card activity. It will flicker a lot during boot and then more intermittently once booted. If it doesn't flash at all, or flashes in a specific pattern, it might indicate a boot problem (e.g., SD card issue, power issue).
Wait for Boot: Allow the Raspberry Pi a few minutes to boot up for the first time. The initial boot can take a bit longer as it might resize the filesystem and perform other first-run tasks. For Raspberry Pi OS Lite, this is usually 1-2 minutes.

Finding Your Raspberry Pi's IP Address

To connect to your Raspberry Pi via SSH, you need to know its IP address on your local network. Here are a few common methods to find it:

Router's DHCP Client List

This is often the most reliable method if you have access to your router's administration interface.

Access Your Router's Admin Page: Open a web browser on a computer connected to your network and enter your router's IP address. Common router IPs are 192.168.1.1, 192.168.0.1, or 10.0.0.1. If you don't know it, check your computer's network settings (look for "Default Gateway").
Log In: Enter the username and password for your router. This is often printed on a sticker on the router itself or was provided by your ISP.
Find DHCP Client List: Look for a section named "DHCP List," "Client List," "Connected Devices," "LAN Status," or similar. The exact naming varies greatly between router manufacturers.
Identify Your Raspberry Pi: In the list of connected devices, look for the hostname you set in Raspberry Pi Imager (e.g., pihole). If the hostname isn't displayed, you might need to identify it by its MAC address (though this is harder to find without logging into the Pi first). The Pi should have acquired an IP address from your router via DHCP. Note down this IP address (e.g., 192.168.1.123).

Network Scanning Tools

If you can't access your router's admin page or if the hostname isn't showing up, you can use a network scanning tool.

nmap (Linux/macOS/Windows): A powerful command-line network scanner.
- First, find your network range. On Windows, open Command Prompt and type ipconfig. Look for your "IPv4 Address" and "Subnet Mask." On macOS/Linux, open Terminal and type ip addr or ifconfig.
- If your IP is 192.168.1.X and subnet is 255.255.255.0, your network is likely 192.168.1.0/24.
- Run: nmap -sn 192.168.1.0/24 (replace with your network).
- Look for entries. If SSH is enabled, nmap might identify it as a Linux device or show port 22 open.
Advanced IP Scanner (Windows): A free, user-friendly GUI tool. Download and run it. It will scan your network and list connected devices, often identifying them by manufacturer (look for "Raspberry Pi Foundation").
Fing (Mobile App - iOS/Android): A popular network scanning app for smartphones. Connect your phone to the same Wi-Fi network as the Pi and run a scan.

Using mDNS (if enabled and supported)

If you set a hostname like pihole.local in Raspberry Pi Imager, and your operating system (on your main computer) and network support mDNS (Multicast DNS, also known as Bonjour on Apple devices or Avahi on Linux), you might be able to connect using the hostname directly:

Try pinging it: ping pihole.local (replace pihole with the hostname you set).
If it resolves to an IP address, that's your Pi's IP.

This method is convenient but not always reliable, as it depends on mDNS working correctly across your network and client OS.

Connecting via SSH

Once you have the Raspberry Pi's IP address (or if hostname.local works), you can connect to it using an SSH client.

Enabling SSH (if not done via Imager)

If you didn't enable SSH through the Raspberry Pi Imager's advanced options, you would traditionally need to:

Remove the microSD card from the Pi (after shutting it down).
Insert it into your computer.
Create an empty file named ssh (no extension) in the boot partition of the microSD card.
Eject the card, put it back in the Pi, and boot up. However, since we used the Imager's advanced option, SSH should already be enabled.

Using an SSH Client

Username: The username you set in Raspberry Pi Imager (e.g., rpadmin).
Password: The password you set for that user.
IP Address: The IP address you found for your Raspberry Pi.
Hostname: Or, pihole.local (if mDNS works).

Windows (using PowerShell / Command Prompt with built-in OpenSSH):

Open PowerShell or Command Prompt.
Type the command: ssh your_username@your_pi_ip_address
- Example: ssh rpadmin@192.168.1.123
- Or: ssh rpadmin@pihole.local
The first time you connect, you'll see a message about the authenticity of the host: The authenticity of host '192.168.1.123 (192.168.1.123)' can't be established. ECDSA key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Are you sure you want to continue connecting (yes/no/[fingerprint])?
Type yes and press Enter. This saves the Pi's SSH key fingerprint to your computer, so you won't be asked again (unless the Pi's OS is reinstalled or its key changes).
You will then be prompted for the password: rpadmin@192.168.1.123's password:
Type your password and press Enter. Note: The password will not be displayed on screen as you type it (not even asterisks). This is normal.
If the username and password are correct, you'll be logged into the Raspberry Pi's command line, and you'll see a prompt like rpadmin@pihole:~ $.

Windows (using PuTTY):

Open PuTTY.
In the "Host Name (or IP address)" field, enter the Pi's IP address (e.g., 192.168.1.123) or hostname (pihole.local).
Ensure "Port" is 22 and "Connection type" is SSH.
You can optionally save the session details: enter a name in "Saved Sessions" (e.g., "My Pi-hole") and click "Save".
Click "Open".
The first time, a PuTTY Security Alert about the server's host key not being cached will appear. Click "Accept" (or "Yes" depending on the version) to trust the key and connect.
A terminal window will open, prompting login as:. Type your username (e.g., rpadmin) and press Enter.
Then, it will prompt rpadmin@192.168.1.123's password:. Type your password and press Enter (it won't show).

macOS/Linux (using Terminal):

Open Terminal.
Type the command: ssh your_username@your_pi_ip_address
- Example: ssh rpadmin@192.168.1.123
- Or: ssh rpadmin@pihole.local
The first-time connection process (authenticity of host, typing yes, password prompt) is the same as described for Windows PowerShell.

You are now successfully connected to your Raspberry Pi via SSH!

First Boot Configuration (`sudo raspi-config`)

Even though we pre-configured some settings using Raspberry Pi Imager, it's good practice to run raspi-config, the Raspberry Pi's command-line configuration tool, to verify settings and make any other necessary adjustments.

On the Raspberry Pi's command line (via your SSH session), type: sudo raspi-config

You'll see a blue screen menu. Navigate using the arrow keys, Tab key, and Enter key. Select "Finish" to exit.

Key options to check/configure:

System Options:
- S1 Password: If you used the default username pi and didn't change its password via the Imager, do it now! This option allows you to change the current user's password. Since we created a custom user with a custom password, this step might not be strictly necessary if you're confident with the password you set, but it's here if you need it.
- S3 Boot / Auto Login: Ensure "B1 Console" or "B2 Console Autologin" (if you want it to log in automatically to the console for the specified user, generally not recommended for security on a server) is selected. "Desktop" options are not relevant for Lite. For a server, "B1 Console" (requiring login) is usually preferred.
- S4 Hostname: We already set this via Imager. You can verify it here.
- S5 Wireless LAN: If you need to configure or change Wi-Fi settings and didn't do it via Imager, you can do it here.
Interface Options (Legacy option, now mostly under "Interface Options" or "Advanced Options" in newer raspi-config):
- I2 SSH: We already enabled this. You can verify it's enabled.
- Other interfaces (Camera, SPI, I2C, etc.) are not needed for Pi-hole.
Performance Options (May not be present or relevant for all Pi models/OS versions):
- P2 GPU Memory: For Raspberry Pi OS Lite (no desktop), the GPU needs very little memory. You can usually reduce this to the minimum (e.g., 16MB) to free up more RAM for the system. However, modern Raspberry Pi OS versions manage this well, and it's often not necessary to tweak for Pi-hole. If you do change it, a reboot is required.
Localisation Options:
- L1 Locale: Ensure your locale is set correctly (e.g., en_US.UTF-8 UTF-8 or en_GB.UTF-8 UTF-8). If not set via Imager, you can configure it here. This affects language and character encoding.
- L2 Timezone: We set this via Imager. Verify it's correct. Accurate time is important for logs and scheduled tasks.
- L3 Keyboard: We set this via Imager. Verify your keyboard layout.
- L4 WLAN Country: We set this via Imager if using Wi-Fi. Verify.
Advanced Options:
- A1 Expand Filesystem: This ensures that the OS can use all the space on your microSD card. On recent versions of Raspberry Pi OS and with Imager, this is usually done automatically on the first boot. If you see this option and suspect it hasn't run, selecting it won't hurt. It will tell you if it's already been done.
- Other options here are generally not needed for Pi-hole.

After making any changes in raspi-config, navigate to <Finish> and press Enter. It might ask if you want to reboot. If you changed significant settings like GPU memory or expanded the filesystem, a reboot is a good idea. Select <Yes>. Your SSH session will disconnect. Wait a minute or two for the Pi to reboot, then SSH back in.

Updating the System (`sudo apt update && sudo apt upgrade -y`)

It's crucial to update your Raspberry Pi's software packages to the latest versions. This ensures you have the latest security patches and bug fixes.

In your SSH session, run the following commands:

Update the package list: sudo apt update This command downloads the latest list of available software packages from the repositories defined in your system.
Upgrade installed packages: sudo apt upgrade -y This command upgrades all currently installed packages to their newest versions based on the list fetched by apt update.
- sudo: Executes the command with superuser (administrator) privileges, which is necessary for installing/updating system software.
- apt: Advanced Package Tool, Debian's package manager.
- upgrade: The command to upgrade packages.
- -y: Automatically answers "yes" to any prompts during the upgrade process, making it non-interactive.

This process might take some time, especially if there are many updates. You'll see text scrolling as packages are downloaded and installed.

Once completed, your Raspberry Pi OS will be up-to-date. It's a good idea to run these two commands periodically (e.g., monthly) to keep your system current. Sometimes, an upgrade might suggest a reboot; if so, you can reboot using sudo reboot.

Workshop Securely Accessing and Updating Your Raspberry Pi

This workshop consolidates the steps of finding your Pi's IP, connecting via SSH, and performing the initial system update.

Objective:

To successfully connect to the Raspberry Pi via SSH using the pre-configured credentials, navigate raspi-config to verify settings, and update the operating system.

Prerequisites:

Raspberry Pi booted with the microSD card prepared in the previous workshop.
Raspberry Pi connected to your local network (Ethernet recommended).
Your main computer connected to the same network.
SSH client installed on your main computer.
The username and password you set for the Pi.

Steps:

Power On and Wait: Ensure your Raspberry Pi is powered on and has had a couple of minutes to boot fully.
Find Your Raspberry Pi's IP Address:
- Attempt 1 (Router DHCP List): Log in to your router's admin interface. Look for a "DHCP Clients" or "Connected Devices" list. Find the device with the hostname you set (e.g., pihole). Note its IP address.
- Attempt 2 (mDNS): Open a terminal or command prompt on your main computer. Try pinging pihole.local (or whatever hostname you set, followed by .local). ping pihole.local If you get replies, note the IP address shown.
- Attempt 3 (Network Scanner): If the above fail, use a tool like Advanced IP Scanner (Windows), nmap (all platforms), or Fing (mobile) to scan your network for the Raspberry Pi's IP address.
Connect via SSH:
- Open your SSH client (Terminal on macOS/Linux, PowerShell or PuTTY on Windows).
- Use the command: ssh your_username@PI_IP_ADDRESS (e.g., ssh rpadmin@192.168.1.105 or ssh rpadmin@pihole.local)
- If it's your first connection to this Pi, accept the host key by typing yes when prompted.
- Enter the password you set for your user when prompted. Remember, it won't display as you type.
- You should now see the command prompt of your Raspberry Pi (e.g., rpadmin@pihole:~ $).
Run raspi-config (Optional Check):
- Type sudo raspi-config and press Enter.
- Navigate to "Localisation Options".
  - Check "L2 Timezone" – ensure it matches your actual timezone.
  - Check "L3 Keyboard" – ensure it matches your keyboard layout.
- Navigate to "Advanced Options".
  - Select "A1 Expand Filesystem". It will likely tell you the filesystem is already expanded. This is just a check.
- You don't need to change anything if your Imager settings were correct.
- Select <Finish> using the arrow keys and press Enter. If it asks to reboot and you didn't change anything critical, you can select <No>.
Update System Packages:
- At the Raspberry Pi's command prompt, execute: sudo apt update
- Wait for it to complete. It will fetch package information.
- Then execute: sudo apt full-upgrade -y (Using full-upgrade is generally preferred over just upgrade as it can also remove obsolete packages if necessary during an upgrade, providing a cleaner update. For most routine updates, upgrade is fine, but full-upgrade is more thorough.)
- This step may take several minutes, depending on your internet speed and the number of updates. Let it run until the command prompt returns.
(Optional but Recommended) Reboot After Major Updates:
- If many packages were updated, especially kernel or system-critical ones, it's a good idea to reboot. sudo reboot
- Your SSH session will close. Wait 1-2 minutes for the Pi to restart, then SSH back in using the same command as in Step 3.

Outcome:

You have successfully logged into your Raspberry Pi headlessly.
You've verified key configurations.
Your Raspberry Pi OS is now up-to-date with the latest software patches.

Your Raspberry Pi is now in a healthy, secure, and updated state, ready for the next step: configuring a static IP address, which is crucial for Pi-hole.

4. Understanding Static IP Addressing

For any server application that other devices on your network need to reliably connect to, using a static (fixed) IP address is essential. Pi-hole, acting as your network's DNS server, is no exception. This section explains why a static IP is necessary and details the methods to configure one for your Raspberry Pi.

Why Pi-hole Needs a Static IP Address

When your devices (computers, phones, etc.) are configured to use Pi-hole for DNS, they need to know Pi-hole's IP address. By default, most home networks use DHCP (Dynamic Host Configuration Protocol). The DHCP server (usually running on your router) assigns IP addresses to devices automatically when they join the network. These IP addresses are "leased" for a certain period and can change over time (e.g., after a reboot of the device or router, or when the lease expires).

If your Raspberry Pi's IP address changes, your devices will no longer be able to find it to send their DNS queries. This would mean:

Ads would no longer be blocked.
Worse, your devices might lose internet connectivity altogether because they can't resolve any domain names.

Therefore, the Raspberry Pi running Pi-hole must have an IP address that does not change. This is known as a static IP address.

Methods for Assigning a Static IP

There are two primary methods to ensure your Raspberry Pi has a static IP address:

Method 1: Setting a Static IP on the Raspberry Pi Itself
- You manually configure the network interface on the Raspberry Pi to use a specific IP address, subnet mask, gateway, and DNS server(s).
Method 2: DHCP Reservation on Your Router
- You configure your router's DHCP server to always assign the same specific IP address to your Raspberry Pi, based on its unique MAC (Media Access Control) address.

Which method is better?

DHCP Reservation (Method 2) is generally recommended for home networks if your router supports it reliably. It centralizes IP address management on your router, is often easier to set up for less technical users, and avoids potential IP conflicts if you're not careful with manual assignment.
Setting a static IP on the Pi itself (Method 1) gives you direct control on the device and doesn't rely on the router behaving correctly for reservations. It's a perfectly valid method, especially if your router's DHCP reservation feature is unreliable or difficult to configure.

Important Consideration:

The static IP address you choose for the Pi-hole must be within your local network's IP range but outside the range of IP addresses automatically assigned by your router's DHCP server.

For example, if your router's IP is 192.168.1.1 and its DHCP server assigns IPs from 192.168.1.100 to 192.168.1.200, you could choose a static IP like 192.168.1.53 for your Pi-hole (DNS traditionally uses port 53, so using an IP ending in .53 is a common, though not required, convention).
Check your router's DHCP settings to find its range. Pick an IP address outside this dynamic pool but within the same subnet (e.g., if the router is 192.168.1.1, your Pi's static IP should also start with 192.168.1.x).

We will detail both methods. Choose the one that suits you best.

Method 1 Setting a Static IP on the Raspberry Pi Itself

This involves editing the dhcpcd.conf file on your Raspberry Pi. dhcpcd is the DHCP client daemon used by Raspberry Pi OS to manage network configurations.

Before you start:

Identify your network details:
- Current IP address of the Pi: You can find this with ip addr show eth0 (for Ethernet) or ip addr show wlan0 (for Wi-Fi). Note this down.
- Gateway IP address: This is usually your router's IP address. Find it with ip route | grep default.
- DNS Server IP address(es): These are the DNS servers your Pi currently uses (likely your router's IP or your ISP's DNS). Find it with cat /etc/resolv.conf. You'll eventually point this to Pi-hole itself or a public DNS for the Pi's own lookups. For initial setup, using your router's IP or a public DNS like 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare) is fine.
- The static IP address you want to assign to the Pi: Choose one as discussed above (within your network range, outside DHCP pool). For this example, let's assume we want to set the Pi's IP to 192.168.1.53. Assume your router/gateway is 192.168.1.1.

Steps:

SSH into your Raspberry Pi.
Edit the dhcpcd.conf file:
Use a command-line text editor like nano: sudo nano /etc/dhcpcd.conf
Add the static IP configuration:
Scroll to the end of the file. You might see some commented-out examples. Add your configuration.
- For an Ethernet connection (eth0):
```
interface eth0
static ip_address=192.168.1.53/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1 8.8.8.8
```
- For a Wi-Fi connection (wlan0):
```
interface wlan0
static ip_address=192.168.1.53/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1 8.8.8.8
```
Explanation of parameters:
- interface eth0 (or interface wlan0): Specifies which network interface this configuration applies to. Use eth0 for wired Ethernet, wlan0 for wireless.
- static ip_address=192.168.1.53/24:
  - 192.168.1.53: The static IP address you want to assign to your Pi. Replace this with your chosen IP.
  - /24: This is CIDR notation for the subnet mask. /24 corresponds to 255.255.255.0. This is very common for home networks. If your network uses a different subnet mask, adjust accordingly (e.g., /16 for 255.255.0.0).
- static routers=192.168.1.1: This is your gateway IP address (your router's IP). Replace with your router's IP.
- static domain_name_servers=1.1.1.1 8.8.8.8: These are the DNS servers the Raspberry Pi itself will use for its own lookups.
  - Important: When Pi-hole is installed, it will act as a DNS server. For the Pi-hole device itself, you generally don't want to point it to its own Pi-hole IP address (127.0.0.1 or its static IP) in dhcpcd.conf initially, as this can create a loop if Pi-hole isn't fully functional yet or if FTL is down.
  - It's safer to point it to external DNS servers (like Cloudflare's 1.1.1.1 and 1.0.0.1, Google's 8.8.8.8 and 8.8.4.4, or Quad9's 9.9.9.9) or your router's IP address (if your router forwards DNS).
  - You can list multiple DNS servers separated by spaces.
  - Later, once Pi-hole is running and stable, you can configure Pi-hole (in its own settings) to use upstream DNS servers, and some advanced users might point the Pi's system resolver to 127.0.0.1 (localhost) after Pi-hole is fully set up and uses different upstream servers. But for initial static IP setup, use external IPs here.
Save and Exit:
- In nano, press Ctrl+X.
- It will ask "Save modified buffer?". Press Y.
- It will then ask "File Name to Write: /etc/dhcpcd.conf". Press Enter.
Reboot the Raspberry Pi:
For the changes to take effect reliably, reboot the Pi: sudo reboot Your SSH session will disconnect.
Verify the New Static IP:
- Wait for the Pi to reboot (1-2 minutes).
- Try to SSH into the Pi using the new static IP address you configured (e.g., ssh rpadmin@192.168.1.53).
- If you can connect, log in and verify the IP: ip addr show eth0 (or wlan0). You should see the static IP you set.
- Also, check internet connectivity from the Pi: ping google.com. If it works, your gateway and DNS settings are correct.

Method 2 DHCP Reservation on Your Router

This method involves telling your router to always give the same IP address to your Raspberry Pi. This is often preferred as it keeps IP address management centralized.

Before you start:

Find your Raspberry Pi's MAC Address: The MAC address is a unique hardware identifier for your Pi's network interface (Ethernet or Wi-Fi).
- If your Pi is currently connected to the network, you can find its MAC address from your router's DHCP client list (it's often displayed alongside the IP address).
- Alternatively, SSH into your Pi (using its current dynamic IP) and type:
  - For Ethernet: ip link show eth0 (Look for link/ether xx:xx:xx:xx:xx:xx)
  - For Wi-Fi: ip link show wlan0 (Look for link/ether yy:yy:yy:yy:yy:yy)
- Note down the correct MAC address (e.g., b8:27:eb:12:34:56).
Choose the IP Address: Decide on the static IP address you want to assign (e.g., 192.168.1.53), ensuring it's within your network range but outside the router's DHCP pool.

Steps:

Access Your Router's Admin Interface: Open a web browser and log in to your router's configuration page (e.g., 192.168.1.1).
Find DHCP Reservation / Static Lease Section:
- The location of this setting varies greatly between router models and firmware. Look for terms like:
  - "DHCP Reservation"
  - "Static DHCP Leases"
  - "Address Reservation"
  - "LAN IP Setup"
  - "Client List" (sometimes you can make a reservation from here)
- It's usually under "LAN Settings," "Network Settings," or "DHCP Server Settings." You may need to consult your router's manual or search online for "DHCP reservation [your router model]".
Create the Reservation:
- You'll typically need to provide:
  - MAC Address: Enter the MAC address of your Raspberry Pi's network interface (the one you'll be using for Pi-hole, usually Ethernet).
  - Desired IP Address: Enter the static IP address you've chosen for the Pi (e.g., 192.168.1.53).
  - (Optional) Description/Name: Some routers let you add a name for the reservation (e.g., "Pi-hole").
- Add or save the new reservation entry.
Apply Changes and Reboot Router/Pi (if necessary):
- Save the settings on your router. Some routers apply changes immediately, while others might require a reboot of the router itself.
- To ensure the Raspberry Pi picks up the new reserved IP, it's a good idea to reboot the Pi: sudo reboot (via SSH, using its current IP before the reboot).
Verify the New Reserved IP:
- Wait for the Pi to reboot.
- It should now obtain the reserved IP address from the router.
- Check your router's client list again to see if the Pi now has the reserved IP.
- Try to SSH into the Pi using the new reserved IP address (e.g., ssh rpadmin@192.168.1.53).
- If you can connect, log in and verify: ip addr show eth0 (or wlan0).

Pros and Cons of Each Method

Method 1: Static IP on Pi

Pros:
- Full control on the Pi itself.
- Works even if the router's DHCP reservation is flaky or unavailable.
- No dependency on the router for this specific setting.
Cons:
- Risk of IP conflict if you accidentally choose an IP that's in the DHCP pool or already used by another static device, and you don't manage your IP range carefully.
- If you change your network's IP scheme (e.g., move from 192.168.1.x to 192.168.0.x), you must manually update the Pi's configuration.
- Slightly more complex to set up initially for beginners.

Method 2: DHCP Reservation on Router

Pros:
- Centralized IP management on the router.
- Easier to avoid IP conflicts, as the router manages assignments.
- If you change the Pi (e.g., swap SD card to a new Pi), as long as the new Pi uses the same MAC address (e.g., by using the same Ethernet interface) or you update the reservation with the new MAC, it can get the same IP. (Note: MAC addresses are unique to hardware).
- Generally simpler for non-technical users if the router interface is clear.
Cons:
- Relies on the router's DHCP server and reservation feature working correctly. Some consumer routers have buggy implementations.
- If the router is replaced or reset to factory defaults, you'll need to reconfigure the reservation.
- Requires access to router admin settings.

Recommendation:

For most home users, DHCP reservation (Method 2) is slightly preferred for its simplicity and centralized management IF your router supports it well. If not, or if you prefer direct control, setting the static IP on the Pi (Method 1) is perfectly reliable.

Choose one method, not both! If you configure a static IP on the Pi and a DHCP reservation for the same MAC address to a different IP, you can create network conflicts or unpredictable behavior. If you use Method 1, ensure the chosen static IP is outside your router's DHCP assignment pool.

Workshop Configuring a Static IP for Your Raspberry Pi

In this workshop, we will practice Method 1: Setting a Static IP on the Raspberry Pi itself. This method gives us direct control and is a good learning exercise. If you strongly prefer Method 2 (DHCP Reservation) and are comfortable with your router's interface, you can opt to do that instead, but follow these steps to understand the manual process.

Objective:

To configure a static IP address for your Raspberry Pi's Ethernet interface.

Prerequisites:

Raspberry Pi booted, updated, and accessible via SSH using its current (likely dynamic) IP address.
Knowledge of your:
- Desired static IP for the Pi (e.g., 192.168.1.53 - choose one appropriate for your network and outside your router's DHCP pool).
- Router's IP address (Gateway) (e.g., 192.168.1.1).
- A public DNS server IP (e.g., 1.1.1.1 or 8.8.8.8).

Let's assume for this workshop:

Your chosen static IP for Pi: 192.168.1.53
Your router/gateway IP: 192.168.1.1
Subnet mask: 255.255.255.0 (which is /24 in CIDR)
Public DNS for Pi's own use: 1.1.1.1 (Cloudflare) and 8.8.8.8 (Google) as a secondary.
We are configuring the Ethernet interface (eth0).

Steps:

Connect via SSH:
SSH into your Raspberry Pi using its current IP address. ssh your_username@CURRENT_PI_IP_ADDRESS
Gather Network Information (If you haven't already):
- Verify current Ethernet interface name (usually eth0): ip addr (look for eth0)
- Find your current gateway: ip route | grep default (e.g., default via 192.168.1.1 dev eth0)
- Note your current DNS servers (for reference, though we'll set new ones): cat /etc/resolv.conf
Backup dhcpcd.conf (Good Practice):
Before editing critical configuration files, it's wise to make a backup. sudo cp /etc/dhcpcd.conf /etc/dhcpcd.conf.backup
Edit dhcpcd.conf: sudo nano /etc/dhcpcd.conf
Add Static IP Configuration:
Scroll to the very end of the file. Add the following lines, adjusting the IP addresses and interface name (eth0 or wlan0) as necessary for your setup:
```
# Static IP configuration for Pi-hole (Ethernet)
interface eth0
static ip_address=192.168.1.53/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1 8.8.8.8
```
- Double-check:
  - interface eth0: Ensure this is your active wired interface. If using Wi-Fi, it would be wlan0, and you'd also need Wi-Fi credentials configured higher up in this file (or via raspi-config / Imager).
  - static ip_address=192.168.1.53/24: Replace 192.168.1.53 with your chosen static IP for the Pi, and /24 if your subnet mask is different (though /24 is common).
  - static routers=192.168.1.1: Replace 192.168.1.1 with your router's IP address.
  - static domain_name_servers=1.1.1.1 8.8.8.8: You can keep these or use other public DNS servers.
Save and Exit Nano:
- Press Ctrl+X.
- Press Y to confirm saving.
- Press Enter to confirm the filename.
Reboot the Raspberry Pi:
sudo reboot Your SSH session will disconnect.
Verification:
- Wait 1-2 minutes for the Pi to reboot.
- Important: You must now try to SSH using the NEW STATIC IP ADDRESS you just configured. ssh your_username@192.168.1.53 (Replace with your chosen static IP and username).
- If the SSH connection is successful, log in.
- Verify the IP address settings: ip addr show eth0 Look for the inet line under eth0. It should display 192.168.1.53/24 (or your configured IP).
- Verify gateway: ip route | grep default Should show your router's IP as the default gateway.
- Verify DNS settings for the Pi itself (this reflects what dhcpcd configured): cat /etc/resolv.conf You should see nameserver 1.1.1.1 and nameserver 8.8.8.8 (or whatever you set in dhcpcd.conf).
- Test internet connectivity from the Pi: ping -c 4 google.com You should get successful replies. If not, re-check your dhcpcd.conf settings (IP, gateway, DNS) for typos. If you made a mistake and can't connect, you might need to connect a monitor and keyboard or re-image the SD card if you can't fix it via SSH using the old IP (which might briefly work if dhcpcd failed to apply the static config). This is why backing up dhcpcd.conf was a good idea – you could revert if needed via a recovery method.

Troubleshooting:

Cannot SSH to the new IP:
- Double-check the IP you typed in the SSH command.
- Ensure the Pi has fully rebooted.
- Temporarily connect a monitor and keyboard to the Pi if possible, log in locally, and check ip addr. Correct any typos in /etc/dhcpcd.conf.
- If you made a typo in dhcpcd.conf that broke networking, you might need to remove the SD card, mount its root partition on another Linux machine (or use a tool that can read ext4 on Windows/Mac), and edit /etc/dhcpcd.conf there to fix it or restore the backup.
SSH works, but no internet (ping google.com fails):
- The static routers (gateway) IP in dhcpcd.conf might be wrong.
- The static domain_name_servers IPs in dhcpcd.conf might be wrong or unreachable.

Outcome:

Your Raspberry Pi should now have a fixed, static IP address. This is a critical prerequisite for installing Pi-hole, as other devices on your network will need to be pointed to this unchanging address for DNS resolution.

5. Installing Pi-hole

With your Raspberry Pi set up, updated, and assigned a static IP address, you're now ready to install the Pi-hole software itself. Pi-hole provides a convenient one-step automated installation script that makes the process very straightforward. We'll walk through running this script and understanding the choices you'll make during its interactive setup wizard.

Pre-installation Checks

Before running the installer, let's quickly verify a few things:

System Up-to-date: You should have already done this in a previous step (sudo apt update && sudo apt full-upgrade -y). If not, do it now.
Static IP Configured: Confirm your Raspberry Pi is using the static IP address you set up in the previous section. ip addr show eth0 (or wlan0)
Curl Installed: The installation script is typically downloaded using curl. Raspberry Pi OS Lite usually includes it, but let's make sure. sudo apt install curl -y If it's already installed, it will say so. Otherwise, it will be installed.
Sudo Access: You'll need sudo privileges to run the installer, which your custom user (e.g., rpadmin) should have.

The One-Step Automated Install Script

Pi-hole's developers provide an officially recommended installation script. This script automates the process of downloading necessary packages, configuring system settings, and setting up Pi-hole.

The command to download and execute the script is: curl -sSL https://install.pi-hole.net | bash

Let's break down this command:

curl: A command-line tool for transferring data with URLs.
-sSL: Options for curl:
- -s or --silent: Silent mode. Don't show progress meter or error messages (script handles its own output).
- -S or --show-error: If an error occurs in silent mode, show it.
- -L or --location: Follow redirects. If the URL has moved, curl will follow to the new location.
https://install.pi-hole.net: The official URL where the installation script is hosted.
|: This is a "pipe." It sends the output of the command on its left (curl ...) as input to the command on its right (bash).
bash: The Bourne Again SHell, a common command-line interpreter. This part of the command executes the script that curl downloads.

Understanding the Script's Actions (Transparency):

Piping a script directly from the internet into bash executes it immediately. While the Pi-hole script is widely trusted and open source, it's good practice to understand what you're running. If you're cautious, you can inspect the script before running it:

Download the script first: curl -sSL https://install.pi-hole.net -o pihole_install.sh
Inspect its contents: less pihole_install.sh (Use arrow keys to scroll, q to quit) Or open it in a text editor.
If you're satisfied, make it executable and run it: sudo chmod +x pihole_install.sh sudo ./pihole_install.sh

For this guide, we'll proceed with the direct pipe method as it's standard practice for Pi-hole and the script is well-vetted by the community.

Walking Through the Installation Wizard

Once you execute the installation command, the script will run and present you with a series of dialog boxes (using a tool called whiptail) to guide you through the configuration. Use the Arrow keys to navigate, Spacebar to select/deselect options (like checkboxes), and Enter to confirm choices.

Here's a breakdown of the typical installation steps and choices:

Welcome Screen / Installer Confirmation:
- The script will display an initial screen stating that it will install Pi-hole.
- Press Enter to continue.
Donation Information:
- A screen will mention that Pi-hole is free but relies on donations.
- Press Enter to continue.
Static IP Address Needed:
- The installer will warn you that Pi-hole needs a static IP address. We have already configured this in the previous section.
- Press Enter to continue.
Choose an Upstream DNS Provider(s):
- Pi-hole needs to forward legitimate (non-blocked) DNS queries to an upstream DNS server. You'll be presented with a list of popular public DNS providers:
  - Google
  - Cloudflare
  - OpenDNS
  - Quad9 (offers malware blocking, an good choice)
  - Norton
  - Comodo
  - And often an option for "Custom" if you want to specify IP addresses not listed.
- Considerations:
  - Privacy: Some users prefer providers like Cloudflare (1.1.1.1) or Quad9 (9.9.9.9) due to their strong privacy policies compared to others.
  - Performance/Speed: Proximity to the DNS server can affect speed. Most major providers have global networks, so performance is generally good.
  - Filtering: Some providers like Quad9 offer built-in malware blocking at the DNS level, which can be an added layer of security. OpenDNS also offers filtering options (though these are configured at OpenDNS, not Pi-hole).
  - DNS over HTTPS (DoH) / DNS over TLS (DoT): Pi-hole itself, by default, sends plain DNS (port 53) queries to these upstream providers. However, you can later configure Pi-hole to use a local DoH/DoT proxy (like cloudflared or unbound in forwarding mode with DoT) to encrypt these upstream queries. For now, just pick from the list. We can enhance this later.
- Recommendation: Cloudflare (1.1.1.1, 1.0.0.1) or Quad9 (9.9.9.9, 149.112.112.112) are excellent choices for privacy and security. You can select one or more. If you select multiple, Pi-hole may use them in a specific order or algorithm.
- Use the arrow keys to highlight your choice(s), press Spacebar to select (an * will appear), and then Tab to <Ok> and press Enter.
Selecting Block Lists (Adlists):
- Pi-hole uses lists of ad-serving domains. The installer will offer to include one or more well-known, maintained lists.
- It's generally recommended to accept the default selected list(s). These are usually good starting points.
- You can always add more blocklists or remove existing ones later through the Pi-hole web interface.
- Press Enter to continue with the selected lists.
Select IP Protocols to Block (IPv4 and/or IPv6):
- The installer will ask if you want Pi-hole to block ads over IPv4, IPv6, or both.
- If your network and ISP support IPv6, and your devices use it, you should enable IPv6 blocking.
- If you're unsure or know you don't use IPv6 extensively, enabling only IPv4 is fine. You can change this later.
- Recommendation: Select both IPv4 and IPv6 if you're unsure, as it provides the most comprehensive coverage.
- Use Spacebar to select/deselect and Enter to confirm.
Confirm Static IP Address Settings:
- The installer will attempt to detect your current IP address and gateway. It will ask if you want to use these settings for Pi-hole's static IP configuration.
- Since we manually configured a static IP address in /etc/dhcpcd.conf earlier, the displayed IP address should be the static IP you set. Verify this.
- The Gateway should also be correct (your router's IP).
- Select <Yes> to confirm these settings are correct.
- If the displayed IP is not the static IP you intended, select <No> and it will prompt you to enter the IP address and gateway manually. However, it's better to have this correctly set at the OS level before running the Pi-hole installer.
IP Address Conflict Warning:
- A warning may appear if the installer detects that the chosen IP address is also being handed out by a DHCP server. This is a reminder to ensure your Pi-hole's static IP is outside your router's DHCP range. We already considered this.
- Press Enter to acknowledge.
Install Web Admin Interface and Lighttpd:
- Pi-hole comes with a web-based administration interface that allows you to view stats, manage lists, and configure settings.
- The installer will ask if you want to install the web admin interface. Select <On> (Yes).
- It will also ask if you want to install the lighttpd web server (a lightweight web server) and required PHP modules, which are necessary for the web interface to function. Select <On> (Yes). This is highly recommended.
- Press Enter to continue.
Logging Queries:
- The installer will ask if you want to log DNS queries.
  - Log queries (Recommended): This allows you to see which domains are being requested, which are blocked, and helps in troubleshooting (e.g., if a site is broken, you can see what domain was blocked and whitelist it). It also populates the dashboard statistics.
  - Do not log queries: Provides slightly more privacy as no record of your DNS queries is kept by Pi-hole. However, this severely limits the usefulness of the dashboard and troubleshooting capabilities.
  - Anonymous mode: Logs queries but anonymizes client IP addresses. A compromise between logging and privacy.
- Recommendation: For most users, especially when starting, select "Log queries" (<On>). You can change the logging level later via the web interface if privacy becomes a greater concern.
- Press Enter.
Select Privacy Level for FTL Statistics:
- FTL (Faster Than Light) is Pi-hole's DNS resolver and statistics engine. You'll be asked to choose a privacy level for the information displayed in the Query Log and dashboard. The options usually range from:
  - 0: Show everything: Displays full domain names, client IPs. Most detailed.
  - 1: Hide domains: Domains are hidden/anonymized.
  - 2: Hide domains and clients: Both domains and client IPs are hidden/anonymized.
  - 3: Anonymous mode: Extensive anonymization.
  - 4: Disabled (no statistics): Similar to not logging queries.
- Recommendation: Start with Level 0: Show everything. This provides the most information for learning how Pi-hole works and for troubleshooting. You can adjust this later in Pi-hole's settings (Settings > Privacy).
- Press Enter.
Installation Process:
- The script will now download and install all the necessary packages and configure Pi-hole. You'll see a lot of text scrolling by as it works. This may take a few minutes.
Installation Complete!:
- Once finished, you'll see an "Installation Complete!" screen.
- Crucially, this screen will display:
  - Your Pi-hole's IPv4 and (if enabled) IPv6 address(es).
  - The URL to access the web admin interface (e.g., http://192.168.1.53/admin or http://pihole.local/admin).
  - Your web admin interface password. This password is randomly generated and displayed only once here. Write it down immediately and store it securely! You will need it to log in to the admin interface.
- Press Enter to finish the installer.

You are now back at the command prompt. Pi-hole should be installed and running!

Important:

Note down the web admin password shown on the final installation screen. If you miss it, you can reset it later using the command pihole -a -p from the Raspberry Pi's terminal, but it's best to capture it now.

Workshop Installing Pi-hole Software

This workshop will guide you through running the Pi-hole installation script and making the recommended choices.

Objective:

To install Pi-hole on your Raspberry Pi using the official installation script.

Prerequisites:

Raspberry Pi with Raspberry Pi OS Lite, updated, and configured with a static IP address.
SSH access to your Raspberry Pi.
curl installed (sudo apt install curl -y).

Steps:

SSH into Your Raspberry Pi: ssh your_username@YOUR_PI_STATIC_IP (e.g., ssh rpadmin@192.168.1.53)
Execute the Pi-hole Installation Script:
At the Raspberry Pi's command prompt, type or paste the following command and press Enter: curl -sSL https://install.pi-hole.net | sudo bash (Note: The Pi-hole documentation sometimes shows bash and sometimes sudo bash. Since the script itself will use sudo for many operations, running the initial bash command with sudo ensures it has permissions from the start. If it complains, try without sudo first, as the script internally escalates privileges when needed.) The official simple command is: curl -sSL https://install.pi-hole.net | bash - the script will prompt for sudo password if needed, or if you run it as a user that has passwordless sudo, it will proceed. Let's use the official simple one.

curl -sSL https://install.pi-hole.net | bash
Follow the On-Screen Installer (Recap of Choices):
- Installer Welcome: Press Enter.
- Donation Info: Press Enter.
- Static IP Needed: Press Enter.
- Upstream DNS Provider:
  - Use arrow keys to navigate.
  - Press Spacebar to select/deselect.
  - Recommended: Select Cloudflare or Quad9. (You can select one by highlighting and pressing space, then Tab to <Ok>, then Enter). For this workshop, let's choose Cloudflare.
  - Press Tab to move to <Ok> and press Enter.
- Block Lists:
  - The default "StevenBlack's unified hosts list" is usually pre-selected. This is a good list.
  - Ensure it's selected (or select any you prefer).
  - Press Tab to <Ok> and press Enter.
- IP Protocols:
  - Ensure both IPv4 and IPv6 are selected (marked with [*]).
  - Press Tab to <Ok> and press Enter.
- Static IP Address Confirmation:
  - The installer should display the static IP address you configured for your Pi (e.g., 192.168.1.53/24) and your Gateway (e.g., 192.168.1.1).
  - Verify these are correct.
  - Select <Yes> and press Enter.
- IP Conflict Warning: Press Enter.
- Web Admin Interface:
  - "Install Web Admin Interface?" -> Select <On> and press Enter.
- Web Server (lighttpd):
  - "Install lighttpd webserver and PHP modules?" -> Select <On> and press Enter.
- Log Queries:
  - "Enable query logging?" -> Select <On> and press Enter.
- Privacy Level for FTL:
  - "Select a privacy mode for FTL statistics": -> Select Show everything (usually the first option, 0).
  - Press Tab to <Ok> and press Enter.
Wait for Installation: The script will now install packages. This will take a few minutes.
Installation Complete - CRITICAL STEP:
- When you see the "Installation Complete!" screen:
  - Locate the Admin Webpage address: It will look like http://192.168.1.53/admin/
  - Locate the Webpage login password: It will be a random string of characters.
  - WRITE DOWN THIS PASSWORD IMMEDIATELY AND ACCURATELY. Store it in a safe place (e.g., your password manager). You will not be shown this password again.
  - Example output:
```
Your Pi-hole is installed and running!
...
Web interface password: (a_random_password_here)
...
Access the web interface via:
http://192.168.1.53/admin
http://pihole.local/admin
```
- Once you have recorded the password, press Enter to exit the installer.
(Optional) Change Web Admin Password (If you missed it or want to set your own):
If you missed the password or want to change it to something memorable (though a random strong password is more secure), you can do so now from the Pi's command line: sudo pihole -a -p It will prompt you to enter a new password twice.

Outcome:

Pi-hole is now installed and running on your Raspberry Pi! You have the URL and password for the web admin interface. The next step is to configure your network devices (or your router) to use your Pi-hole as their DNS server.

6. Configuring Network Devices to Use Pi-hole

Now that Pi-hole is installed and running on your Raspberry Pi with a static IP address, the final crucial step is to tell your network devices to use it as their DNS server. There are two main approaches:

Router-Level Configuration (Recommended): Configure your router's DHCP settings to hand out the Pi-hole's IP address as the DNS server to all devices that connect to your network. This provides network-wide ad blocking automatically.
Device-Level Configuration: Manually configure the DNS settings on individual devices (e.g., your computer, smartphone) to point to the Pi-hole's IP address. This is useful for testing or if you only want specific devices to use Pi-hole.

The Pi-hole's IP address is the static IP you configured for it (e.g., 192.168.1.53).

Option 1 Router-Level Configuration (Recommended for Network-Wide Blocking)

This is the most convenient method as it applies Pi-hole to all devices on your network that obtain their network settings via DHCP from your router, without needing to configure each device individually.

Steps:

Access Your Router's Admin Interface:
- Open a web browser on a computer connected to your network.
- Enter your router's IP address (e.g., 192.168.1.1, 192.168.0.1).
- Log in with your router's administrator username and password.
Find DNS Settings within DHCP Configuration:
- The location of DNS settings varies significantly between router manufacturers and models. You are looking for DNS settings related to the DHCP server on your router.
- Look for sections like:
  - "LAN Setup"
  - "Network Settings"
  - "DHCP Server"
  - "Advanced Settings" -> "LAN" or "DHCP"
- Within these sections, you should find fields for "DNS Server 1" (or "Primary DNS") and "DNS Server 2" (or "Secondary DNS").
- Important: You want to change the DNS server addresses that your router gives out to DHCP clients, not the DNS servers that the router itself uses for its own internet connectivity (often called "WAN DNS" or "Internet DNS"). Some routers combine these, while others separate them. If unsure, consult your router's manual.
Change the DHCP DNS Server to Pi-hole's IP Address:
- In the DHCP DNS server settings on your router:
  - Set DNS Server 1 (Primary DNS) to your Pi-hole's static IP address (e.g., 192.168.1.53).
  - What about DNS Server 2 (Secondary DNS)?
    - Option A (Single Pi-hole, Most Common): Leave the Secondary DNS field blank or, if your router requires an entry, enter 0.0.0.0 (if accepted) or re-enter your Pi-hole's IP address. Do NOT put a public DNS server (like 8.8.8.8) in the secondary slot here. If you do, some devices or operating systems might bypass Pi-hole and use the secondary DNS server directly, thus seeing ads. The goal is to force all DNS traffic through Pi-hole.
    - Option B (Dual Pi-holes for Redundancy): If you have set up a second Pi-hole for redundancy (an advanced setup), you would put the IP address of your second Pi-hole here.
- Save or apply the changes on your router. The router might restart or simply apply the settings.
Renew DHCP Leases on Client Devices:
- For your devices to start using the new DNS server (your Pi-hole), they need to renew their DHCP lease from the router. This will provide them with the updated DNS server information.
- You can either:
  - Reboot each device: This will force it to request a new DHCP lease.
  - Manually renew the DHCP lease:
    - Windows:
      1. Open Command Prompt as Administrator.
      2. Type ipconfig /release and press Enter.
      3. Type ipconfig /renew and press Enter.
      4. Type ipconfig /flushdns (to clear local DNS cache).
    - macOS:
      1. Go to System Settings (or System Preferences) > Network.
      2. Select your active network connection (e.g., Wi-Fi or Ethernet).
      3. Click "Details..." (or "Advanced...").
      4. Go to the "TCP/IP" tab.
      5. Click "Renew DHCP Lease."
      6. (Optional) Flush DNS cache: Open Terminal and type sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder.
    - Linux (NetworkManager):
      1. Often, disconnecting and reconnecting the network interface (e.g., via the network applet) is sufficient.
      2. Or, from the terminal: sudo dhclient -r (to release) and then sudo dhclient (to renew). Interface name might be needed, e.g., sudo dhclient -r eth0 && sudo dhclient eth0.
      3. Flush DNS (if systemd-resolved is used): sudo systemd-resolve --flush-caches.
    - Android/iOS: The easiest way is usually to turn Wi-Fi off and then back on for that device. This forces it to re-negotiate the DHCP lease. Alternatively, restarting the device also works.
Verify DNS Settings on a Client Device:
- After renewing the DHCP lease, check the network settings on one of your client devices (e.g., your computer).
- The DNS server listed should now be your Pi-hole's IP address.
  - Windows: ipconfig /all (look for "DNS Servers").
  - macOS: System Settings > Network > [Your Interface] > Details... > DNS.
  - Linux: cat /etc/resolv.conf (though this can be managed by NetworkManager or systemd-resolved, so it might point to 127.0.0.53 if systemd-resolved is active, which then should be configured by DHCP to use your Pi-hole). A more reliable check on Linux might be to see what NetworkManager or dhclient received.

Option 2 Device-Level Configuration (For Testing or Specific Devices)

If you don't want to configure your router or only want to test Pi-hole on a single device, you can manually set the DNS server on that device.

General Steps (vary by OS):

You'll typically go into your device's network connection settings (Wi-Fi or Ethernet) and find the DNS server configuration. Change it from "Automatic (DHCP)" to "Manual" and enter your Pi-hole's IP address as the only DNS server.

Windows:
1. Control Panel > Network and Internet > Network and Sharing Center.
2. Click on your active connection (e.g., "Ethernet" or "Wi-Fi").
3. Click "Properties."
4. Select "Internet Protocol Version 4 (TCP/IPv4)" and click "Properties."
5. Select "Use the following DNS server addresses."
6. Enter your Pi-hole's IP in "Preferred DNS server."
7. Leave "Alternate DNS server" blank or enter 0.0.0.0 (or if you have a second Pi-hole, its IP). Do not put a public DNS here.
8. If you use IPv6, repeat for "Internet Protocol Version 6 (TCP/IPv6)" using Pi-hole's IPv6 address (if configured and known).
9. Click "OK" on all dialogs. Flush DNS: ipconfig /flushdns.
macOS:
1. System Settings (or System Preferences) > Network.
2. Select your active connection, click "Details..." (or "Advanced...").
3. Go to the "DNS" tab.
4. Click the + button under DNS Servers and add your Pi-hole's IP address.
5. Remove any other DNS servers listed (like your router's IP or public DNS IPs) by selecting them and clicking -.
6. Click "OK" and "Apply."
Linux (NetworkManager GUI):
1. Open network settings.
2. Select your active connection and go to its settings/edit.
3. Find the "IPv4" tab. Change "Method" from "Automatic (DHCP)" to "Automatic (DHCP) addresses only" OR to "Manual" if you also want to set a static IP for the client here (not usually needed).
4. In the "DNS servers" field, enter your Pi-hole's IP address.
5. If there's an "Automatic" toggle for DNS, turn it off.
6. Apply/save. You might need to disconnect and reconnect the network.
Android:
1. Go to Settings > Network & internet > Wi-Fi.
2. Tap and hold your connected Wi-Fi network, then select "Modify network." (Or tap the gear icon next to it, then "Advanced").
3. Change "IP settings" from "DHCP" to "Static."
4. You'll need to re-enter your device's IP address (choose one outside DHCP range or use its current one if it's stable), Gateway (router's IP), Network prefix length (e.g., 24 for 255.255.255.0).
5. Enter your Pi-hole's IP address in "DNS 1."
6. Leave "DNS 2" blank or enter your Pi-hole's IP again.
7. Save.
8. Alternatively, newer Android versions (9+) support "Private DNS" (DNS-over-TLS). This is not for pointing to a local Pi-hole by IP address directly, but for using public DoT servers. For local Pi-hole, manual IP config is the way.
iOS (iPhone/iPad):
1. Go to Settings > Wi-Fi.
2. Tap the "i" icon next to your connected Wi-Fi network.
3. Scroll down to "Configure DNS" and tap it.
4. Change from "Automatic" to "Manual."
5. Tap "Add Server" and enter your Pi-hole's IP address.
6. Tap the red minus (-) icon next to any existing DNS servers (like your router's IP) to remove them.
7. Tap "Save."

Drawbacks of Device-Level Configuration:

You have to configure each device individually.
New devices joining your network won't automatically use Pi-hole.
It's easy to forget you've set it manually, which can cause issues if Pi-hole's IP changes or if you take the device to another network.

Verifying Pi-hole is Working

After configuring your router or device(s) to use Pi-hole:

Visit Ad-Heavy Websites:
- Open a web browser on a device that is now configured to use Pi-hole.
- Go to websites that typically display a lot of ads (e.g., news sites, some tech blogs, cnn.com, forbes.com - though some sites are getting clever with first-party ads).
- You should see significantly fewer ads. Areas where ads used to be might be blank or collapsed.
- Note: Pi-hole primarily blocks ads served from third-party domains. It won't block ads served from the same domain as the content (e.g., YouTube video ads, Facebook sponsored posts are harder to block at DNS level).
Check the Pi-hole Admin Dashboard:
- Open your web browser and go to your Pi-hole's admin interface: http://PI_HOLE_IP_ADDRESS/admin (e.g., http://192.168.1.53/admin) or http://pihole.local/admin (if mDNS works).
- Log in with the password that was displayed at the end of the Pi-hole installation (or the one you set with pihole -a -p).
- Dashboard Statistics: You should see numbers increasing for:
  - "Total Queries"
  - "Queries Blocked"
  - "Percent Blocked"
  - "Domains on Blocklist"
- Query Log: Go to "Query Log" from the left-hand menu. As you browse the web on a client device, you should see DNS queries appearing here in real-time.
  - Allowed queries will show "OK (forwarded)" or "OK (cached)".
  - Blocked queries (ads/trackers) will show "Blocked (gravity)" or "Blocked (regex/wildcard)". The domain name will often be indicative of an ad server.

If you see queries being logged and some being blocked, congratulations! Your Pi-hole is working.

Workshop Pointing Your Network/Device to Pi-hole

This workshop will focus on the Router-Level Configuration (Option 1), as it's the most effective for comprehensive ad blocking. We will simulate the general steps, as router interfaces vary widely. If you are hesitant to change router settings or don't have access, you can try the device-level configuration on your own computer as a fallback.

Objective:

To configure your home router to use Pi-hole as the DNS server for all devices on your network.

Prerequisites:

Pi-hole installed and running with a known static IP address (e.g., 192.168.1.53).
Access to your home router's administration interface (IP address, username, password).

Steps:

Gather Information:
- Pi-hole's static IP address: (e.g., 192.168.1.53)
- Your router's admin IP address: (e.g., 192.168.1.1)
- Your router's admin login credentials.
Log in to Your Router:
- Open a web browser on your computer.
- Enter your router's IP address in the address bar and press Enter.
- Log in with the admin username and password.
Locate DHCP Server / LAN DNS Settings:
- This is the trickiest part due to router differences. Patiently navigate through your router's menus. Look for sections like:
  - LAN Setup
  - Network Settings
  - DHCP Server
  - Local Network
  - Advanced Settings -> DHCP or DNS
- You are looking for where your router specifies the DNS servers it hands out to clients via DHCP. Do not confuse this with WAN DNS settings (which are for the router itself).
Configure DNS Servers:
- Once you find the relevant DNS settings for your LAN/DHCP clients:
  - For Primary DNS Server (or DNS Server 1): Enter your Pi-hole's static IP address (e.g., 192.168.1.53).
  - For Secondary DNS Server (or DNS Server 2):
    - Ideal: Leave this blank if your router allows it.
    - If it requires an entry, try 0.0.0.0.
    - If neither of the above works, re-enter your Pi-hole's IP address (192.168.1.53).
    - CRITICAL: Do NOT enter a public DNS server like 8.8.8.8 or 1.1.1.1 here, as devices might use it and bypass Pi-hole.
Save/Apply Router Settings:
- Click "Save," "Apply," or a similar button to store the new configuration.
- Your router might reboot or simply apply the changes. If it reboots, wait for it to come back online.
Renew DHCP Lease on Your Computer:
- On your computer (the one you're using for testing):
  - Windows: Open Command Prompt (Admin): ipconfig /release, then ipconfig /renew, then ipconfig /flushdns.
  - macOS: System Settings > Network > [Interface] > Details... > TCP/IP > Renew DHCP Lease. Then Terminal: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder.
  - Linux: Disconnect/reconnect network or use sudo dhclient -r && sudo dhclient [interface]. Then sudo systemd-resolve --flush-caches (if applicable).
Verify DNS on Your Computer:
- Check your computer's network settings again. The DNS server should now be pointing to your Pi-hole's IP address.
Test Ad Blocking:
- Open a web browser on this computer. Clear your browser's cache and cookies for a cleaner test.
- Visit a few websites known for having many ads (e.g., cnn.com, forbes.com, yahoo.com, or a specific ad test page like https://ads-blocker.com/testing/).
- Observe if ads are being blocked.
Check Pi-hole Dashboard:
- Log in to your Pi-hole admin interface (http://PI_HOLE_IP/admin).
- Watch the "Total Queries" and "Queries Blocked" numbers. They should increase as you browse.
- Check the "Query Log" to see requests from your computer's IP address being processed (some allowed, some blocked).
Test on Other Devices (Optional but Recommended):
- Take another device on your network (e.g., a smartphone).
- Disconnect its Wi-Fi and reconnect it (or reboot it) to get the new DHCP settings.
- Browse the web and see if ads are blocked. Check the Pi-hole query log for activity from this device's IP.

If ads are still appearing:

Double-check the router DNS settings. Did they save correctly?
Ensure you renewed the DHCP lease properly on the client device. Rebooting the client is often the surest way.
Clear browser cache on the client device.
Check the Pi-hole query log: are queries from your client's IP even reaching Pi-hole? If not, the client is not using Pi-hole for DNS.
Some ads (YouTube in-video, Facebook sponsored) are hard for Pi-hole to block. Focus on banner ads and third-party tracker domains.

Outcome:

If successful, your entire network should now be benefiting from Pi-hole's ad-blocking capabilities! Any device getting its IP via DHCP from your router will automatically use Pi-hole.

7. Exploring the Pi-hole Web Admin Interface

The Pi-hole web admin interface is your command center for monitoring, managing, and customizing your ad-blocking setup. It provides a wealth of information and tools. Now that Pi-hole is installed and (hopefully) blocking ads on your network, let's take a comprehensive tour of this interface.

Accessing the Dashboard

Open a web browser on any device connected to your network.
Navigate to one of the following URLs:
- http://PI_HOLE_STATIC_IP/admin (e.g., http://192.168.1.53/admin)
- http://pihole.local/admin (if your network and client support mDNS/Bonjour and you used pihole as the hostname).
You will be prompted for a password. Enter the web admin password that was displayed at the end of the Pi-hole installation, or the one you set using pihole -a -p.
Click "Login" or press Enter.

You'll land on the main Dashboard page.

Dashboard Overview

The dashboard provides an at-a-glance summary of your Pi-hole's activity. Key elements include:

Status Indicators: Shows if Pi-hole is "Active" and if FTL (the DNS resolver engine) is "Online."
Statistic Boxes (typically for the last 24 hours):
- Total Queries: The total number of DNS requests processed by Pi-hole.
- Queries Blocked: The number of DNS requests that were blocked because they matched a domain on your blocklists.
- Percent Blocked: The percentage of total queries that were blocked.
- Domains on Blocklist: The total number of unique domains aggregated from all your active adlists.
Graphs:
- Queries over last 24 hours: A bar chart showing the volume of total queries and blocked queries over time.
- Query types over last 24 hours: A pie chart showing the distribution of DNS query types (e.g., A, AAAA, PTR, MX).
- Forward destinations over last 24 hours: A pie chart showing which upstream DNS servers your Pi-hole forwarded allowed queries to.
Top Lists (typically for the last 24 hours):
- Top Permitted Domains: The domains that were queried most frequently and allowed.
- Top Blocked Domains: The ad/tracker domains that were queried most frequently and blocked.
- Top Clients (Total): The IP addresses (or hostnames if resolved) of devices on your network making the most DNS queries in total.
- Top Clients (Blocked): The IP addresses of devices on your network that had the most queries blocked.

The dashboard data usually auto-refreshes. You can pause/resume this auto-refresh.

Query Log

This is one of the most useful sections for understanding what Pi-hole is doing and for troubleshooting.

Access: Click "Query Log" in the left-hand navigation menu.
Functionality:
- Displays a real-time (or near real-time if paused) table of all DNS queries processed by Pi-hole.
- Columns:
  - Time: Timestamp of the query.
  - Type: DNS record type (A, AAAA, CNAME, etc.).
  - Domain: The requested domain name.
  - Client: IP address or hostname of the device that made the query.
  - Status:
    - OK (forwarded to <upstream_server#IP>): Query was allowed and forwarded.
    - OK (cached): Query was allowed and served from Pi-hole's cache.
    - Blocked (gravity): Query was blocked by one of your adlists.
    - Blocked (regex/wildcard): Query was blocked by a custom blacklist or regex filter.
    - Blocked (external, NXDOMAIN): Blocked by an external blocklist that returns NXDOMAIN.
    - Other statuses for different scenarios (e.g., CNAME inspection results).
  - Reply: The DNS reply type (e.g., IP address, NXDOMAIN, NODATA).
  - Action: Allows you to quickly Whitelist or Blacklist the domain directly from the log.
Filtering: You can filter the query log by date/time range or search for specific domains or clients.
Use Cases:
- See exactly what your devices are trying to access.
- Identify why a specific website or service might be broken (if a necessary domain is being blocked).
- Discover new ad/tracker domains to potentially add to custom blacklists.

Long-Term Data

Pi-hole can store query data for a longer period (configurable) if you have logging enabled.

Access: "Long-term data" in the menu, then "Query Log," "Graphics," or "Top Lists."
Query Log (Historical): Allows you to search and view past DNS queries beyond the default 24-hour dashboard view. You can select custom date ranges.
Graphics: Provides interactive charts for:
- Total queries over time.
- Blocked queries over time.
- Percentage blocked.
- Number of clients seen over time.
- And more, allowing you to visualize trends.
Top Lists: Similar to the dashboard but allows you to select custom date ranges for:
- Top Domains (Allowed)
- Top Ads (Blocked Domains)
- Top Clients (by total or blocked queries)
- Upstream server query distribution.

This section is invaluable for analyzing historical network activity and Pi-hole performance. By default, Pi-hole stores data in its database (/etc/pihole/pihole-FTL.db) for a configurable number of days (default is usually 365 days, but can be changed in settings).

Group Management (Client, Domain, Adlist Grouping)

This is a powerful feature for applying different filtering policies to different devices or groups of devices.

Access: "Group Management" in the menu, then "Groups," "Clients," "Domains," or "Adlists."
Groups:
- You can create custom groups (e.g., "Kids_Devices," "Work_Laptops," "No_Blocking").
- The "Default" group applies to all clients not specifically assigned to another group.
- Each group can have its own set of enabled/disabled adlists and its own whitelist/blacklist entries.
Clients:
- Lists all known clients (by IP or MAC address if Pi-hole is DHCP server).
- You can assign specific clients to different groups. For example, you could assign your children's devices to a group with more aggressive blocking.
Domains (Whitelist/Blacklist per Group):
- Under "Domains", you can add domains to a global whitelist/blacklist or associate them with specific groups.
- This means a domain could be whitelisted for one group (e.g., "Work_Laptops" if it's needed for work) but remain blocked for others.
Adlists:
- You can assign different adlists (blocklists) to different groups. For example, the "Default" group might use standard adlists, while a "High_Security" group could use additional, more restrictive lists.

This granular control is excellent for tailoring Pi-hole's behavior to the diverse needs of a household or small office.

Domain Management

This section allows you to fine-tune what gets blocked or allowed, overriding the main adlists.

Access: "Domain Management" in the menu, then "Blacklist," "Whitelist," or "Regex filters." (In newer Pi-hole versions, this is often just "Domains" and you specify if it's a blacklist/whitelist entry).
Blacklist:
- Exact Blocking: Add specific domains you always want to block, even if they are not on any adlist. (e.g., annoying.tracker.com).
- Wildcard Blocking: Use wildcards to block a domain and all its subdomains. For example, adding *.doubleclick.net as a wildcard blacklist entry would block ad.doubleclick.net, stats.doubleclick.net, etc. (Syntax for wildcard can be just doubleclick.net and select "Add domain as wildcard", or using regex).
Whitelist:
- Add specific domains you always want to allow, even if they appear on one of your blocklists. This is crucial for fixing "broken" websites or services.
- For example, if analytics.example.com is blocked by an adlist but is required for example.com to function correctly, you would whitelist analytics.example.com.
- Like blacklisting, you can often add exact or wildcard whitelist entries.
Regex Filters:
- For advanced users. Allows you to use Regular Expressions to define complex patterns for blocking or allowing domains.
- Example: Block all domains ending in .xyz (regex: \.xyz$). Block domains containing "adserver" (regex: adserver).
- Regex is very powerful but can also easily lead to over-blocking if not crafted carefully. Test regex filters thoroughly.

When you add/remove entries here, Pi-hole's "Gravity" (the combined blocklist) usually needs to be updated. The interface often prompts you or does this automatically.

Adlists

This is where you manage the sources of your blocklists.

Access: "Group Management" > "Adlists" (in newer versions) or a dedicated "Adlists" menu item.
Functionality:
- Lists all the adlist URLs Pi-hole is currently using.
- You can enable or disable individual lists.
- You can add new adlist URLs. Many community-curated lists are available online (search for "Pi-hole adlists"). Popular ones include StevenBlack's hosts, Firebog lists, etc.
- Caution: Adding too many lists, or poorly maintained lists, can increase the chance of false positives (blocking legitimate domains) and can also increase the time it takes to update Gravity and consume more memory. Start with a few reputable lists and add more only if needed.
- You can see the status of each list (e.g., last updated, number of domains).
Updating Gravity: After adding or changing adlists, you must update Gravity. This process downloads all enabled lists, de-duplicates entries, and compiles the final blocklist Pi-hole uses. There's usually a button or link to "Update Gravity" or it's done via "Tools" > "Update Gravity."

Tools

This section provides various utilities for maintenance and troubleshooting.

Update Gravity:
- Manually triggers the process of downloading and recompiling your adlists.
- Useful after adding new adlist URLs or if you suspect lists are outdated.
Query Adlists:
- Allows you to search for a specific domain across all your enabled adlists to see which list(s) contain it. Very useful for figuring out why a particular domain is being blocked.
Audit Log:
- Shows a log of domains that have been added to your whitelist or blacklist and were also found on one of your adlists. Helps identify redundant entries.
Tail Pi-hole Log (pihole.log):
- Shows a live, scrolling view of the main Pi-hole log file (/var/log/pihole.log). Useful for real-time, low-level troubleshooting.
Tail FTL Log (pihole-FTL.log):
- Shows a live, scrolling view of the Pi-hole FTL (DNS resolver) log file (/var/log/pihole-FTL.log). Useful for diagnosing issues with the DNS engine itself.
Generate Debug Log:
- This is a critical tool for troubleshooting. It collects a comprehensive set of diagnostic information from your Pi-hole and system, sanitizes private information, and (optionally) uploads it to a secure server, providing you with a unique token. You can then share this token with Pi-hole support (e.g., on their Discourse forum) to help them diagnose your issue.
Network Overview:
- Provides a table of devices that have made DNS queries through your Pi-hole, showing their IP address, MAC address (if Pi-hole is DHCP server or can determine it), hostname, and first/last query times. Useful for identifying all clients using Pi-hole.

Settings

This is where you configure various aspects of Pi-hole's behavior and the system it runs on.

System:
- Information about your Pi-hole version, web interface version, FTL version.
- Buttons to: Restart DNS resolver (FTL), Restart system (Reboot Pi), Shutdown system (Power off Pi).
- Interface card information, disk usage, memory usage, CPU temperature.
- Flush network table: Clears Pi-hole's ARP cache.
- Flush logs: Deletes old query data from the database (use with caution).
- Power off system / Reboot system: Self-explanatory.
DNS:
- Upstream DNS Servers: Configure which upstream DNS servers Pi-hole forwards allowed queries to (e.g., Google, Cloudflare, Quad9, Custom IPs). You can select IPv4 and IPv6 servers.
- Interface listening behavior:
  - Listen on all interfaces: Pi-hole responds to DNS queries on any network interface.
  - Listen on all interfaces, permit all origins: Same as above, but less strict about where queries come from (generally okay for home LAN).
  - Listen only on interface <interface_name>: Restrict Pi-hole to listen only on a specific interface (e.g., eth0). Recommended for security if your Pi has multiple interfaces and only one should be serving DNS.
- Advanced DNS settings:
  - Never forward non-FQDNs: Prevents forwarding of single-label names (e.g., "mycomputer" instead of "mycomputer.localdomain").
  - Never forward reverse lookups for private IP ranges: Prevents forwarding PTR queries for local IP addresses.
  - Use DNSSEC: If your selected upstream DNS servers support DNSSEC (DNS Security Extensions), enabling this adds a layer of validation to DNS responses, ensuring they haven't been tampered with. Most major providers like Google, Cloudflare, Quad9 support DNSSEC. Recommended to enable if your upstreams support it.
  - Rate-limiting: Configure how many queries per second a client can make before being temporarily ignored (helps prevent DNS amplification attacks or misbehaving clients).
DHCP:
- DHCP server enabled: You can configure Pi-hole to act as your network's DHCP server.
  - Why? If Pi-hole is your DHCP server, it can accurately map client IP addresses to hostnames in its logs and statistics, making them more readable. Some routers don't allow changing DHCP DNS settings, so using Pi-hole's DHCP is an alternative.
  - How? If you enable this, you MUST disable the DHCP server on your main router to avoid conflicts.
  - Configuration options include: DHCP IP range to lease, router (gateway) address to provide to clients, lease time.
- Static DHCP leases: If Pi-hole is your DHCP server, you can create static leases here (similar to DHCP reservations on a router).
API / Web Interface:
- API Token (Show API Token): Needed if you want to use third-party apps or scripts to interact with Pi-hole's API.
- Interface Appearance: Choose themes, enable/disable charts.
- Query Log Settings: Show/hide different columns, how many entries to display.
- Top Lists Settings: How many entries to show.
- Privacy Level: Change the FTL logging privacy level (same options as during installation).
- Password: Change your web admin login password here.
Teleporter:
- Allows you to Backup your Pi-hole settings (whitelists, blacklists, adlists, static DHCP leases, client assignments, etc.) into a downloadable .tar.gz archive.
- You can then Restore from this backup file on the same or a different Pi-hole instance. Incredibly useful for migrating to a new Pi, recovering from an SD card failure, or just keeping a safe backup.

Workshop Mastering the Pi-hole Web Interface

This workshop is an exploratory exercise. The goal is to familiarize yourself with the different sections of the Pi-hole web admin interface and understand where to find key information and settings.

Objective:

To navigate and understand the main components of the Pi-hole web admin interface.

Prerequisites:

Pi-hole installed, running, and configured as your network's DNS server (or for your test client).
Web admin password.
A client device actively browsing the internet to generate DNS queries.

Steps:

Login and Dashboard Exploration:
- Access your Pi-hole admin interface (e.g., http://192.168.1.53/admin).
- Log in with your password.
- Spend 5-10 minutes on the Dashboard.
  - Note the "Total Queries," "Queries Blocked," and "Percent Blocked."
  - Identify your own computer's IP address in the "Top Clients" lists.
  - Look at the "Top Permitted Domains" and "Top Blocked Domains." Do any look familiar from your browsing?
  - Observe how the "Queries over last 24 hours" graph changes if you refresh the page after some browsing.
Deep Dive into the Query Log:
- Click on "Query Log" in the left menu.
- On a client device (e.g., your computer), open a new website, preferably one with ads (e.g., a news site).
- Watch the Query Log in Pi-hole. You should see many new entries appear.
- Identify a few queries with "Blocked (gravity)" status. Click the domain name – it might give you more info or search options.
- Identify a few queries with "OK (forwarded)" status.
- Find a blocked domain that you think might be an ad. Click the "Blacklist" button next to it (just to see the confirmation dialog, you can cancel it).
- Find a domain that was allowed. Click the "Whitelist" button (again, just to see the dialog, then cancel). This demonstrates how you'd whitelist a false positive.
Check Long-Term Data (if you've had Pi-hole running for a bit):
- Go to "Long-term data" > "Query Log."
- Try to view queries from "Yesterday" or a specific time range.
- Explore "Long-term data" > "Graphics." See how the charts look.
Whitelist and Blacklist Practice:
- Go to "Domain Management" (or just "Domains").
- Blacklist:
  - Think of a non-essential, safe-to-block domain (e.g., test-ads.com - this may not exist, which is fine for practice).
  - Type test-ads.com in the "Domain" field, add a comment like "Test blacklist", and click "Add to Blacklist."
  - If prompted, allow Gravity to be updated or go to "Tools" > "Update Gravity" and run it.
- Whitelist:
  - Imagine necessary.example.com was accidentally blocked by an adlist and is breaking example.com.
  - Type necessary.example.com in the "Domain" field, add a comment "Test whitelist for example.com", and click "Add to Whitelist."
  - Update Gravity if needed.
- Review: See your entries in the Blacklist and Whitelist tabs.
- Cleanup: After testing, you can remove these test entries by clicking the trash can icon next to them.
Explore Adlists:
- Go to "Group Management" > "Adlists."
- See the default adlist(s) Pi-hole is using.
- (Optional) Search online for "recommended Pi-hole adlists" (e.g., on firebog.net). If you find a reputable list URL (e.g., one from https://v.firebog.net/hosts/lists.php?type=tick), you can try adding it.
  - Copy the URL.
  - Paste it into the "Address" field, add a comment, and click "Add."
  - Remember to update Gravity ("Tools" > "Update Gravity") after adding a new list.
- Caution: Be selective with adlists. More isn't always better.
Visit Tools:
- Go to "Tools" > "Query Adlists."
- Enter a known ad domain (e.g., doubleclick.net) and search. See which of your active adlists contain it.
- Briefly look at "Tail Pi-hole Log" and "Tail FTL Log" to see live log data streaming. Close the pop-up windows when done.
Navigate Settings:
- Click on "Settings" in the left menu.
- Briefly click through each tab ("System," "DNS," "DHCP," "API / Web Interface," "Teleporter") to see the available options.
- In "DNS" tab: Note your current "Upstream DNS Servers." Are they what you selected during installation? Note the "Interface listening behavior."
- In "API / Web Interface" tab: Find the "Change Web Password" section (don't change it now unless you want to).
- In "Teleporter" tab: Click "Backup." A pi-hole-teleporter_*.tar.gz file will be downloaded to your computer. This is your Pi-hole configuration backup!

Outcome:

By the end of this workshop, you should feel much more comfortable navigating the Pi-hole web admin interface. You'll know where to find:

Overall statistics and performance.
Detailed DNS query logs.
Tools for managing whitelists, blacklists, and adlists.
Key configuration settings.
Utilities for troubleshooting and maintenance.

This familiarity will be invaluable as you continue to use and fine-tune your Pi-hole.

8. Advanced Pi-hole Configurations and Features

Once you have your Pi-hole up and running with the basics, there are several advanced configurations and companion tools you can explore to enhance its functionality, privacy, and utility. This section delves into some of the most popular and useful ones.

Using Pi-hole as a DHCP Server

As mentioned earlier, you can configure Pi-hole to act as the DHCP server for your network.

Why Use Pi-hole as DHCP?

Improved Client Identification: When Pi-hole is the DHCP server, it directly knows the hostnames of the clients it assigns IP addresses to. This means the Pi-hole Query Log and Top Clients lists will show actual device names (e.g., johns-iphone, livingroom-tv) instead of just IP addresses, making it much easier to identify which device is making which queries. While Conditional Forwarding (covered next) can help, Pi-hole as DHCP is more reliable for this.
Router Limitations: Some ISP-provided or basic routers have very limited DHCP configuration options. They might not allow you to change the DNS servers handed out by DHCP, or their DHCP reservation features might be poor. Using Pi-hole as the DHCP server bypasses these router limitations.
Centralized Network Control: Consolidates DNS and DHCP management onto your Pi-hole device.

Step-by-step Configuration:

CRITICAL: Disable DHCP Server on Your Router:
- Before enabling DHCP on Pi-hole, you MUST disable the existing DHCP server on your main router. Having two active DHCP servers on the same network will cause major IP address conflicts and network instability.
- Log in to your router's admin interface.
- Find the DHCP server settings (usually under LAN Setup or Network Settings).
- Look for an option to "Disable DHCP Server" or uncheck "Enable DHCP Server."
- Save the changes on your router. Your router might need to reboot.
- At this point, devices on your network will not be able to obtain new IP addresses until Pi-hole's DHCP is active.
Enable and Configure DHCP Server in Pi-hole:
- Log in to your Pi-hole web admin interface.
- Go to Settings > DHCP tab.
- Check the box "DHCP server enabled".
- Configure the Range of IP addresses to hand out:
  - From: The starting IP address of your DHCP pool (e.g., 192.168.1.101).
  - To: The ending IP address of your DHCP pool (e.g., 192.168.1.250).
  - Ensure this range does not overlap with any statically assigned IP addresses on your network (including Pi-hole's own static IP, your router's IP, and any other devices with static IPs).
- Router (gateway) address:
  - Enter your router's IP address here (e.g., 192.168.1.1). Pi-hole will hand this out as the default gateway to clients.
- Lease Time:
  - How long an IP address lease is valid before a client needs to renew it (e.g., 24 hours is common). Default is usually fine.
- (Optional) Domain Name:
  - You can specify a local domain name (e.g., lan or home.arpa). Clients will then be addressable as hostname.yourdomain (e.g., mypc.lan). home.arpa is a specially designated domain for home networks.
- (Optional) Enable Rapid Commit (speeds up IPv6 address assignment if clients support it).
Static DHCP Leases (Optional but Recommended for Key Devices):
- Scroll down to the "Static DHCP leases configuration" section.
- Here, you can assign specific IP addresses to devices based on their MAC addresses (similar to DHCP reservations on a router). This is useful for servers, printers, or any device you want to have a consistent IP address.
- You'll need the MAC address of the device and the desired IP address.
- Click "Add."
Save DHCP Settings:
- Scroll to the bottom of the DHCP settings page and click "Save".
Renew DHCP Leases on Client Devices:
- Client devices on your network need to obtain a new IP address from the Pi-hole DHCP server.
- You can either reboot each client device or manually renew their DHCP lease (as described in Section 6).
- For example, on a Windows PC: ipconfig /release then ipconfig /renew.
- The client should now receive an IP address from the range you defined in Pi-hole, and its DNS server should automatically be set to Pi-hole's IP.

Potential Conflicts and How to Avoid Them:

Two DHCP Servers: The biggest risk. Only one DHCP server should be active on a given network segment. Always disable your router's DHCP before enabling Pi-hole's.
IP Range Overlap: Ensure the DHCP pool in Pi-hole doesn't include any IPs you've manually assigned statically to other devices.
Router IP Change: If your router's IP address changes, you'll need to update the "Router (gateway) address" in Pi-hole's DHCP settings.

Conditional Forwarding

If you choose not to use Pi-hole as your DHCP server, you might notice that the Pi-hole Query Log and Top Clients lists show client IP addresses rather than their more friendly hostnames (e.g., 192.168.1.120 instead of davids-laptop). Conditional Forwarding can help resolve this.

What it does: It tells Pi-hole to forward reverse DNS lookups (IP address to hostname) for your local network range to your router (which usually knows the hostnames of DHCP clients).
Configuration:
1. In the Pi-hole web admin interface, go to Settings > DNS tab.
2. Scroll down to the "Advanced DNS settings" section.
3. Check the box "Use Conditional Forwarding".
4. IP address of your DHCP server (router): Enter your router's IP address (e.g., 192.168.1.1).
5. Local domain name: Enter the local domain name your router uses (if any). This can often be found in your router's LAN or DHCP settings. Common values are lan, local, or it might be blank. If unsure, you can try leaving it blank or using lan.
6. Click "Save" at the bottom of the page.
How it works: When Pi-hole sees a query from a local IP (e.g., 192.168.1.120), it will ask your router (at 192.168.1.1) "What is the hostname for 192.168.1.120?". If the router knows, it responds with the hostname.
Limitations:
- It relies on your router responding correctly to these reverse DNS queries. Some routers do this well, others don't.
- It might not work for devices with statically configured IPs that the router doesn't know about via DHCP.
- Using Pi-hole as the DHCP server is generally more reliable for hostname resolution.

Customizing Block Pages (Limited Utility with HTTPS)

In the past, when a domain was blocked over HTTP, Pi-hole could serve a custom block page explaining why the content was blocked. However, with the prevalence of HTTPS, this feature has limited utility.

How Pi-hole Handles Blocked Domains: By default, Pi-hole typically responds to blocked DNS queries with an IP address of 0.0.0.0 (NULL blocking) or its own IP address, or NXDOMAIN (Non-Existent Domain), depending on the BLOCKINGMODE set in /etc/pihole/pihole-FTL.conf.
Limitations with HTTPS:
- If a browser tries to connect to a blocked domain https://ads.example.com and Pi-hole returns its own IP, the browser will attempt an HTTPS connection to the Pi-hole's IP.
- The Pi-hole's web server (lighttpd) does not have a valid SSL/TLS certificate for ads.example.com.
- This results in a browser certificate warning/error page (e.g., "Your connection is not private"), not a Pi-hole block page. Users won't see a friendly Pi-hole message.
For HTTP Traffic: If some ads are still served over HTTP (rare nowadays), and Pi-hole is configured to return its own IP for blocked domains, lighttpd can serve a simple block page from /var/www/html/pihole/index.html (or a more specific block page if configured).
Recommendation: Due to HTTPS, relying on a visible block page is not very effective. The "silent" blocking (where the ad element just doesn't load or shows an error) is the common experience. Focusing on effective blocklists is more important than custom block pages.

Using `unbound` as a Recursive DNS Resolver with Pi-hole

By default, Pi-hole forwards allowed queries to upstream public DNS servers (like Cloudflare, Google, Quad9). While these are generally fast and reliable, you are still relying on a third party for DNS resolution. unbound is an open-source, validating, recursive, and caching DNS resolver that you can run locally on your Raspberry Pi.

What is a Recursive DNS Resolver?

Instead of just forwarding your query to another server, a recursive resolver like unbound performs the entire DNS lookup process itself. It queries the internet's root DNS servers, then the TLD (Top-Level Domain, e.g., .com) servers, then the authoritative name servers for the specific domain, until it finds the IP address.

Benefits of using unbound with Pi-hole:

Increased Privacy: Your DNS queries (for allowed domains) do not go to a third-party public DNS provider. Only your unbound instance communicates with the authoritative DNS servers across the internet. This can reduce tracking by commercial DNS providers.
Independence: You are not reliant on the uptime or policies of a specific public DNS provider.
DNSSEC Validation: unbound performs DNSSEC validation, ensuring the authenticity and integrity of DNS responses (Pi-hole can also do this if its upstream supports it, but unbound does it locally).
Learning: Setting up unbound is a great way to learn more about how DNS works.

Installing and Configuring unbound:

Install unbound on your Raspberry Pi: sudo apt update sudo apt install unbound -y
Create/Edit unbound Configuration File: Pi-hole's documentation provides a recommended configuration for unbound. Create a new config file, for example, /etc/unbound/unbound.conf.d/pi-hole.conf: sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf

Paste the following configuration (this is a common, well-regarded configuration from Pi-hole docs/community;
```
                                                                   
```
always check official Pi-hole documentation for the latest recommended unbound config): name="__codelineno-4-1" href="#__codelineno-4-1">server: # If no logfile is specified, syslog is used # logfile: "/var/log/unbound/unbound.log" verbosity: 0 interface: 127.0.0.1 port: 5335 do-ip4: yes do-udp: yes do-tcp: yes # May be set to yes if you have IPv6 connectivity do-ip6: no # You want to leave this to no unless you have *our* private key # 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 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 issues with certain DNS servers. # DEPRECATED IN LATER UNBOUND VERSIONS, use: 'use-caps-for-id: no' # use-caps-for-id: no # For Unbound 1.13.1 and above, this is the new option: # # Turn on DNSSEC query-response validation. # If you are concerned about the performance impact, you can disable it. # However, it's generally recommended to keep it on for security. # validator: module # val-permissive-mode: no # Reduce EDNS reassembly buffer size. # Suggested by the unbound man page to reduce fragmentation reassembly errors edns-buffer-size: 1232 # Rotate RRSet order in response (load balancing) rrset-roundrobin: yes # Perform prefetching of close to expired DNS records # This only applies to records that have been frequently requested prefetch: yes prefetch-key: yes # One thread should be sufficient, can be increased on beefy machines. Best rule of thumb # is one thread per core, but try to leave one core available for Pi-hole. num-threads: 1 # More cache results, requires more memory msg-cache-size: 128m rrset-cache-size: 256m # 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
- Key settings:
  - interface: 127.0.0.1: unbound will only listen on the loopback interface (localhost).
  - port: 5335: unbound will listen on port 5335 (to avoid conflict with Pi-hole FTL on port 53).
  - do-ip6: no: Change to yes if your Pi has reliable IPv6 connectivity and you want unbound to use it for its recursive queries.
  - Make sure root-hints is commented out if you are using the dns-root-data package (usually installed as a dependency or recommended with unbound).
- Save and close the file (Ctrl+X, Y, Enter in nano).
Download Root Hints (if not using dns-root-data package or want to ensure fresh copy):
While often unbound finds them automatically via dns-root-data, you can manually fetch them: wget -O root.hints https://www.internic.net/domain/named.root sudo mv root.hints /var/lib/unbound/ (or the path specified in unbound.conf if you uncomment root-hints)
Restart unbound and Enable it to Start on Boot: sudo systemctl restart unbound sudo systemctl enable unbound Check its status: sudo systemctl status unbound (should be active and running).
Point Pi-hole to unbound:
- In the Pi-hole web admin interface, go to Settings > DNS tab.
- Uncheck all public Upstream DNS Servers (Google, Cloudflare, etc.) on both IPv4 and IPv6.
- In the Custom 1 (IPv4) field, enter 127.0.0.1#5335.
  - 127.0.0.1 is localhost (where unbound is listening).
  - #5335 specifies the port number unbound is using.
- Leave other Custom DNS fields blank (unless you have a secondary unbound instance or specific IPv6 setup for unbound).
- Click "Save" at the bottom.
Test unbound Functionality:
- From the Raspberry Pi's command line, test a DNS lookup using dig through unbound directly: dig google.com @127.0.0.1 -p 5335 You should get a successful response with IP addresses for google.com. The first query might be a bit slower as unbound recursively resolves it. Subsequent queries for the same domain should be faster (served from unbound's cache).
- Check Pi-hole's Query Log. Allowed queries should now show they are being forwarded to 127.0.0.1#5335.

You now have a local recursive DNS resolver enhancing your privacy!

DNS over HTTPS (DoH) and DNS over TLS (DoT) with `cloudflared` or other proxies

If you prefer not to run a full recursive resolver like unbound but still want to encrypt the DNS queries from your Pi-hole to its upstream public DNS provider, you can use a DoH or DoT proxy. cloudflared (from Cloudflare) is a popular tool for this.

Concept: Pi-hole sends its queries to a local proxy (like cloudflared). This proxy then encrypts the queries and sends them to a public DoH/DoT resolver (like Cloudflare's 1.1.1.1).
Benefits: Encrypts your DNS traffic between Pi-hole and the upstream provider, preventing snooping by your ISP or anyone on the path.
Setting up cloudflared (Example for DoH):
1. Download cloudflared: Go to the Cloudflare Argo Tunnel downloads page (https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/) and get the ARM binary for Linux. Example for Raspberry Pi (ARMv7/ARM32): wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm sudo cp cloudflared-linux-arm /usr/local/bin/cloudflared sudo chmod +x /usr/local/bin/cloudflared (Check for the correct ARM version - arm for 32-bit OS, arm64 for 64-bit OS).
2. Create a cloudflared user: sudo useradd -s /usr/sbin/nologin -r -M cloudflared
3. Create a configuration file for cloudflared: sudo mkdir /etc/cloudflared sudo nano /etc/cloudflared/config.yml Add:
```
proxy-dns: true
proxy-dns-port: 5053 # Or another unused port
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query
# For IPv6 (optional)
#  - https://[2606:4700:4700::1111]/dns-query
#  - https://[2606:4700:4700::1001]/dns-query
```
  Save and close.
4. Set permissions for config file: sudo chown cloudflared:cloudflared /etc/cloudflared/config.yml sudo chmod 640 /etc/cloudflared/config.yml
5. Create a systemd service file for cloudflared: sudo nano /etc/systemd/system/cloudflared.service Paste:
```
[Unit]
Description=Cloudflare Tunnel DNS Proxy
After=network.target

[Service]
Type=simple
User=cloudflared
ExecStart=/usr/local/bin/cloudflared proxy-dns --config /etc/cloudflared/config.yml
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target
```
  Save and close.
6. Enable and start the cloudflared service: sudo systemctl enable cloudflared sudo systemctl start cloudflared sudo systemctl status cloudflared (Check it's active and running).
7. Configure Pi-hole to use cloudflared:
  - In Pi-hole web admin: Settings > DNS.
  - Uncheck all public DNS servers.
  - In Custom 1 (IPv4), enter 127.0.0.1#5053 (or the IP/port you configured for cloudflared).
  - Save.
Other Proxies:

Similar tools exist for DoT, or unbound itself can be configured to forward queries over DoT to upstream servers.

unbound vs. DoH/DoT Proxy:

unbound (Recursive): More privacy from upstream providers, you control the whole chain. Can be slightly slower for initial queries.
DoH/DoT Proxy: Still relies on a public upstream provider, but encrypts the "last mile" from your Pi-hole to them. Simpler setup than full recursion if you trust the DoH/DoT provider.

Workshop Setting Up Pi-hole as a DHCP Server and Exploring `unbound`

This workshop will be split into two main parts. Part 1: Configure Pi-hole as your DHCP Server. Part 2: Install and configure unbound as a local recursive DNS resolver for Pi-hole.

Prerequisites:

Pi-hole installed, running, and currently using your router for DHCP.
Access to your router's admin interface.
SSH access to your Raspberry Pi.

Part 1: Configuring Pi-hole as DHCP Server

Plan Your DHCP Settings:
- Pi-hole's static IP: (e.g., 192.168.1.53)
- Router's IP (Gateway): (e.g., 192.168.1.1)
- Desired DHCP IP Range for Pi-hole to manage: (e.g., 192.168.1.150 to 192.168.1.250). Ensure this range does not include your Pi-hole's IP, your router's IP, or any other static IPs on your network.
CRITICAL: Disable DHCP on Your Router:
- Log in to your router's admin page.
- Navigate to its DHCP server settings.
- Disable the DHCP server function on your router. Save the setting. The router might reboot.
- Warning: From this moment until Pi-hole's DHCP is active, new devices or devices trying to renew leases won't get IP addresses from the router.
Configure Pi-hole DHCP:
- Open your Pi-hole admin interface.
- Go to Settings > DHCP tab.
- Check the box "DHCP server enabled".
- Fill in your planned Range of IP addresses to hand out:
  - From: e.g., 192.168.1.150
  - To: e.g., 192.168.1.250
- Fill in Router (gateway) address: e.g., 192.168.1.1
- (Optional) Set a Domain Name like home.arpa.
- Click "Save" at the bottom.
Test on a Client Device:
- Take one client device (e.g., your computer or smartphone).
- Force it to renew its DHCP lease:
  - PC: Disconnect and reconnect network cable, or ipconfig /release & ipconfig /renew.
  - Smartphone: Turn Wi-Fi off and on.
- Check its network settings. It should now have:
  - An IP address from the range you set in Pi-hole (e.g., 192.168.1.151).
  - The DNS server should be Pi-hole's IP address.
  - The Gateway should be your router's IP address.
- Verify internet connectivity and ad blocking.
- Check Pi-hole's Query Log. You should see the client's hostname instead of just its IP address for new queries.

Part 2: Installing and Configuring unbound

Install unbound:
SSH into your Raspberry Pi. sudo apt update sudo apt install unbound -y
Configure unbound (pi-hole.conf): sudo nano /etc/unbound/unbound.conf.d/pi-hole.conf Paste the recommended configuration from the "Using unbound" section above. Ensure interface is 127.0.0.1, port is 5335, and do-ip6 is set according to your network. Save and exit (Ctrl+X, Y, Enter).
Start and Enable unbound: sudo systemctl restart unbound sudo systemctl enable unbound sudo systemctl status unbound (Verify it's active and running without errors).
Configure Pi-hole to Use unbound:
- In Pi-hole admin interface: Settings > DNS tab.
- Uncheck ALL upstream DNS servers (Google, Cloudflare, etc.) in the predefined lists on the left and right.
- In the "Upstream DNS Servers" section, under Custom 1 (IPv4), enter: 127.0.0.1#5335
- Leave Custom 2, Custom 3 (IPv6) etc., blank for now.
- Scroll down and click "Save".
Test unbound and Pi-hole Integration:
- From Pi SSH: dig pi-hole.net @127.0.0.1 -p 5335 You should get a valid response. The first query might take a few seconds.
- From Pi SSH: dig flurry.com @127.0.0.1 -p 5335 (flurry.com is often on blocklists) You should still get an IP from unbound (unbound doesn't block, Pi-hole does).
- From a client device: Browse the internet. Ads should still be blocked.
- Check Pi-hole Query Log: Allowed queries should now show "forwarded to 127.0.0.1#5335". Blocked queries should still be blocked by "gravity".
- Check unbound logs (optional advanced): sudo journalctl -u unbound -f to see unbound activity.

Outcome:

Your Pi-hole is now acting as the DHCP server for your network, providing better client identification.
Your Pi-hole is using your own local recursive DNS resolver (unbound), enhancing your DNS privacy.

This setup provides a robust, private, and highly informative ad-blocking solution!

9. Maintaining and Updating Pi-hole

Like any software, Pi-hole and the underlying Raspberry Pi OS require periodic maintenance and updates to ensure optimal performance, security, and access to new features. This section covers the essential maintenance tasks.

Updating Pi-hole Core, Web Interface, and FTL

Pi-hole consists of three main components that can be updated:

Pi-hole Core: The main scripting and logic.
Web Interface: The admin dashboard you access via your browser.
FTL (Faster Than Light engine): The DNS resolver and statistics processor.

The Pi-hole team regularly releases updates for these components.

Command to Update Pi-hole:

The simplest way to update all Pi-hole components is via the command line on your Raspberry Pi (through an SSH session):

pihole -up

When you run this command:
- It will check for updates to Pi-hole Core, Web Interface, and FTL.
- If updates are available, it will inform you and ask if you wish to proceed.
- It will then download and install the updates.
- It typically backs up your existing configuration and then attempts to re-apply it after the update.

Frequency: It's a good idea to check for Pi-hole updates perhaps once a month, or when you hear about a new release on the Pi-hole blog or forums.

Updating Blocklists (Gravity)

Your adlists (blocklists) also get updated by their maintainers. To ensure Pi-hole has the latest definitions of ad-serving domains, you need to update "Gravity." This process re-downloads all your enabled adlists, de-duplicates them, and compiles them into the single master list that FTL uses.

Command to Update Gravity: From the Raspberry Pi's command line:

pihole -g

This command will:
- Show you the lists being downloaded.
- Process them and report the number of domains added, removed, and the total number of domains on your blocklist.

Via Web Interface:

You can also update Gravity from the web admin interface:

Go to Tools > Update Gravity.
Click the large "Update" button.

Automating Gravity Updates with Cron:

Manually running pihole -g is fine, but you can automate it to run regularly using cron, the Linux task scheduler. Pi-hole usually sets up a weekly cron job for this by default during installation.

To check existing Pi-hole cron jobs: sudo ls -l /etc/cron.d/pihole You should see a file there. View its contents: sudo cat /etc/cron.d/pihole It often contains a line like: # Pi-hole: Update a local copy of the ad lists # (Update occurs every Sunday at a random time between 01:00 and 05:59) # 52 3 * * 7 root PATH="$PATH:/usr/sbin:/usr/local/bin/" pihole updateGravity >/var/log/pihole_updateGravity.log || cat /var/log/pihole_updateGravity.log (The exact time and syntax might vary slightly). This indicates it's already scheduled.
If you need to manually create or modify a cron job for Gravity:
1. Edit the root user's crontab: sudo crontab -e (select an editor like nano if prompted).
2. Add a line to schedule pihole -g. For example, to run it every Sunday at 3:30 AM: 30 3 * * 7 root /usr/local/bin/pihole -g (The root part is usually for system cron files in /etc/cron.d/; for sudo crontab -e, you might just need 30 3 * * 7 /usr/local/bin/pihole -g) Consult crontab guru websites for help with cron syntax.
3. Save and exit.

Generally, the default weekly update set up by Pi-hole is sufficient.

Backing Up Your Pi-hole Configuration

It's crucial to back up your Pi-hole configuration, especially if you've customized whitelists, blacklists, adlists, DHCP settings, or client group assignments. This will save you a lot of time if your microSD card fails or if you need to migrate Pi-hole to a new device.

Method 1: Using the Teleporter Feature (Recommended)

In the Pi-hole web admin interface, go to Settings > Teleporter tab.
Click the "Backup" button.
A file named pi-hole-YOURHOSTNAME-teleporter_YYYY-MM-DD_HH-MM-SS.tar.gz will be downloaded to your computer.
Store this backup file in a safe place (e.g., on your computer, a USB drive, cloud storage).

What Teleporter Backs Up:

It typically backs up:

/etc/pihole/ directory contents (adlists, blacklists, whitelists, regex lists, FTL config, custom DNS entries, etc.)
/etc/dnsmasq.d/ directory contents (custom dnsmasq configurations, including static DHCP leases if Pi-hole is DHCP server).
Information about client group assignments.

Restoring from Teleporter:

On a fresh Pi-hole installation (or the one you want to restore to), go to Settings > Teleporter.
Under "Restore," click "Choose File," select your backup .tar.gz file.
Click "Restore." Pi-hole will process the file and apply the settings.

Method 2: Manual Backup of Key Files

If you prefer manual control or want to script backups, you can copy the key configuration directories. The most important directory is /etc/pihole/. You might also want /etc/dnsmasq.d/ if you have custom configurations there.

Example using tar to create an archive via SSH: sudo tar -czvf pihole_backup_$(date +%F).tar.gz /etc/pihole /etc/dnsmasq.d/ Then use scp or an SFTP client (like FileZilla or WinSCP) to copy this pihole_backup_YYYY-MM-DD.tar.gz file from your Pi to your computer.

Frequency:

Back up whenever you make significant changes to your Pi-hole configuration, or periodically (e.g., monthly) as a precaution.

Monitoring System Health

Your Raspberry Pi is a small computer. Monitoring its health can help prevent issues.

Checking Raspberry Pi Temperature: Overheating can lead to instability or shorten the Pi's lifespan. From the Pi's command line: vcgencmd measure_temp (e.g., temp=45.5'C). Generally, temperatures below 60-70°C under normal load are fine. If it consistently runs very hot (80°C+), consider better cooling (heatsinks, fan, better case ventilation). Pi-hole itself is not very CPU intensive, so overheating is usually not an issue unless the Pi is in a very hot environment or running many other services.
CPU Usage, Memory Usage:
- htop: An interactive process viewer. Run htop in the terminal. It shows CPU usage per core, memory usage, swap usage, and a list of running processes. pihole-FTL is the main Pi-hole process to watch. Press q to exit htop.
- free -h: Shows memory usage (total, used, free, shared, buff/cache, available) in human-readable format.
- df -h: Shows disk space usage on all mounted filesystems. Ensure your root partition (/) has enough free space. Logs can fill up disk space if not managed.
Monitoring microSD Card Health (Wear and Tear): microSD cards have a finite number of write cycles. While Pi-hole is not extremely write-intensive (especially if you adjust logging levels or use unbound which caches locally), card corruption is the most common failure point for Raspberry Pis.
- Reduce Logging: In Pi-hole Settings > System, you can adjust FTL's logging levels or disable it if card wear is a major concern (though this impacts troubleshooting).
- External Storage for Logs: As discussed in Section 2, moving logs to a USB drive can significantly reduce writes to the SD card.
- Use High-Endurance Cards: These are designed for more write cycles.
- Regular Backups of Pi-hole (Teleporter) AND the entire SD card image: If the card fails, having a full image backup allows for a quick restore to a new card. You can create an image of your running Pi's SD card using tools like Win32DiskImager (Windows) or dd (Linux/macOS) by putting the SD card in another computer. This is more involved than just Pi-hole's Teleporter backup.
- There aren't simple, universally reliable tools to predict SD card failure precisely on the Pi itself. Observing system stability and having backups are key.

Workshop Automating Updates and Backing Up Pi-hole

This workshop will guide you through:

Verifying/setting up an automated weekly cron job for pihole -g (updating Gravity).
Performing a manual Pi-hole component update (pihole -up).
Creating a backup of your Pi-hole configuration using Teleporter.

Prerequisites:

Pi-hole installed and running.
SSH access to your Raspberry Pi.
Access to the Pi-hole web admin interface.

Steps:

Part 1: Verify/Set Up Automated Gravity Update

SSH into your Raspberry Pi.
Check Existing Pi-hole Cron Job: sudo cat /etc/cron.d/pihole
- Look for a line similar to: 52 3 * * 7 root PATH="$PATH:/usr/sbin:/usr/local/bin/" pihole updateGravity ... (The numbers representing time will vary as Pi-hole randomizes it to avoid overwhelming list servers).
- If such a line exists, Gravity is already scheduled to update weekly (typically on Sunday). You can proceed to Part 2.
(If no cron job exists or you want to change it) Manually Set Up Cron Job:
- Open the root crontab for editing: sudo crontab -e (If prompted, choose nano as your editor).
- Add the following line at the end of the file to update Gravity every Sunday at 2:30 AM: 30 2 * * 0 /usr/local/bin/pihole -g > /var/log/pihole_updateGravity.log 2>&1
  - 30 2 * * 0: Minute 30, Hour 2 (2 AM), Day of month , Month , Day of week 0 (Sunday).
  - /usr/local/bin/pihole -g: The command to update Gravity.
  - > /var/log/pihole_updateGravity.log 2>&1: Redirects standard output and standard error to a log file.
- Save and exit (Ctrl+X, Y, Enter in nano).
- Verify the cron job was added: sudo crontab -l

Part 2: Manually Update Pi-hole Components

Still in your SSH session on the Raspberry Pi.
Run the Pi-hole Update Command: pihole -up
Observe the Output:
- The script will check for updates for Core, Web, and FTL.
- If updates are found, it will list the current and available versions.
- It will likely ask Do you want to continue? (Y/n). Type Y and press Enter.
- The updates will be downloaded and installed. This might take a few minutes.
- You should see messages like "[✓] Update complete!" for each component.
Verify Versions (Optional):
- After the update, you can check the versions on the Pi-hole web admin dashboard (usually in the footer) or via command line: pihole -v This will show versions for Pi-hole, Web Interface, and FTL.

Part 3: Create a Pi-hole Configuration Backup using Teleporter

Open your web browser and navigate to the Pi-hole admin interface. (e.g., http://192.168.1.53/admin)
Log in with your web admin password.
Go to Teleporter:
- In the left-hand menu, click Settings.
- Then, click the Teleporter tab.
Initiate Backup:
- Under the "Backup" section, click the large "Backup" button.
Download and Save:
- Your browser will download a file named something like pi-hole-yourhostname-teleporter_YYYY-MM-DD_HH-MM-SS.tar.gz.
- Save this file to a secure location on your computer or another backup medium. This file contains your crucial Pi-hole settings.

Outcome:

You've ensured that your Pi-hole's blocklists (Gravity) will be updated automatically on a weekly basis.
You've successfully updated the Pi-hole software components to their latest versions.
You've created a backup of your Pi-hole's configuration, which can be used for restoration or migration.

Performing these maintenance tasks regularly will keep your Pi-hole running smoothly and securely.

10. Troubleshooting Common Pi-hole Issues

Even with a robust setup, you might occasionally encounter issues with Pi-hole. This section covers some common problems and how to diagnose and resolve them. The Pi-hole debug log and query log are your best friends when troubleshooting.

Ads Are Not Being Blocked

This is a common first issue users encounter.

Verify Client DNS Settings:
- Ensure the device you're testing on is actually configured to use Pi-hole as its DNS server.
  - If you configured Pi-hole at the router level, renew the DHCP lease on the client device (reboot device, or toggle Wi-Fi, or use ipconfig /renew etc.). Then check its network settings to see if the DNS server IP is your Pi-hole's IP.
  - If you configured Pi-hole manually on the client, double-check those settings.
- Crucially: Make sure the client is ONLY using Pi-hole as its DNS. If you have a secondary DNS server listed (like 8.8.8.8) either on the client or in your router's DHCP settings, the client might bypass Pi-hole.
Check Pi-hole Query Log:
- Access the Pi-hole web admin interface. Go to "Query Log."
- Browse a website with ads on your client device.
- Do you see queries from your client's IP address appearing in the Pi-hole Query Log?
  - If NO queries from your client appear: Your client is not using Pi-hole for DNS. Revisit Step 1.
  - If queries DO appear:
    - Are any queries being marked as "Blocked (gravity)"?
    - If all queries are "OK (forwarded)" or "OK (cached)," it could mean the ad domains are not on your blocklists, or ads are being served from the same domain as content (which Pi-hole can't easily block).
Ensure Gravity is Updated:
- When was the last time you updated Gravity? Outdated lists might not block newer ad domains.
- In Pi-hole web admin: Tools > Update Gravity > Click "Update."
- Or via SSH: pihole -g
Flush DNS Cache on Clients:
- Client devices and browsers cache DNS responses. Even if Pi-hole starts blocking a domain, your client might still have an old, allowed IP address cached.
- Windows: ipconfig /flushdns (in admin Command Prompt).
- macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder (in Terminal).
- Browsers: Most browsers have their own internal DNS cache. Closing and reopening the browser, or clearing its cache/history, might help. Chrome: chrome://net-internals/#dns -> "Clear host cache".
Browser Extensions Overriding DNS:
- Some browser extensions (especially VPNs or "secure DNS" extensions) can override the system's DNS settings and bypass Pi-hole.
- Try testing in a private/incognito browser window with extensions disabled, or temporarily disable suspect extensions.
Hardcoded DNS in Applications or Devices:
- Some applications or IoT devices (notoriously, some Google devices or smart TVs) might have public DNS servers (like 8.8.8.8) hardcoded into them. These will bypass Pi-hole.
- Advanced solution: Block outgoing DNS (port 53) traffic from all devices except your Pi-hole at your firewall/router level, forcing them to use Pi-hole or have no DNS. This is more complex to set up.
IPv6 Issues:
- If your network uses IPv6 and your clients get an IPv6 DNS server from your router that isn't your Pi-hole's IPv6 address, they might use that for DNS and bypass Pi-hole for some queries.
- Ensure your router's DHCPv6 settings (if applicable) also hand out Pi-hole's IPv6 address as the DNS server, or disable IPv6 on problematic clients if simpler.

Pi-hole Web Interface Not Accessible

If you can't reach http://pi.hole/admin or http://PI_HOLE_IP/admin.

Check Pi-hole Service Status (pihole status):
- SSH into your Raspberry Pi.
- Run: pihole status
- This will tell you if the DNS service (FTL) is running and if blocking is enabled.
- If FTL is not running, try: sudo service pihole-FTL restart or pihole restartdns.
Check Lighttpd Service Status (sudo systemctl status lighttpd):
- Lighttpd is the web server that serves the Pi-hole admin interface.
- SSH into your Pi and run: sudo systemctl status lighttpd
- Look for "active (running)".
- If it's not running or has errors, try restarting it: sudo systemctl restart lighttpd
- Check for errors: sudo journalctl -u lighttpd -e (shows recent logs, -e jumps to end). Common issues: port conflicts (if another web server is on port 80), PHP errors.
Verify Raspberry Pi IP Address:
- Has the Pi's IP address changed? If it wasn't set statically or the static assignment failed, it might have a different IP.
- On the Pi (via SSH if possible, or console): ip addr
- Try accessing the web interface using the current IP.
Firewall Issues:
- Is there a firewall on the Raspberry Pi itself (e.g., ufw) or on your network that might be blocking port 80 (HTTP)?
- Pi-hole's installer typically configures ufw if it's active, but check: sudo ufw status. If active, ensure port 80 is allowed.
Clear Browser Cache/Try Different Browser: Sometimes browser issues can prevent a page from loading. Try clearing your browser's cache or using a different browser/private window.
Disk Space Full:
- If the microSD card is full, services like Lighttpd or FTL might fail to start or run correctly.
- SSH into Pi: df -h
- Check usage for / (root) and /var/log. If nearly full, you need to free up space (e.g., clear old logs, remove unneeded files). Pi-hole has log rotation, but other services might not.

Certain Websites or Services Not Working

This usually means Pi-hole is blocking a domain that the website/service needs to function. This is called a "false positive."

Identify Blocked Domains Using Query Log:
- Go to the Pi-hole web admin interface > Query Log.
- Try to access the problematic website/service on a client device.
- Observe the Query Log in real-time. Look for domains related to the failing service that are being "Blocked (gravity)".
- Common culprits are telemetry, analytics, or content delivery network (CDN) domains that are overly aggressively blocked by an adlist.
Whitelist Necessary Domains:
- Once you identify a suspicious blocked domain in the Query Log, click the green "Whitelist" button next to it.
- This will add the domain to your whitelist, and Pi-hole will no longer block it. Gravity will be updated.
- Try accessing the website/service again. You might need to whitelist multiple domains.
- Be cautious: only whitelist domains you trust and are reasonably sure are needed for functionality.
Use Tools > Query Adlists:
- If you know a specific domain is causing issues (e.g., cdn.important-service.com), go to Tools > Query Adlists.
- Enter the domain and search. This will tell you which of your blocklists is causing it to be blocked. You can then decide if you want to whitelist the domain or perhaps disable that specific, overly aggressive blocklist (if it causes many problems).
Temporarily Disable Pi-hole for Testing:
- In the web admin interface, on the left menu, you can "Disable" Pi-hole for a set amount of time (e.g., 5 minutes) or indefinitely.
- If the website/service works when Pi-hole is disabled, it confirms Pi-hole's blocking is the cause. Re-enable Pi-hole and use the Query Log to find the specific domain to whitelist.
Common False Positives:
- Some link shorteners (e.g., t.co from Twitter, bit.ly).
- Affiliate link domains.
- Some CDNs or domains serving images/videos if they are also used for ads.
- Device telemetry (e.g., device-metrics-us.amazon.com).
- Microsoft services can sometimes be over-blocked.

Pi-hole Stops Working After a While

If Pi-hole works initially but then fails later.

microSD Card Corruption:
- This is a common failure mode for Raspberry Pis. Power outages or low-quality SD cards can lead to corruption.
- Symptoms: Pi becomes unresponsive, services fail to start, errors in logs about read/write failures.
- Solution: Try re-imaging the SD card with a fresh OS and reinstalling Pi-hole (restore from Teleporter backup if you have one!). Consider using a new, high-quality (or high-endurance) SD card.
Power Supply Issues:
- An inadequate or failing power supply can cause instability, reboots, and SD card corruption.
- Ensure you're using the correct official power supply for your Pi model or a reputable third-party one with sufficient amperage (e.g., 5V 3A for Pi 4).
- Look for the under-voltage warning symbol (lightning bolt) if you have a monitor connected, or check logs for under-voltage messages (dmesg | grep -i "under-voltage").
Network Connectivity Problems:
- Loose Ethernet cable.
- Wi-Fi issues (if using Wi-Fi).
- Problems with your router or switch.
- Pi-hole's static IP changed or IP conflict.
Running out of Disk Space:
- As mentioned, if / or /var/log fills up, services will fail.
- df -h. Clean up old logs or unneeded files.
- Pi-hole FTL database (/etc/pihole/pihole-FTL.db) can grow large if you store long-term data. You can configure the retention period in Settings > System > "MaxDBDays".
Overheating:
- Less common for just Pi-hole, but if the Pi is in a hot enclosure or running other demanding tasks, it could overheat and throttle or become unstable.
- vcgencmd measure_temp. Improve cooling if necessary.

High CPU or Memory Usage

If pihole-FTL is consistently using a lot of CPU or memory.

Analyzing pihole-FTL.log:
- SSH into Pi: sudo less /var/log/pihole-FTL.log (or tail it: sudo tail -f /var/log/pihole-FTL.log).
- Look for error messages, warnings, or unusual patterns.
Too Many Clients or Excessive Queries:
- A very large number of clients or a few misbehaving clients making an enormous number of DNS queries (e.g., a device in a DNS query loop) can strain FTL.
- Check Pi-hole Dashboard > Top Clients to identify any unusually active devices.
- Rate limiting (Settings > DNS > Advanced DNS settings) can help mitigate abusive clients.
Misconfigured Blocklists (e.g., overly broad regex):
- A poorly written regex filter (e.g., one that matches almost everything) can cause FTL to work very hard.
- Review your custom regex filters in Domain Management > Regex filters. Disable suspect ones for testing.
Large Number of Adlists/Domains on Blocklist:
- While FTL is efficient, an extremely large number of domains on blocklist (many millions) can increase memory usage. Try to be judicious with adlists.
Database Issues:
- Corruption or issues with the long-term query database (pihole-FTL.db) can sometimes cause problems.
- You might try moving the database and letting FTL create a new one (you'll lose historical data): sudo service pihole-FTL stop sudo mv /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.old sudo service pihole-FTL start

Generating and Interpreting Debug Logs

When you can't solve an issue, the Pi-hole debug log is invaluable for getting help from the community or developers.

pihole -d command:
- SSH into your Raspberry Pi.
- Run: pihole -d
- The script will perform a series of checks and gather information about your Pi-hole installation, system configuration, network setup, and recent log entries.
- It will sanitize some private information (like MAC addresses by default).
Uploading Debug Logs for Support:
- At the end of the debug process, it will ask: *** [ DIAGNOSING ]: Would you like to upload the log? [y/N]
- If you type y and press Enter, it will upload the log to a secure Pi-hole server.
- It will then display a debug token URL (e.g., https://tricorder.pi-hole.net/youruniquetoken).
- Copy this URL. This is what you share with support personnel (e.g., on the Pi-hole Discourse forum: https://discourse.pi-hole.net/). They can use the token to view your debug log. The log automatically expires after 48 hours.
- If you choose N (not to upload), the log is usually stored locally at /var/log/pihole_debug.log for your own inspection.

Interpreting Debug Logs (Basic Pointers):

The log is quite verbose. Look for sections with [✗] (cross mark) or [?] (question mark) as these often indicate problems or warnings.
Check network configuration sections: IP addresses, gateway, DNS servers Pi-hole is using.
Look at resolver checks (can Pi-hole reach its upstream DNS?).
Check for errors in excerpts from pihole.log, pihole-FTL.log, and lighttpd error logs.

Workshop Diagnosing and Fixing a Non-Functional Pi-hole

This workshop will simulate a common scenario: a website is not loading correctly, and we suspect Pi-hole is the cause. We'll use the Query Log and Whitelisting to fix it. We'll also practice generating a debug log.

Scenario:

You find that example-broken-site.com (a fictional site for this exercise) is not loading images, and you suspect Pi-hole.

Steps:

Verify the Issue and Initial Test:
- On a client device using Pi-hole, try to visit example-broken-site.com. Observe that some content (e.g., images from cdn.images-for-example.com) is missing.
- Quick Test: In Pi-hole web admin, temporarily disable Pi-hole (e.g., for 5 minutes). Reload example-broken-site.com. If images now load, Pi-hole is likely blocking a needed domain. Re-enable Pi-hole.
Use the Query Log to Investigate:
- With Pi-hole re-enabled, go to the Query Log in the web admin interface.
- On your client device, refresh example-broken-site.com again.
- Watch the Query Log closely for entries related to this site. Look for:
  - Queries for example-broken-site.com (should be "OK").
  - Other domains being queried around the same time, especially any with "Blocked (gravity)" status that look like they could be related to content delivery (e.g., containing "cdn," "assets," "images," or the site's name).
- Let's imagine you find cdn.images-for-example.com is being "Blocked (gravity)".
Whitelist the Problematic Domain:
- In the Query Log, find the row for cdn.images-for-example.com.
- Click the green "Whitelist" button in the "Action" column for that row.
- A confirmation will appear. Confirm. Pi-hole will update Gravity.
Retest the Website:
- On your client device, clear browser cache for example-broken-site.com or do a hard refresh (Ctrl+F5 or Cmd+Shift+R).
- Visit example-broken-site.com again. The images from cdn.images-for-example.com should now load correctly.
What if the Issue Persists? (Generate a Debug Log)
- If whitelisting didn't fix it, or if you encounter a more complex issue (e.g., Pi-hole FTL crashing, web interface inaccessible), generate a debug log.
- SSH into your Raspberry Pi.
- Run the command: pihole -d
- Follow the prompts. When asked Would you like to upload the log? [y/N], type y and press Enter.
- The script will upload the log and provide you with a token URL (e.g., https://tricorder.pi-hole.net/abcdef1234).
- Copy this URL.
(Hypothetical) Seeking Help:
- If this were a real issue you couldn't solve, you would go to the Pi-hole Discourse forum (https://discourse.pi-hole.net/).
- Create a new topic in the "Help" category.
- Describe your problem clearly: what you're experiencing, what you've tried, your setup details.
- Include the debug token URL you copied. Do not paste the entire debug log content into the forum post. Just the token URL.

Outcome:

You've learned a practical workflow for identifying and resolving false positives (incorrectly blocked domains) using the Pi-hole Query Log and whitelisting feature.
You know how to generate and upload a debug log, which is essential for getting effective support from the Pi-hole community.

Troubleshooting is a key skill. With practice and these tools, you'll become adept at keeping your Pi-hole running smoothly!

Conclusion and Further Learning

Congratulations on successfully setting up and configuring Pi-hole on your Raspberry Pi! You've transformed a tiny computer into a powerful network-wide ad and tracker blocker, enhancing the privacy, speed, and security of your internet experience for all devices on your network.

Recap of Pi-hole Benefits and Setup

Throughout this guide, you have:

Understood what Pi-hole is and how it uses DNS sinkholing to block unwanted content.
Prepared your Raspberry Pi hardware and flashed it with Raspberry Pi OS Lite.
Configured essential settings like a static IP address, crucial for Pi-hole's function as a server.
Installed the Pi-hole software using its automated script.
Directed your network devices (ideally via your router) to use Pi-hole as their DNS server.
Explored the Pi-hole web admin interface to monitor activity, manage blocklists, whitelists, and blacklists.
Learned about advanced configurations like using Pi-hole as a DHCP server and setting up unbound for recursive DNS resolution.
Covered important maintenance tasks such as updating Pi-hole and its lists, backing up your configuration, and monitoring system health.
Practiced troubleshooting common issues and generating debug logs.

By implementing Pi-hole, you're now enjoying a cleaner, faster, and more private internet experience. You've also gained valuable hands-on experience with Linux, networking concepts, and the versatile Raspberry Pi platform.

Exploring More Advanced Adlists and Regex

Your Pi-hole journey doesn't have to end here. You can further customize its blocking capabilities:

Curated Adlists: Explore reputable sources for additional adlists. Websites like The Firebog categorize lists by type (suspicious, advertising, tracking, malicious, etc.). Remember to add lists judiciously – more isn't always better, as it can increase false positives and resource usage.
Regex Mastery: For fine-grained control, dive deeper into using Regular Expressions (regex) in Pi-hole's blacklist/whitelist. Regex can block entire patterns of domains. There are many community-shared regex examples on the Pi-hole forums and Reddit. For instance:
- Blocking domains with many hyphens often used by spam/malware: (^|[-._])([a-zA-Z0-9-_]{15,}|[a-zA-Z0-9]{1,}[-][a-zA-Z0-9]{1,}[-][a-zA-Z0-9]{1,}[-][a-zA-Z0-9]{1,})([a-zA-Z0-9]{15,})\.
- Be very careful with regex, as a poorly written one can block legitimate sites. Test thoroughly.
Group Management: If you have diverse needs within your household (e.g., kids needing more restrictions, specific work-related domains that must be allowed for certain users), make full use of Pi-hole's Group Management to apply different policies to different clients.

Community Resources

The Pi-hole community is active and supportive. If you have questions, encounter issues, or want to learn more, these are excellent resources:

Pi-hole Discourse Forum: https://discourse.pi-hole.net/
- This is the official forum. You can find solutions to common problems, ask for help (remember to provide a debug token!), and discuss features.
Pi-hole Subreddit: https://www.reddit.com/r/pihole/
- Another active community for discussion, tips, and troubleshooting.
Pi-hole Documentation: https://docs.pi-hole.net/
- The official documentation is comprehensive and covers installation, configuration, and advanced topics.

Other Raspberry Pi Projects

Your Raspberry Pi is capable of much more than just running Pi-hole! Now that you're comfortable with setting up a service on it, consider exploring other projects:

Network Attached Storage (NAS): Use Samba or OpenMediaVault to create a home file server.
VPN Server: Set up PiVPN (using WireGuard or OpenVPN) to securely access your home network from anywhere. This can also allow you to use your Pi-hole ad blocking when you're away from home.
Home Automation Hub: Use software like Home Assistant or Domoticz to control smart home devices.
Retro Gaming Console: With RetroPie or Lakka.
Web Server: Host a personal website or develop web applications.
Media Center: Using OSMC or LibreELEC (Kodi).

Many of these can even run alongside Pi-hole on the same Raspberry Pi, especially if you have a Pi 3B+ or newer model with sufficient resources.

Thank you for following this guide. We hope you enjoy your ad-free browsing and continue to explore the exciting world of Raspberry Pi and open-source software!

Raspberry Pi workshop - Pi-hole Network-Wide Ad Blocker

Introduction to Pi-hole and Network-Wide Ad Blocking

What is Pi-hole?

How Pi-hole Works (DNS Sinkhole)

Benefits of Using Pi-hole

Limitations and Considerations

Workshop Introduction to Network Traffic Analysis

1. Prerequisites and Hardware Setup

Required Hardware

Raspberry Pi (Model Recommendations)

microSD Card (Size and Class Recommendations)

Power Supply

Ethernet Cable (Recommended) or Wi-Fi Dongle

(Optional) Case for Raspberry Pi

Required Software

Raspberry Pi Imager

SSH Client

Web Browser

Assembling Your Raspberry Pi

Workshop Verifying Your Hardware Components

2. Preparing the Operating System for Raspberry Pi

Understanding Raspberry Pi OS

Raspberry Pi OS Lite vs. Desktop

Why Lite is Preferred for Pi-hole

Downloading Raspberry Pi Imager

Choosing Your Raspberry Pi OS Image

Writing the OS to the microSD Card using Raspberry Pi Imager

Standard OS Installation

Disk Preparation Architectures

Standard Single Partition (Default)

Separate Partitions for OS and Data (e.g., logs)

Using an External USB Drive for Logs/Data

Considerations for Hibernation

Workshop Preparing Your microSD Card with Raspberry Pi OS Lite

3. Initial Raspberry Pi Configuration

Booting Up Your Raspberry Pi for the First Time

Finding Your Raspberry Pi's IP Address

Router's DHCP Client List

Network Scanning Tools

Using mDNS (if enabled and supported)

Connecting via SSH

Enabling SSH (if not done via Imager)

Using an SSH Client

First Boot Configuration (sudo raspi-config)

Updating the System (sudo apt update && sudo apt upgrade -y)

Workshop Securely Accessing and Updating Your Raspberry Pi

4. Understanding Static IP Addressing

Why Pi-hole Needs a Static IP Address

Methods for Assigning a Static IP

Method 1 Setting a Static IP on the Raspberry Pi Itself

Method 2 DHCP Reservation on Your Router

Pros and Cons of Each Method

Workshop Configuring a Static IP for Your Raspberry Pi

5. Installing Pi-hole

Pre-installation Checks

The One-Step Automated Install Script

Walking Through the Installation Wizard

Workshop Installing Pi-hole Software

6. Configuring Network Devices to Use Pi-hole

Option 1 Router-Level Configuration (Recommended for Network-Wide Blocking)

Option 2 Device-Level Configuration (For Testing or Specific Devices)

Verifying Pi-hole is Working

Workshop Pointing Your Network/Device to Pi-hole

7. Exploring the Pi-hole Web Admin Interface

Accessing the Dashboard

Dashboard Overview

Query Log

Long-Term Data

Group Management (Client, Domain, Adlist Grouping)

Domain Management

Adlists

Tools

Settings

Workshop Mastering the Pi-hole Web Interface

8. Advanced Pi-hole Configurations and Features

Using Pi-hole as a DHCP Server

Conditional Forwarding

Customizing Block Pages (Limited Utility with HTTPS)

Using unbound as a Recursive DNS Resolver with Pi-hole

DNS over HTTPS (DoH) and DNS over TLS (DoT) with cloudflared or other proxies

First Boot Configuration (`sudo raspi-config`)

Updating the System (`sudo apt update && sudo apt upgrade -y`)

Using `unbound` as a Recursive DNS Resolver with Pi-hole

DNS over HTTPS (DoH) and DNS over TLS (DoT) with `cloudflared` or other proxies

Workshop Setting Up Pi-hole as a DHCP Server and Exploring `unbound`