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

DNS Ad Blocker Pi-hole

Welcome to this comprehensive guide on self-hosting Pi-hole, your network-wide ad blocker. This document is designed for university students and anyone eager to gain a deep understanding of DNS, ad blocking, and how to effectively deploy and manage Pi-hole. We will journey from basic concepts and installation to advanced configurations and troubleshooting, equipping you with the knowledge to master this powerful tool.

Introduction to Pi-hole

This introductory section lays the groundwork for understanding Pi-hole. We'll explore what Pi-hole is, its core working principles, the benefits it offers, and the basic system requirements to get started.

What is Pi-hole?

Pi-hole is a free, open-source software application designed to block advertisements and internet trackers at the network level. Unlike browser-based ad blockers, which work only within the browser they are installed in, Pi-hole protects all devices connected to your network. This includes computers, smartphones, tablets, smart TVs, and any other IoT (Internet of Things) device that makes DNS (Domain Name System) requests.

Originally designed to run on a Raspberry Pi (hence the "Pi" in Pi-hole), it can now be installed on most Linux distributions, either on physical hardware, virtual machines, or within Docker containers. Its primary function is to act as a DNS "sinkhole." When a device on your network tries to access a domain known to serve ads or track user behavior, Pi-hole intercepts this request and prevents the content from being loaded. This results in a cleaner, faster, and more private internet browsing experience.

Pi-hole achieves this by becoming your local DNS server. Instead of your devices querying an external DNS server directly for every domain, they query Pi-hole. Pi-hole then checks the requested domain against extensive blocklists. If the domain is on a blocklist, Pi-hole effectively pretends the domain doesn't exist or redirects it to a non-routable address, thus preventing the ad or tracker from loading. If the domain is not on a blocklist, Pi-hole forwards the request to an upstream DNS server of your choice (like Google DNS, Cloudflare DNS, Quad9, etc.) and returns the legitimate IP address to the requesting device.

How Pi-hole Works The Magic of DNS Sinkholing

To truly appreciate Pi-hole, it's essential to understand the concept of DNS sinkholing.

The Role of DNS:
When you type a website address like www.example.com into your web browser, your computer doesn't inherently know where on the internet www.example.com is located. Computers communicate using IP addresses (e.g., 93.184.216.34). The Domain Name System (DNS) acts like the internet's phonebook, translating human-readable domain names into machine-readable IP addresses.

The Standard DNS Process (Without Pi-hole):

User Action: You type www.example.com into your browser.
Device Query: Your device (computer, phone) sends a DNS query to the DNS server configured in its network settings (often your router, which then forwards it to your ISP's DNS server, or a public DNS server like Google's 8.8.8.8).
DNS Resolution: The DNS server looks up the IP address for www.example.com.
IP Address Returned: The DNS server responds with the IP address (e.g., 93.184.216.34).
Connection: Your browser uses this IP address to connect to the web server hosting www.example.com and load the page.

How Websites Load Ads:
Web pages are rarely self-contained. They often include content (like advertisements or tracking scripts) from many different third-party domains. For example, a news website might load its articles from news.com, but its ads from ads.adcompany.com and analytics trackers from track.analyticsservice.com. Your browser makes separate DNS requests for each of these domains.

Pi-hole's Intervention (DNS Sinkholing):

When Pi-hole is your network's DNS server:

User Action: You type www.example.com into your browser.
Device Query to Pi-hole: Your device sends DNS queries for www.example.com, ads.adcompany.com, and track.analyticsservice.com to Pi-hole (because you've configured your network to use Pi-hole as its DNS server).
Pi-hole Checks Blocklists:
- For www.example.com (assuming it's not an ad domain): Pi-hole sees it's not on any blocklist. It forwards the query to an upstream DNS server (e.g., Cloudflare), gets the real IP address, and returns it to your device. Your browser loads the main content.
- For ads.adcompany.com: Pi-hole checks its blocklists and finds this domain listed. Instead of forwarding the query, Pi-hole "sinkholes" it. This means it typically responds with a non-routable IP address (like 0.0.0.0) or the IP address of the Pi-hole device itself.
- For track.analyticsservice.com: Similar to the ad domain, if it's on a blocklist, Pi-hole sinkholes it.
Content Loading (or not):
- Your browser successfully connects to www.example.com.
- When your browser tries to connect to ads.adcompany.com using the IP address 0.0.0.0, the connection fails. The ad doesn't load.
- Similarly, the tracking script from track.analyticsservice.com doesn't load.

The "magic" is that Pi-hole prevents the connection to ad and tracking servers from ever being established by providing a bogus IP address. Your browser or app simply thinks the ad server is unreachable.

Benefits of Using Pi-hole

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

Network-Wide Ad Blocking:
- Comprehensive Coverage: Blocks ads across all devices and applications on your network, not just in web browsers. This includes ads in mobile apps, smart TV interfaces, and other IoT devices.
- No Client-Side Software: You don't need to install ad-blocking software on every individual device.
Improved Browsing Speed:
- Reduced Data Download: Web pages load faster because your devices don't download ad content, which can often be heavy with images and scripts.
- Fewer HTTP Requests: By preventing connections to ad servers, the number of requests your browser makes is reduced.
Enhanced Privacy:
- Blocks Trackers: Pi-hole effectively blocks many third-party trackers that collect data about your online behavior for targeted advertising or analytics.
- Reduces Digital Footprint: By limiting the data sent to tracking companies, you can reduce your digital footprint and improve your online privacy.
Reduced Bandwidth Consumption:
- Saves Data: Especially beneficial for users with metered internet connections or mobile hotspots, as ads and trackers consume data. Blocking them saves bandwidth.
Improved Network Security (to an extent):
- Blocks Malware Domains: Some blocklists used by Pi-hole include domains known for distributing malware or phishing. By blocking these domains at the DNS level, Pi-hole can prevent devices from connecting to them, offering an additional layer of security.
- Note: Pi-hole is not a replacement for a firewall, antivirus software, or good security practices. It's a complementary tool.
Customization and Control:
- Dashboard: Pi-hole provides a user-friendly web interface to monitor its activity, see statistics, and manage settings.
- Whitelisting/Blacklisting: You have fine-grained control to whitelist specific domains (e.g., if a legitimate site is accidentally blocked) or blacklist additional domains.
- Custom Blocklists: You can add your own blocklists or choose from various community-curated lists.
- Group Management: Apply different blocking rules to different groups of devices on your network.
Educational Value:
- Understanding DNS: Running Pi-hole provides excellent insight into how DNS works and the sheer volume of background requests your devices make.
- Network Monitoring: The query log offers a transparent view of which domains your devices are trying to contact.
Cost-Effective:
- Free Software: Pi-hole itself is free and open-source.
- Low Hardware Cost: Can run on inexpensive hardware like a Raspberry Pi Zero.

System Requirements

Pi-hole is lightweight and can run on modest hardware. Here are the general system requirements:

Operating System: A supported Linux distribution. The most common and well-supported include:
- Raspberry Pi OS (32-bit and 64-bit)
- Debian (10, 11, 12)
- Ubuntu (20.04, 22.04)
- Fedora (37, 38, 39)
- CentOS Stream (8, 9)
- AlmaLinux (8, 9)
- Rocky Linux (8, 9)
- (Check the official Pi-hole documentation for the most up-to-date list of supported OS versions)
Hardware (Minimum Recommendations):
- Processor: Any modern single-core CPU is generally sufficient. For Raspberry Pi, a Pi Zero W is capable, but a Pi 3B+ or Pi 4 offers a smoother experience, especially with more devices or larger blocklists.
- RAM: At least 512MB of RAM is recommended. 1GB or more is better for larger networks or if you plan to run other services on the same device. Pi-hole itself typically uses around 100-200MB.
- Storage: A minimum of 4GB of free disk space is recommended. A fresh install uses very little, but logs and the long-term query database can grow over time. An 8GB or 16GB SD card for a Raspberry Pi is common.
- Network: A wired Ethernet connection is highly recommended for reliability and performance as a DNS server. Wi-Fi can work but may introduce latency or instability.
Static IP Address: The device running Pi-hole must have a static IP address on your local network. This is crucial because all your network devices will be configured to point to this specific IP address for DNS resolution. If the Pi-hole's IP address changes, DNS resolution will break for your network.
Internet Connection: Pi-hole needs internet access to download blocklists, update itself, and forward legitimate DNS queries to upstream DNS servers.

These requirements are quite flexible. Many users successfully run Pi-hole on older hardware repurposed for this task. The key is a stable operating system and network connection.

Workshop Setting Up Your Learning Environment

Before diving into Pi-hole installation, it's beneficial to prepare a consistent learning and experimentation environment. This workshop guides you through setting up a virtual machine (VM) which provides a safe and isolated space for practice.

Objective:

To install a lightweight Linux distribution (Debian) in a virtual machine using VirtualBox. This VM will serve as the host for your Pi-hole installation in later workshops.

Prerequisites:

A computer (Windows, macOS, or Linux) with at least 8GB of RAM (more is better) and 30GB of free disk space.
VirtualBox installed (download from https://www.virtualbox.org/).
A Debian NetInstall ISO image (download the latest stable "netinst" amd64 version from https://www.debian.org/distrib/).

Steps:

Create a New Virtual Machine in VirtualBox:
- Open VirtualBox.
- Click "New".
- Name: Pi-hole Lab VM (or any name you prefer).
- Type: Linux.
- Version: Debian (64-bit).
- Click "Next".
Allocate Memory (RAM):
- Allocate at least 1024 MB (1 GB) of RAM. If your host system has plenty of RAM (e.g., 16GB+), you can allocate 2048 MB for a smoother experience, but 1024 MB is sufficient for Pi-hole.
- Click "Next".
Create a Virtual Hard Disk:
- Select "Create a virtual hard disk now".
- Click "Create".
- Hard disk file type: Choose VDI (VirtualBox Disk Image).
- Click "Next".
- Storage on physical hard disk: Choose Dynamically allocated. This saves space initially, as the virtual disk file will grow as needed up to its maximum size.
- Click "Next".
- File location and size:
  - Set the size to at least 10 GB. 15-20 GB is a good range if you plan to experiment further.
  - Click "Create".
Configure VM Settings (Before First Boot):
- Select your newly created Pi-hole Lab VM in the VirtualBox manager.
- Click "Settings".
- System > Processor:
  - Assign 2 CPUs if your host system has 4 or more cores. 1 CPU will work but might be slower during installation and updates.
- Storage:
  - Under "Storage Devices", select the "Empty" CD/DVD drive under "Controller: IDE".
  - On the right-hand side, click the CD icon and choose "Choose a disk file...".
  - Navigate to and select the Debian NetInstall ISO file you downloaded.
  - Ensure "Live CD/DVD" is unchecked.
- Network:
  - Adapter 1:
    - Ensure "Enable Network Adapter" is checked.
    - Attached to: Bridged Adapter. This will allow the VM to get its own IP address on your local network, making it accessible like any other physical device. This is crucial for Pi-hole to function for other devices on your network.
    - Name: Select your host computer's active network interface (e.g., your Wi-Fi adapter or Ethernet adapter).
  - Expand "Advanced":
    - Promiscuous Mode: Set to Allow All. This can be helpful for network troubleshooting tools within the VM.
- Click "OK" to save settings.
Install Debian Linux:
- Select the Pi-hole Lab VM and click "Start".
- The VM will boot from the Debian ISO.
- Choose "Install" (the text-based installer is fine and lightweight).
- Follow the on-screen prompts:
  - Language, Location, Keyboard: Select your preferences.
  - Hostname: pihole-lab (or similar).
  - Domain name: Leave blank or use lan or home.arpa if you prefer.
  - Root password: Set a strong password and remember it.
  - Full name for new user: Your name.
  - Username for your account: Choose a username (e.g., student).
  - Password for new user: Set a strong password and remember it.
  - Partitioning:
    - Choose "Guided - use entire disk".
    - Select the virtual disk you created.
    - Choose "All files in one partition (recommended for new users)".
    - Select "Finish partitioning and write changes to disk".
    - Confirm "Yes" to write changes.
  - Scan extra installation media: No.
  - Package manager: Choose a mirror close to your location.
  - HTTP proxy: Leave blank unless you use one.
  - Software selection:
    - Deselect "Debian desktop environment" (we want a server, no GUI).
    - Ensure "SSH server" is selected.
    - Ensure "standard system utilities" is selected.
    - Press Continue.
  - Install GRUB boot loader: Yes, install it to the master boot record. Select your virtual hard disk (e.g., /dev/sda).
  - Finish installation: Continue. The VM will reboot.
Post-Installation VM Tweaks:
- Once Debian reboots, it should eject the ISO automatically. If not, you can manually remove it from VirtualBox settings > Storage > click the ISO and "Remove Disk from Virtual Drive".
- Log in to the Debian VM console with the user account you created (e.g., student).
- Update the system:
```
sudo apt update
sudo apt upgrade -y
```
- Install necessary tools:
```
sudo apt install -y curl sudo vim net-tools git
```
  (vim is a text editor, net-tools for ifconfig, git for some software installations, sudo is likely already there but good to ensure).
- Check IP Address:
```
ip addr show
```
  Note the IP address of the enp0s3 (or similar) interface. This is the IP address your VM has on your local network. You'll need this to SSH into it.
- Enable SSH (Optional - for convenience): You can now SSH into your VM from your host machine using a terminal or PuTTY (on Windows).
```
ssh student@<VM_IP_ADDRESS>
```

You now have a clean Debian server environment running in a VM, bridged to your network. This VM is ready for you to install Pi-hole in subsequent workshops. This approach allows you to experiment without affecting your main operating system or physical hardware directly. If something goes wrong, you can easily delete the VM and start over.

1. Understanding DNS and Ad Blocking Fundamentals

Before we jump into installing Pi-hole, it's crucial to have a solid understanding of the underlying technologies: the Domain Name System (DNS) and the mechanisms of online advertising and ad blocking. This knowledge will help you appreciate how Pi-hole works and troubleshoot potential issues more effectively.

What is DNS (Domain Name System)?

The Domain Name System (DNS) is one of the fundamental building blocks of the internet. Its primary role is to translate human-friendly domain names (like www.google.com or www.myuniversity.edu) into numerical IP (Internet Protocol) addresses (like 172.217.160.142 or 2607:f8b0:4004:809::200e) that computers use to identify and communicate with each other on a network. Think of it as the internet's phone book.

Without DNS, you would have to remember long strings of numbers for every website you want to visit, which is impractical for humans.

DNS Resolution Process

When you type a domain name into your web browser or an application tries to connect to a server, a DNS resolution process occurs. Here's a simplified step-by-step breakdown:

User Request & Local Cache Check:
- You request www.example.com.
- Your operating system first checks its local DNS cache. This cache stores recently resolved domain names and their IP addresses. If found, the IP is used directly, and the process stops here.
- If not in the OS cache, the query might also check the browser's cache.
Resolver Query (Recursive DNS Server):
- If the domain isn't in local caches, your computer (the "DNS client" or "stub resolver") sends a DNS query to a DNS resolver (also known as a recursive DNS server).
- This resolver is typically configured in your device's network settings. It might be:
  - Your home router (which often acts as a DNS forwarder).
  - Your Internet Service Provider's (ISP) DNS servers.
  - A public DNS resolver like Google Public DNS (8.8.8.8), Cloudflare DNS (1.1.1.1), or Quad9 (9.9.9.9).
  - In our case, eventually, this will be your Pi-hole.
Resolver's Cache Check:
- The recursive resolver first checks its own cache. If it has recently resolved www.example.com for another user, it will return the cached IP address.
Querying Root Servers (if not cached):
- If the resolver doesn't have the IP address in its cache, it begins a recursive query process.
- The resolver queries one of the DNS root servers. There are 13 geographically distributed root server clusters (named A through M) around the world.
- The root server doesn't know the IP address of www.example.com, but it knows where the Top-Level Domain (TLD) servers for the .com TLD are. It responds with the addresses of these .com TLD servers.
Querying TLD Servers:
- The resolver then queries one of the .com TLD servers.
- The TLD server doesn't know the IP address of www.example.com, but it knows the authoritative name servers for the example.com domain. These authoritative servers are responsible for holding the actual DNS records for that specific domain. The TLD server responds with the addresses of these authoritative name servers.
Querying Authoritative Name Servers:
- The resolver finally queries one of the authoritative name servers for example.com.
- This authoritative server does know the IP address for www.example.com (or more precisely, the IP address associated with the A record for www in the example.com zone).
- The authoritative name server responds to the resolver with the IP address.
Response to Resolver & Caching:
- The resolver receives the IP address. It caches this information (along with its Time-To-Live or TTL value, which dictates how long it can keep it cached) to speed up future requests for the same domain.
- The resolver then sends the IP address back to your computer (the original DNS client).
Response to Client & Caching:
- Your computer's operating system receives the IP address and also caches it.
- Your browser or application now uses this IP address to establish a connection with the web server hosting www.example.com.

This entire process, while seemingly complex, usually happens in milliseconds. Pi-hole inserts itself into this chain typically at step 2, acting as your local recursive resolver (or more commonly, as a DNS forwarder that leverages upstream recursive resolvers).

DNS Record Types

Authoritative name servers store various types of DNS records for a domain. Some common and important record types include:

A Record (Address Record):
- Maps a hostname to an IPv4 address (e.g., www.example.com -> 93.184.216.34).
- This is the most common type of record.
AAAA Record (IPv6 Address Record):
- Maps a hostname to an IPv6 address (e.g., www.example.com -> 2606:2800:220:1:248:1893:25c8:1946).
- Used for IPv6 connectivity.
CNAME Record (Canonical Name Record):
- Creates an alias from one domain name to another (the "canonical" or true name). For example, ftp.example.com might be a CNAME to server1.example.com.
- When a DNS resolver encounters a CNAME, it will restart the query for the canonical name.
- Pi-hole can sometimes have specific behavior with CNAMEs, especially if the canonical name is on a blocklist (this is called CNAME cloaking detection).
MX Record (Mail Exchange Record):
- Specifies the mail servers responsible for receiving email messages on behalf of a domain.
- Includes a priority value to indicate preference if multiple mail servers are listed.
TXT Record (Text Record):
- Allows administrators to associate arbitrary text with a domain.
- Often used for verification purposes (e.g., domain ownership verification for services like Google Workspace or Microsoft 365), SPF (Sender Policy Framework) records to combat email spoofing, and DKIM (DomainKeys Identified Mail) records for email authentication.
NS Record (Name Server Record):
- Delegates a DNS zone to use the given authoritative name servers.
- For example, the .com TLD servers have NS records pointing to the authoritative name servers for example.com.
PTR Record (Pointer Record):
- Performs a reverse lookup, mapping an IP address back to a hostname.
- Primarily used for reverse DNS lookups, often for logging or verification purposes. Stored in a special in-addr.arpa (for IPv4) or ip6.arpa (for IPv6) domain.
SRV Record (Service Record):
- Specifies the hostname and port number of servers for specified services, rather than a static IP address.
- Used for services like VoIP (SIP), XMPP, and LDAP.
SOA Record (Start of Authority Record):
- Contains administrative information about a DNS zone, including the primary name server, email of the domain administrator, domain serial number, and timers relating to refreshing the zone.

Understanding these record types is helpful when analyzing Pi-hole's query log, as you'll see requests for various record types.

How Online Advertising Works

Online advertising is a multi-billion dollar industry and the primary revenue model for a vast portion of the "free" internet. Understanding its mechanics helps clarify why ad blocking tools like Pi-hole are effective.

Ad Servers and Trackers

When you visit a website that displays ads, the following typically happens:

Page Load: Your browser requests the main content of the webpage (e.g., an article from news-website.com).
Ad Space Allocation: The HTML code of the webpage contains designated spaces (often <iframe> elements or JavaScript tags) for advertisements.
Ad Network Communication: Embedded scripts on the page communicate with ad servers or ad exchanges. These are platforms run by companies like Google (Google AdSense, DoubleClick), Meta, Amazon, and many others.
- The script might send information about the website, the user (if known through cookies or other tracking mechanisms), and the ad slot to the ad network.
Ad Selection (Real-Time Bidding - RTB):
- In many cases, an auction (Real-Time Bidding) occurs in milliseconds. Advertisers bid to display their ad to you based on your profile (demographics, browsing history, location, etc.) and the context of the website.
- The winning advertiser's ad creative (image, video, text) is selected.
Ad Content Delivery:
- The ad server instructs your browser to fetch the ad content (images, videos, scripts) from another domain, often a Content Delivery Network (CDN) associated with the ad or the advertiser.
- Your browser makes new DNS requests for these ad-serving domains. This is where Pi-hole can intervene by blocking these specific domains.
Tracking Scripts:
- Alongside ads, websites and ad networks often load tracking scripts. These scripts can:
  - Place cookies in your browser to identify you across different websites.
  - Use tracking pixels (tiny, invisible images) to log page views and user interactions.
  - Employ browser fingerprinting techniques to create a unique profile of your browser and system configuration.
  - Collect data on your browsing habits, search queries, clicks, location, device type, and more.
- This data is sent to analytics servers or data brokers.

The ecosystem is vast, involving publishers (websites displaying ads), advertisers (companies wanting to promote products/services), ad networks/exchanges (intermediaries), and data management platforms.

The Privacy Implications

The pervasive nature of online advertising and tracking raises significant privacy concerns:

Data Collection: Vast amounts of personal data are collected, often without explicit, informed consent. Users may not be aware of how much data is being gathered or by whom.
Profiling: This data is used to create detailed user profiles, which can include sensitive information about interests, habits, health, financial status, and more.
Targeted Advertising: While sometimes convenient, highly targeted ads can feel intrusive and manipulative. They can also lead to price discrimination or exclusion from certain opportunities.
Lack of Transparency and Control: It's often difficult for users to know what data is collected, how it's used, who it's shared with, and how to opt-out effectively.
Security Risks: Malvertising (malicious ads) can deliver malware or direct users to phishing sites. Ad networks, despite efforts, can sometimes be exploited to distribute harmful content.
Filter Bubbles and Echo Chambers: Personalized content and ads can reinforce existing beliefs and limit exposure to diverse perspectives.

Pi-hole, by blocking many ad and tracking domains, helps mitigate some of these privacy risks by reducing the amount of data that can be exfiltrated from your devices.

Methods of Ad Blocking

There are several approaches to blocking online advertisements, each with its pros and cons.

Browser Extensions

How they work: These are add-ons installed directly into web browsers (e.g., uBlock Origin, AdBlock Plus). They typically work by:
- Content Filtering: Analyzing the HTML, CSS, and JavaScript of a webpage as it loads.
- Element Hiding: Using CSS rules to hide ad elements on the page.
- Request Blocking: Intercepting network requests made by the browser and blocking those to known ad/tracking domains based on filter lists.
Pros:
- Generally effective for ads within the browser.
- Often highly customizable with various filter lists and whitelisting options.
- Can block more sophisticated ads that rely heavily on client-side scripts.
- Some can block cosmetic elements (e.g., empty ad spaces).
Cons:
- Browser-specific: Only protect the browser they are installed in. Ads in other applications, mobile apps, or on smart TVs are not blocked.
- Resource Intensive: Can consume CPU and RAM, potentially slowing down the browser, especially with many tabs or complex filter lists.
- Requires Installation on Every Device/Browser: Needs to be set up and maintained individually.
- "Acceptable Ads" Programs: Some browser ad blockers have programs that allow certain "non-intrusive" ads by default, which may be controversial.
- Vulnerable to Anti-Adblock Scripts: Websites are increasingly deploying scripts to detect and circumvent browser-based ad blockers.

Network-Level Blocking (Pi-hole's Approach)

How it works: As discussed, Pi-hole acts as a DNS sinkhole. It prevents devices on the network from even resolving the domain names of ad servers and trackers.
Pros:
- Network-wide: Protects all devices on the network that are configured to use Pi-hole as their DNS server. This includes computers, smartphones, tablets, smart TVs, IoT devices, etc.
- Blocks Ads in Apps: Effective at blocking ads embedded within mobile applications and other non-browser software.
- Lightweight on Client Devices: No software needs to be installed on individual devices, so there's no performance impact on them.
- Centralized Management: Configuration, whitelisting, and blocklist updates are managed in one place.
- Improved Privacy for All Devices: Reduces tracking across the entire network.
Cons:
- DNS-Level Only: Primarily blocks ads by preventing domain resolution. It generally cannot block:
  - Ads served from the same domain as the content (e.g., YouTube ads, Facebook sponsored posts, Twitter promoted tweets).
  - Ads that are embedded directly or served via IP addresses without a separate domain lookup that Pi-hole can intercept.
  - It usually doesn't hide the empty spaces where ads would have appeared (though some browsers might collapse these).
- Over-blocking Potential: Can sometimes block legitimate content if a domain is too aggressively listed or if a service uses the same domain for both content and ads/tracking. Whitelisting is then necessary.
- Requires Network Configuration: Needs to be set up at the network level (router) or on individual devices to point to the Pi-hole.
- Single Point of Failure (if not redundant): If the Pi-hole device goes down, DNS resolution for the entire network can fail, leading to an inability to access the internet (unless clients have a secondary DNS configured or fallback mechanisms).

Complementary Approach: Many users find that using Pi-hole for network-wide blocking in conjunction with a good browser-based ad blocker (like uBlock Origin) offers the most comprehensive solution. Pi-hole catches the majority of ads and trackers network-wide, while the browser extension can handle more nuanced in-browser ads and cosmetic filtering.

Workshop Analyzing DNS Traffic with `tcpdump`

This workshop will give you a hands-on feel for DNS traffic by capturing and observing DNS queries made by your computer before Pi-hole is installed. This helps illustrate what Pi-hole will eventually manage.

Objective:

To use tcpdump (a powerful command-line packet analyzer) on your Linux VM (or your host Linux/macOS machine if preferred) to capture and inspect live DNS queries.

Prerequisites:

Your Linux VM (created in the previous workshop) or a Linux/macOS system.
tcpdump installed. On Debian/Ubuntu: sudo apt install tcpdump -y. On Fedora: sudo dnf install tcpdump -y. macOS usually has it pre-installed.
Internet connectivity.

Steps:

Open a Terminal:
- If using the VM, SSH into it or use its console.
- If using your host machine, open your standard terminal application.
Identify Your Network Interface:
- You need to know which network interface tcpdump should listen on.
- Run:
```
ip addr
```
  or
```
ifconfig
```
- Look for your active network interface. On a VM, it might be enp0s3 or eth0. On a physical machine, it could be wlan0 (Wi-Fi) or eth0/enpXsY (Ethernet). Note this interface name. Let's assume it's eth0 for this example.
Start Capturing DNS Traffic with tcpdump:
- DNS typically uses UDP port 53, but can also use TCP port 53 for larger responses or zone transfers. We will focus on UDP.
- Run the following command (replace eth0 with your actual interface name):
```
sudo tcpdump -i eth0 -n -vvv port 53
```
  - sudo: tcpdump needs root privileges to capture network packets.
  - -i eth0: Listen on interface eth0.
  - -n: Don't convert addresses (host, port, etc.) to names. This prevents tcpdump itself from making DNS queries, which could pollute our capture.
  - -vvv: Verbose output. Shows more detail about the packets.
  - port 53: Filter for traffic on port 53 (DNS).
Generate DNS Traffic:
- While tcpdump is running in one terminal, open a new terminal (or use your web browser on the machine whose traffic you are capturing).
- Try to resolve some domain names using ping or nslookup or by visiting websites:
  - In the new terminal:
```
ping -c 1 www.google.com
ping -c 1 www.wikipedia.org
ping -c 1 nonexistentsite12345.com
nslookup www.cloudflare.com
```
  - Or, open a web browser and visit a few different websites. Many requests will be generated.
Observe tcpdump Output:
- Switch back to the terminal running tcpdump. You should see output similar to this (the format might vary slightly):
```
10:35:15.123456 IP (tos 0x0, ttl 64, id 12345, offset 0, flags [DF], proto UDP (17), length 60)
    192.168.1.100.54321 > 8.8.8.8.53: [udp sum ok] 1+ A? www.google.com. (32)
10:35:15.234567 IP (tos 0x0, ttl 120, id 54321, offset 0, flags [none], proto UDP (17), length 104)
    8.8.8.8.53 > 192.168.1.100.54321: [udp sum ok] 1 q: A? www.google.com. 1/0/0 www.google.com. A 172.217.16.196 (76)
```
- Interpreting the Output:
  - 192.168.1.100.54321 > 8.8.8.8.53: This shows a packet from your local IP (192.168.1.100) and a random high port (54321) to a DNS server (8.8.8.8 which is Google DNS) on port 53.
  - A? www.google.com.: This is a DNS query asking for the A record (IPv4 address) of www.google.com. The ? indicates a query.
  - 1+: Indicates it's a standard query.
  - The second packet is the response from 8.8.8.8.53 back to 192.168.1.100.54321.
  - 1 q: A? www.google.com. 1/0/0 www.google.com. A 172.217.16.196: This means one question was asked (A? www.google.com.), and one answer was received (www.google.com. A 172.217.16.196).
  - You'll see queries for AAAA records (IPv6), MX records if you lookup mail servers, etc.
  - If you visited a website, you'd see many more queries for various domains related to content, ads, trackers, CDNs, etc.
Stop tcpdump:
- Press Ctrl+C in the terminal where tcpdump is running.

Analysis and Reflection:

Volume of Queries: Notice how many DNS queries are made even for simple web browsing.
Third-Party Domains: If you browsed a complex website, you likely saw queries to many domains you didn't type directly – these are for ads, trackers, analytics, fonts, CDNs, etc. Pi-hole will target many of these.
Query Types: Identify different query types (A, AAAA).
Destination DNS Server: Observe which DNS server IP address your queries are going to. This is the server Pi-hole will replace or sit in front of.

This workshop provides a practical glimpse into the DNS traffic on your network. When Pi-hole is active, it will be the destination for these queries from your client devices, and it will decide whether to block them or forward them upstream.

2. Pi-hole Installation and Initial Setup

With a foundational understanding of DNS and ad blocking, we can now proceed with installing Pi-hole. This section covers hardware choices, operating system preparation, the installation process itself, and crucial post-installation steps.

Choosing Your Hardware

Pi-hole is incredibly versatile and can run on a variety of hardware platforms. Your choice will depend on your budget, technical comfort, existing hardware, and the scale of your network.

Raspberry Pi (Recommended)

Why it's popular: The Raspberry Pi is a credit-card-sized single-board computer (SBC) that is low-cost, power-efficient, and has a large community, making it an ideal platform for Pi-hole. Pi-hole was originally developed for it.
Recommended Models:
- Raspberry Pi 4 Model B (2GB/4GB/8GB RAM): Offers excellent performance, Gigabit Ethernet, and ample RAM for Pi-hole and potentially other services. The 2GB model is more than sufficient for Pi-hole.
- Raspberry Pi 3 Model B/B+: Still very capable for Pi-hole. Has built-in Wi-Fi and Ethernet.
- Raspberry Pi Zero W/WH/2 W: The Zero W/WH (Wi-Fi, pre-soldered header) and the more powerful Zero 2 W are extremely power-efficient and compact. The Zero W/WH might struggle with very large blocklists or very busy networks due to its single-core processor and limited RAM (512MB), and reliance on Wi-Fi (if not using an Ethernet adapter). The Zero 2 W is a significant improvement and a great choice for a dedicated Pi-hole.
Requirements:
- Raspberry Pi board
- MicroSD card (Class 10, 8GB minimum, 16GB or 32GB recommended for longevity and flexibility)
- Power supply (ensure it meets the Pi model's requirements)
- Case (optional, but recommended for protection)
- Ethernet cable (highly recommended over Wi-Fi for a DNS server)
Pros: Low power consumption (runs 24/7 cheaply), small footprint, dedicated device, strong community support for Pi-hole on RPi.
Cons: Initial cost of the Pi and accessories if you don't have them. SD cards can eventually wear out (though this is less of an issue with modern cards and Pi-hole's logging optimizations).

Virtual Machines (VMs)

Why use a VM: If you already have a server or a computer that runs 24/7 (e.g., a home media server, a NAS with virtualization capabilities, or even a desktop you leave on), running Pi-hole in a VM is an excellent option.
Hypervisors:
- VirtualBox (Desktop): Good for testing, learning, or if your desktop is always on. (As used in our workshop setup).
- VMware Workstation Player/Pro (Desktop): Similar to VirtualBox.
- Hyper-V (Windows Server/Pro): Native hypervisor in Windows.
- KVM/QEMU (Linux): Powerful open-source virtualization on Linux.
- Proxmox VE: Open-source virtualization management platform, popular for home labs.
- VMware ESXi: Enterprise-grade hypervisor, free version available.
VM Requirements:
- At least 512MB-1GB RAM allocated to the VM.
- 1-2 vCPUs.
- 10-20GB virtual disk space.
- Bridged networking mode for the VM so it gets its own IP address on your LAN.
Pros: Utilizes existing hardware, easy backups through VM snapshots, isolated environment.
Cons: The host machine must be running 24/7 for Pi-hole to be available. Adds a layer of complexity with virtualization management.

Docker Containers

Why use Docker: Docker allows you to run applications in isolated environments called containers. It's lightweight, fast to deploy, and manages dependencies efficiently. If you're already using Docker for other self-hosted services, adding Pi-hole is straightforward.
Requirements:
- A host system (Linux, Windows with WSL2, macOS) with Docker installed.
- Understanding of basic Docker concepts (images, containers, volumes, networking).
Pi-hole Docker Image: The official Pi-hole Docker image is available on Docker Hub (pihole/pihole).
Pros: Lightweight, fast deployment, easy updates, isolates Pi-hole from the host OS, good for running multiple services on one machine.
Cons: Requires Docker knowledge. Networking configuration (especially macvlan for a separate IP or host networking) can be tricky for beginners. Needs careful volume mapping for persistent data.

Other Single-Board Computers (SBCs)

Pi-hole can run on many other ARM-based SBCs that support a compatible Linux distribution (e.g., Odroid, Banana Pi, ASUS Tinker Board).
The installation process will be similar to a generic Linux install, provided the OS is supported.
Check compatibility and community support for your specific SBC.

For this guide's main installation workshop, we will focus on a Raspberry Pi, as it's a common and recommended starting point. However, the OS preparation and Pi-hole installation script are largely the same for other Debian/Ubuntu-based systems, including VMs.

Preparing Your Operating System

Regardless of the hardware, Pi-hole needs a compatible Linux operating system.

Raspberry Pi OS (formerly Raspbian)

The standard: This is the official OS for Raspberry Pi, based on Debian. It's the most tested and supported OS for Pi-hole on a Pi.
Installation:
1. Download Raspberry Pi Imager: From https://www.raspberrypi.com/software/.
2. Choose OS: Use the Imager to select "Raspberry Pi OS (other)" and then "Raspberry Pi OS Lite (32-bit or 64-bit)". The "Lite" version is recommended as it's command-line only and uses fewer resources. A 64-bit OS is preferable on compatible Pis (Pi 3, 4, Zero 2 W) for better performance, though 32-bit works perfectly fine.
3. Choose Storage: Select your microSD card.
4. Advanced Options (Crucial for headless setup): Before writing, click the gear icon in Raspberry Pi Imager:
  - Set hostname: e.g., pihole.local
  - Enable SSH: Choose "Use password authentication".
  - Set username and password: Create a user (e.g., pi) and a strong password.
  - Configure wireless LAN: If you must use Wi-Fi (Ethernet is preferred), enter your SSID and password here.
  - Set locale settings: Configure your time zone and keyboard layout.
5. Write: Click "Write" to flash the OS to the microSD card.
First Boot & Initial Configuration (if not fully set by Imager):
1. Insert the microSD card into the Pi, connect Ethernet, and power it on.
2. Find the Pi's IP address (your router's DHCP client list, or use a network scanner like nmap or "Advanced IP Scanner").
3. SSH into the Pi: ssh pi@<IP_ADDRESS_OF_PI> (use the username and password you set).
4. Update System:
```
sudo apt update
sudo apt full-upgrade -y
sudo reboot # If kernel or firmware was updated
```
5. Set Static IP (if not done via router reservation): This is critical. See "Setting a Static IP Address for Pi-hole" below.

Debian/Ubuntu (for VMs or other hardware)

Installation: Install your chosen Debian or Ubuntu server version (LTS recommended, minimal/server install without a GUI). Our previous workshop created a Debian VM.
Initial Configuration:
1. Log in (console or SSH).
2. Update System:
```
sudo apt update
sudo apt upgrade -y # or full-upgrade for Debian
sudo reboot # If necessary
```
3. Install Prerequisites (usually included in server installs, but good to check):
```
sudo apt install -y curl sudo git whiptail # whiptail is for the dialog-based installer
```
4. Set Static IP: See "Setting a Static IP Address for Pi-hole" below.

CentOS/Fedora (and other RPM-based distributions)

Pi-hole officially supports Fedora and CentOS Stream.
Installation: Install your chosen distribution (minimal server install).
Initial Configuration:
1. Log in.
2. Update System:
  - Fedora: sudo dnf update -y && sudo dnf upgrade -y
  - CentOS Stream: sudo dnf update -y
  - Reboot if necessary.
3. Install Prerequisites:
```
sudo dnf install -y curl sudo git dialog # dialog is whiptail's equivalent
```
4. Set Static IP: See "Setting a Static IP Address for Pi-hole" below.
5. Firewall: These systems often use firewalld. You'll need to allow DNS (port 53 TCP/UDP) and HTTP (port 80 TCP) for the web interface:
```
sudo firewall-cmd --permanent --add-service=dns
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --reload
```

The One-Step Automated Install

Pi-hole provides a convenient automated installation script that simplifies the process significantly.

Before you run the script, ensure your system is up-to-date and you have set a static IP address for the Pi-hole host (or know how you will set it during/after the install).

Open a terminal on the device where you want to install Pi-hole (e.g., SSH into your Raspberry Pi or VM).
Execute the installer command:
```
curl -sSL https://install.pi-hole.net | sudo bash
```
- curl -sSL: Downloads the script. -s is silent, -S shows errors, -L follows redirects.
- | sudo bash: Pipes the downloaded script directly to bash to be executed with sudo (root) privileges.
Security Note: Piping directly to bash is common but carries a small risk if the source is compromised. Advanced users might download the script first, inspect it, and then run it:
```
curl -sSL https://install.pi-hole.net -o pihole_install.sh
nano pihole_install.sh # Inspect the script
sudo bash pihole_install.sh
```
Follow the On-Screen Prompts: The installer uses a dialog-based interface.
- Initial Welcome/Information Screens: Read and press Enter/OK.
- Static IP Address Reminder: It will emphasize the need for a static IP.
- Choose Upstream DNS Provider:
  - You'll be presented with a list of common public DNS providers (Google, Cloudflare, Quad9, OpenDNS, etc.) or the option to specify a custom one.
  - Recommendation for beginners: Choose a well-known provider like Cloudflare (offers privacy focus, DoH/DoT options for later) or Quad9 (security focus, blocks malicious domains). You can change this later.
  - Use arrow keys to navigate, Spacebar to select/deselect, Tab to move between buttons, Enter to confirm.
- Select Blocklists (Adlists):
  - Pi-hole comes with a few default adlists. It's generally fine to accept the defaults to start. You can add more later.
  - Select the lists you want (StevenBlack's unified list is a good default).
- Select IP Protocols:
  - Choose whether to block ads over IPv4, IPv6, or both. If your network uses IPv6, enable it here. Most home networks primarily use IPv4.
- Set Static IP Address (Installer Option):
  - The installer may offer to use your current network configuration for the static IP address.
  - It will show your current IP address and gateway. Verify these are correct.
  - If you agree, it will configure the system to use this IP statically.
  - Important: If you choose "Yes" here, ensure this IP is outside your router's DHCP range or that you have a DHCP reservation for this IP on your router to prevent IP conflicts.
  - If you previously set a static IP manually (recommended method for more control), you can review the settings here.
- Install Web Admin Interface:
  - Select "On" (default and highly recommended) to install the web interface for managing Pi-hole.
- Install Web Server (lighttpd):
  - Select "On" (default and recommended) to install the lighttpd web server, which Pi-hole uses to serve its admin interface. If you have another web server (like Apache or Nginx) running on port 80, you might need to resolve conflicts or choose not to install lighttpd (advanced).
- Log Queries:
  - Select "On" (default and recommended) to enable query logging. This is essential for seeing what Pi-hole is doing, troubleshooting, and viewing statistics. You can adjust log levels later.
- Privacy Mode for FTL:
  - Choose a privacy level for the statistics shown on the dashboard.
    - Show everything and record everything: Most detailed.
    - Hide domains and clients: Anonymizes data.
    - Anonymous mode: Highest privacy, less useful stats.
    - Recommendation for learning: "Show everything" is fine for a home network. You can change this later.
- The installation will now proceed, downloading and configuring packages. This may take a few minutes.
Installation Complete Screen:
- Once finished, you'll see an "Installation Complete!" screen.
- CRITICAL INFORMATION - DO NOT MISS THIS: This screen displays:
  - Your Pi-hole's IPv4 and/or IPv6 address(es).
  - The web interface URL: http://<PIHOLE_IP_ADDRESS>/admin or http://pi.hole/admin (if pi.hole resolves on your network).
  - Your web interface login password. This password is randomly generated. Record it securely! You can change it later.
- Press "Ok" to finish.

Post-Installation Steps

Accessing the Web Interface

Open a web browser on a device connected to the same network as your Pi-hole.
Navigate to the web interface URL provided at the end of the installation (e.g., http://192.168.1.50/admin, replacing 192.168.1.50 with your Pi-hole's actual static IP address).
You should see the Pi-hole login page.
Enter the password that was displayed at the end of the installation.
You are now logged into the Pi-hole dashboard. Explore it, but don't change too much yet.

Setting a Static IP Address for Pi-hole

This is the most critical step for Pi-hole to function reliably. If Pi-hole's IP address changes, your devices will no longer be able to use it for DNS, and your internet access might break.

There are two main ways to set a static IP:

Method 1: DHCP Reservation on Your Router (Recommended for Simplicity)

Concept: You tell your router's DHCP server to always assign the same IP address to the Pi-hole device based on its MAC address. The Pi-hole device itself remains configured to obtain an IP via DHCP, but the router ensures it always gets the reserved IP.
Steps:
1. Find Pi-hole's MAC Address:
  - On the Pi-hole device, run: ip link show eth0 (or your Ethernet interface name, e.g., enp0s3).
  - Look for the "link/ether" address (e.g., b8:27:eb:xx:yy:zz).
2. Log into Your Router's Admin Interface: Usually an IP like 192.168.1.1 or 192.168.0.1.
3. Find DHCP Settings: Look for sections like "DHCP Server," "Client List," "Static Leases," or "Address Reservation."
4. Add a Reservation:
  - You'll typically need to provide the MAC address of the Pi-hole and the desired IP address.
  - Choose an IP address:
    - It must be within your network's subnet (e.g., if your router is 192.168.1.1, use something like 192.168.1.50).
    - It should ideally be outside the range of IPs your router dynamically assigns (DHCP pool). Check your router's DHCP settings for its start and end IP range. If the range is, for example, 192.168.1.100 to 192.168.1.200, choose an IP like 192.168.1.50. If you must pick an IP within the DHCP pool, reservation is key.
5. Save the settings on your router.
6. Reboot the Pi-hole device (sudo reboot) or restart its networking service for it to pick up the reserved IP if it doesn't already have it.
Pros: Centralized IP management on the router. OS on Pi-hole can be left as DHCP client.
Cons: Router interface varies; finding the setting can be tricky.

Method 2: Manually Configuring Static IP on the Pi-hole Device (More Control)

Concept: You directly edit network configuration files on the Pi-hole's OS to set a static IP.
Important: If you do this, make sure the chosen IP is outside your router's DHCP pool to avoid IP address conflicts.

For Raspberry Pi OS / Debian / Ubuntu (using dhcpcd or systemd-networkd or Netplan):

If using dhcpcd (common on Raspberry Pi OS Lite): Edit /etc/dhcpcd.conf:

sudo nano /etc/dhcpcd.conf

Add or uncomment and modify these lines (at the end of the file is fine), replacing values with your network's details and desired static IP. Use eth0 or your actual interface name.

interface eth0
static ip_address=192.168.1.50/24    # Desired static IP / CIDR subnet mask
static routers=192.168.1.1           # Your router's IP address (gateway)
static domain_name_servers=1.1.1.1 8.8.8.8 # Upstream DNS servers for the Pi-hole *itself*
                                        # (NOT the Pi-hole IP). Can be any public DNS.
                                        # Pi-hole will use these if it needs to resolve something for its own operations.

/24 means a subnet mask of 255.255.255.0.
static domain_name_servers: It's good practice to point the Pi-hole host itself to external DNS servers for its own lookups, rather than itself, to avoid potential startup loops. Save the file (Ctrl+X, then Y, then Enter). Reboot: sudo reboot.

If using systemd-networkd (some modern Debian/Ubuntu server installs): Configuration is in /etc/systemd/network/. Create a file like 10-static-eth0.network:

sudo nano /etc/systemd/network/10-static-eth0.network

Add:

[Match]
Name=eth0 # Or your interface name

[Network]
Address=192.168.1.50/24
Gateway=192.168.1.1
DNS=1.1.1.1
# DNS=8.8.8.8 # Can add multiple DNS lines

Save, then enable and restart systemd-networkd:

sudo systemctl enable systemd-networkd
sudo systemctl restart systemd-networkd

If using Netplan (common on modern Ubuntu Server): Configuration is in /etc/netplan/. Edit the YAML file there (e.g., 01-netcfg.yaml or 50-cloud-init.yaml). The syntax is very specific (YAML indentation matters). Example:

network:
  version: 2
  ethernets:
    eth0: # Or your interface name
      dhcp4: no
      addresses: [192.168.1.50/24]
      gateway4: 192.168.1.1 # 'gateway4' was deprecated, use routes
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [1.1.1.1, 8.8.8.8]

Save, then apply: sudo netplan apply.

Verify: After rebooting or applying changes, check the IP address: ip addr show eth0. Ensure it's the static IP you set.

Recommendation: For most users, DHCP reservation on the router is easier to manage. If you're comfortable with Linux networking, manual configuration offers more direct control. The Pi-hole installer might offer to set a static IP for you; if you used that, double-check it's correct and won't conflict.

Understanding the Dashboard

Once you can log in to the Pi-hole web admin interface, take a moment to familiarize yourself with the main dashboard elements:

Total Queries: Number of DNS queries Pi-hole has processed.
Queries Blocked: Number and percentage of queries blocked.
Percent Blocked: Visual representation of blocked queries.
Domains on Blocklist: Total number of domains in your aggregated blocklists.
Graphs:
- Queries over last 24 hours: Shows query volume and blocked queries over time.
- Clients (over time): Shows activity from different client IP addresses.
- Query Types: Breakdown of DNS record types requested (A, AAAA, etc.).
- Queries Forwarded: Where Pi-hole sent allowed queries (your upstream DNS servers).
Top Permitted Domains / Top Blocked Domains: Lists the most frequently queried allowed and blocked domains.
Top Clients: Shows which devices on your network are making the most DNS queries.

At this stage, these will likely be low or empty until you configure clients to use Pi-hole.

Change Web Interface Password:
It's highly recommended to change the default admin password to something more memorable and secure.

SSH into your Pi-hole device.
Run the command:
```
pihole -a -p
```
Follow the prompts to enter and confirm your new password. Use this new password to log into the web interface.

Workshop Installing Pi-hole on a Raspberry Pi (or your VM)

This workshop will guide you through the actual Pi-hole installation on the Linux environment you've prepared (either a physical Raspberry Pi or the Debian VM from the first workshop).

Objective:

To install Pi-hole, set a static IP address for it, and access its web admin interface.

Prerequisites:

A Raspberry Pi with Raspberry Pi OS Lite installed, updated, and accessible via SSH, OR your Debian VM prepared as per previous instructions.
The device must have internet access.
You know your network's gateway IP (router IP) and a suitable static IP address to assign to Pi-hole (outside your router's DHCP pool or reserved). For this workshop, let's assume:
- Your Router IP (Gateway): 192.168.1.1
- Desired Pi-hole Static IP: 192.168.1.53 (ensure this is free and suitable for your network)
- Your Network Subnet Mask: 255.255.255.0 (which is /24 in CIDR notation)

Steps:

Connect to Your Pi-hole Host:
- SSH into your Raspberry Pi or Debian VM.
- Example: ssh student@<IP_of_VM_or_Pi>

Ensure System is Up-to-Date (Recap):

sudo apt update
sudo apt full-upgrade -y # For RPi OS/Debian
# sudo reboot if a kernel update occurred and you're prompted or unsure

Wait for it to reboot if necessary, then SSH back in.

Set a Static IP Address (Manual Method - dhcpcd example):
- We'll manually configure the static IP before running the Pi-hole installer for greater control and understanding. (If using a VM where the installer can reliably detect and set a static IP, you might let the installer handle it, but manual is good practice).
- Open the dhcpcd configuration file (common on Raspberry Pi OS):
```
sudo nano /etc/dhcpcd.conf
```
- Scroll to the bottom of the file and add the following lines, adjusting eth0 if your interface is named differently (e.g., enp0s3 for the VM):
```
interface eth0
static ip_address=192.168.1.53/24
static routers=192.168.1.1
static domain_name_servers=1.1.1.1 9.9.9.9 # For the Pi-hole host itself
```
  - interface eth0: Replace eth0 with your actual network interface name if different.
  - static ip_address=192.168.1.53/24: Your chosen static IP for Pi-hole.
  - static routers=192.168.1.1: Your router's IP.
  - static domain_name_servers: Upstream DNS for the Pi-hole server itself.
- Save the file (Ctrl+X, then Y, then Enter).
- Reboot the device to apply the new network configuration:
```
sudo reboot
```
- Wait for the device to come back online. You will now need to SSH into it using the new static IP address:
```
ssh student@192.168.1.53
```
- Verify the IP address:
```
ip addr show eth0 # or your interface name
```
  Ensure it shows inet 192.168.1.53/24.

Run the Pi-hole Installer:

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

Navigate the Installer Dialogs:
- Initial Screens: Press OK/Enter.
- Static IP Reminder: Press OK.
- Upstream DNS Provider:
  - Use arrow keys to highlight Cloudflare.
  - Press Spacebar to select it (an * should appear).
  - Press Tab to move to <Ok> and press Enter.
- Blocklists:
  - Keep the default selected list(s) (e.g., StevenBlack).
  - Press Tab to move to <Ok> and press Enter.
- IP Protocols:
  - Ensure both IPv4 and IPv6 are selected (or just IPv4 if you're certain your network doesn't use IPv6 and you don't plan to). For learning, both is fine.
  - Press Tab to move to <Ok> and press Enter.
- Static IP Address Configuration:
  - It will display your current network configuration (which should be the static IP you just set: 192.168.1.53 and gateway 192.168.1.1).
  - It will ask: "Do you want to use your current network settings as a static address?" Select <Yes>. This confirms you want to use these settings.
  - It might warn you if the IP is within a DHCP range. This is okay if you've either ensured it's outside or made a DHCP reservation for it. For this workshop, assuming 192.168.1.53 is outside your typical DHCP pool, press <Ok> if any warning appears.
- Install Web Admin Interface:
  - Select <Ok> (default is On).
- Install Web Server (lighttpd):
  - Select <Ok> (default is On).
- Log Queries:
  - Select <Ok> (default is On).
- Privacy Mode for FTL:
  - Select "Show everything and record everything" for maximum visibility during learning.
  - Select <Ok>.
- The installation will now run.
Installation Complete:
- When finished, the "Installation Complete!" screen will appear.
- VERY IMPORTANT: Write down or screenshot the IPv4 address, Web interface password, and Web interface address.
  - It should show IPv4: 192.168.1.53.
  - The password will be random.
- Press <Ok>.
Change the Web Admin Password:
- Back at the command prompt, change the admin password:
```
pihole -a -p
```
- Enter your desired new password twice. Choose something secure but memorable for you.
Access the Web Interface:
- On another computer on the same network, open a web browser.
- Go to http://192.168.1.53/admin.
- Log in with the password you just set.
- You should see the Pi-hole dashboard. Initially, there will be very little data.

Congratulations! You have successfully installed Pi-hole and can access its web interface. The next step is to configure your network devices (clients) to use Pi-hole as their DNS server.

3. Configuring Clients to Use Pi-hole

Now that your Pi-hole is installed and has a static IP address, the next crucial step is to tell your network devices (clients) to use it for DNS resolution. There are two primary methods: configuring your router or configuring individual devices.

Router Configuration (Network-Wide Blocking)

This is the recommended method for most home users as it provides network-wide ad blocking for all devices that connect to your router (both wired and wireless) without needing to configure each device individually.

Concept: You change the DNS server settings on your router to point to your Pi-hole's static IP address. When devices on your network request DNS information via DHCP from the router, the router will hand out Pi-hole's IP address as the DNS server.

Finding Your Router's DNS Settings

The exact steps vary greatly depending on your router's make and model, but the general process is similar:

Access Your Router's Admin Interface:
- Open a web browser and enter your router's IP address. Common addresses are 192.168.1.1, 192.168.0.1, 192.168.1.254, or 10.0.0.1. This is usually the "Gateway" IP address your computer uses.
- You'll need the router's admin username and password. This might be printed on a sticker on the router itself or in its manual. Common defaults (which you should have changed for security) are admin/admin, admin/password, etc.
Locate DNS Settings:
- Once logged in, look for sections related to:
  - DNS Settings
  - Network Settings
  - LAN Setup or Local Network
  - DHCP Server Settings (often DNS settings are part of the DHCP configuration)
  - Internet Settings or WAN Setup (Some routers have DNS settings here that apply to the router itself, and separate ones for the LAN/DHCP clients. You want to change the one that's provided to LAN clients.)
Change the DNS Server(s):
- You'll typically find fields for "Primary DNS Server" (or DNS Server 1) and "Secondary DNS Server" (or DNS Server 2).
- Primary DNS Server: Enter your Pi-hole's static IP address (e.g., 192.168.1.53 from our workshop).
- Secondary DNS Server: This is a point of discussion:
  - Option A: Only Pi-hole (Recommended for full blocking): Leave the secondary DNS field blank or, if your router requires an entry, re-enter your Pi-hole's IP address. This ensures all DNS queries go through Pi-hole. If Pi-hole goes down, DNS resolution will fail (forcing you to fix Pi-hole or revert settings). This gives you the most consistent blocking.
  - Option B: A Public DNS (Fallback, but may bypass Pi-hole): You could put a public DNS server (e.g., 1.1.1.1 Cloudflare, 8.8.8.8 Google) as the secondary.
    - Behavior Varies: Some devices/OSes will strictly use the primary and only use the secondary if the primary is completely unresponsive. Others might use them in a round-robin fashion or switch to the secondary if the primary is even slightly slow, which can lead to ads leaking through.
    - For troubleshooting or if Pi-hole stability is a concern initially, this offers a fallback. But for maximum ad-blocking effectiveness, using only Pi-hole is preferred.
  - Option C (Advanced): A Second Pi-hole: If you set up a second Pi-hole for redundancy, you would put its IP address here.
- Recommendation for now: Set only the Pi-hole IP as the primary DNS and leave the secondary blank or also set it to the Pi-hole IP.
Save/Apply Settings:
- Look for an "Apply," "Save," or "Save Settings" button on the router's interface.
- The router might reboot or restart its DHCP service.
Renew DHCP Leases on Client Devices:
- For devices to pick up the new DNS settings from the router, they need to renew their DHCP lease.
- The easiest way is to restart the devices (phones, computers).
- Alternatively, you can often disconnect and reconnect them from the network (e.g., turn Wi-Fi off and on for a phone, or for a computer:
  - Windows: ipconfig /release then ipconfig /renew in Command Prompt.
  - macOS: System Settings > Network > Select Interface > Details > TCP/IP > Renew DHCP Lease.
  - Linux: sudo dhclient -r then sudo dhclient (or restart networking service).

Potential Issues and Solutions

ISP-Provided Routers: Some routers provided by ISPs have locked-down firmware that prevents you from changing DNS settings.
- Solution 1 (Bridge Mode): If your ISP router supports "bridge mode" or "modem only mode," you can put it in this mode and connect your own separate, more configurable router behind it. You would then configure Pi-hole's DNS on your own router.
- Solution 2 (Pi-hole as DHCP Server): If you cannot change DNS settings on the router, you can disable the DHCP server on your router and enable Pi-hole's built-in DHCP server. Pi-hole will then manage IP address allocation and automatically provide its own IP as the DNS server. This is an intermediate/advanced topic covered later.
- Solution 3 (Individual Device Configuration): Configure devices manually (less ideal for network-wide).
DNS Rebinding Protection: Some routers have DNS rebinding protection features that might interfere with using a local DNS server like Pi-hole, especially if you try to access the admin interface via http://pi.hole.
- Solution: You may need to whitelist pi.hole or your Pi-hole's local domain in your router's DNS rebinding protection settings, or simply access Pi-hole via its IP address.
IPv6 DNS Settings: If your network uses IPv6, you might also need to configure your router's IPv6 DNS settings to point to Pi-hole's IPv6 address (if you enabled IPv6 during Pi-hole setup and your Pi-hole has a stable IPv6 address). This can be more complex as IPv6 address assignment (e.g., SLAAC, DHCPv6) varies. Often, routers advertise their own IPv6 address for DNS via Router Advertisements (RAs). You might need to disable this or find a way to advertise Pi-hole's IPv6 address. For simplicity, many start with IPv4 only.

Individual Device Configuration

If you cannot configure your router, or if you only want specific devices to use Pi-hole (e.g., for testing), you can configure DNS settings manually on each device. This overrides the DNS settings provided by the router.

General Principle: You need to find the network settings for your Wi-Fi or Ethernet connection and manually input Pi-hole's IP address as the DNS server.

Windows (10/11)

Open Settings: Right-click Start Menu > Settings.
Network & Internet:
- Select "Wi-Fi" (if wireless) or "Ethernet" (if wired).
- Click on your connected network name or "Properties."
DNS Server Assignment:
- Scroll down to "DNS server assignment" and click "Edit."
- Change from "Automatic (DHCP)" to "Manual."
- Turn on the toggle for IPv4.
- Preferred DNS: Enter your Pi-hole's static IP address (e.g., 192.168.1.53).
- Alternate DNS:
  - Leave blank (recommended for full Pi-hole effect).
  - Or, if you must, enter a public DNS (e.g., 1.1.1.1), but be aware this can allow ads if Pi-hole is slow or down.
- Click "Save."
Flush DNS Cache (Optional but Recommended):
- Open Command Prompt as Administrator.
- Type ipconfig /flushdns and press Enter.

macOS

Open System Settings (or System Preferences on older macOS): Apple Menu > System Settings.
Network: Select "Network" from the sidebar.
Select Active Interface: Choose your active connection (e.g., "Wi-Fi" or "Ethernet") from the list.
Details Button: Click the "Details..." button next to the selected interface.
DNS Tab: Select the "DNS" tab from the sidebar in the dialog.
Add DNS Server:
- Click the + button under "DNS Servers."
- Enter your Pi-hole's static IP address (e.g., 192.168.1.53).
- You can add a secondary public DNS here if desired (e.g., 1.1.1.1), but for full Pi-hole effect, only Pi-hole's IP is best. If you add a secondary, Pi-hole should be first in the list.
Click "OK," then "Apply."
Flush DNS Cache (Optional):
- Open Terminal (Applications > Utilities > Terminal).
- Type sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder and press Enter. Enter your Mac password when prompted.

Linux (NetworkManager Example)

The method varies depending on your Linux distribution and network management tool (NetworkManager, systemd-networkd, netplan). Here's an example for NetworkManager, common on desktop Linux:

Network Settings: Click on the network icon in your system tray/panel. Go to "Network Settings" or "Edit Connections."
Select Connection: Choose your active Wi-Fi or Ethernet connection and click the gear icon or "Edit."
IPv4 Settings Tab:
- Method: Change from "Automatic (DHCP)" to "Automatic (DHCP) addresses only." (This keeps DHCP for IP but lets you set DNS manually). Or, choose "Manual" if you want to set a static IP for the client too.
- DNS Servers: In the "DNS servers" field, enter your Pi-hole's IP address (e.g., 192.168.1.53). If the field expects comma-separated values, use that. Some interfaces allow multiple entries.
Apply/Save.
Restart Network or Reconnect:
```
sudo systemctl restart NetworkManager
```
Or, disconnect and reconnect the network.
Verify: Check /etc/resolv.conf. It should show nameserver 192.168.1.53.
- Note: systemd-resolved might manage /etc/resolv.conf differently. You might use resolvectl query example.com to see which server is used.

Android

Open Settings: Go to your device's Settings app.
Network & Internet (or Connections) > Wi-Fi:
- Tap and hold your connected Wi-Fi network, then choose "Modify network."
- Or, tap the gear icon next to your Wi-Fi network, then "Advanced" or "View More."
IP Settings: Change from "DHCP" to "Static."
- You'll need to re-enter the IP address for your Android device (find a free one or use its current one if it's outside the DHCP pool or reserved), Gateway (router IP), and Network prefix length (usually 24).
- DNS 1: Enter your Pi-hole's static IP address (e.g., 192.168.1.53).
- DNS 2: Leave blank or enter a public DNS (e.g., 1.1.1.1).
Save.

Alternative for Android (Private DNS - Android 9 Pie and later):

This method encrypts your DNS queries (DNS-over-TLS) if the provider supports it. Pi-hole itself doesn't do DoT out-of-the-box without extra setup (like with unbound or cloudflared). However, if your Pi-hole forwards to an upstream that can be accessed via a DoT hostname, or if you set up a DoT/DoH proxy for your Pi-hole, this can be an option.

For just pointing to Pi-hole by IP on your local network, the static IP method above is more direct for an internal Pi-hole. If your Pi-hole is accessible via a hostname that supports DoT:

Settings > Network & Internet > Advanced > Private DNS.
Select "Private DNS provider hostname."
Enter the hostname of your DoT-enabled DNS server (e.g., your-pihole-dot-hostname.com).
- Note: This usually won't be your Pi-hole's IP address. This is more for public DoT services or if you've specifically configured your Pi-hole for DoT access with a valid certificate and hostname.

iOS (iPhone/iPad)

Open Settings: Go to the Settings app.
Wi-Fi: Tap on "Wi-Fi."
Info Button: Tap the "i" (info) icon next to your connected Wi-Fi network.
Configure DNS: Scroll down and tap "Configure DNS."
Manual: Change from "Automatic" to "Manual."
Add Server:
- Tap "Add Server."
- Enter your Pi-hole's static IP address (e.g., 192.168.1.53).
- You can delete existing DNS servers (like your router's IP or ISP DNS) by tapping the red minus icon and then "Delete." It's best to have only Pi-hole listed for full effect.
Save: Tap "Save" in the top-right corner.

Verifying Pi-hole is Working

After configuring your router or devices, you need to check if Pi-hole is actually blocking ads and processing DNS queries.

Check Pi-hole Dashboard:
- Open your Pi-hole's admin interface (e.g., http://192.168.1.53/admin).
- You should start seeing an increase in "Total queries" and hopefully some "Queries Blocked" as your configured devices browse the internet.
- The "Clients (over time)" graph should start showing the IP addresses of devices using Pi-hole.
Visit Ad-Heavy Websites:
- On a device that is configured to use Pi-hole, browse some websites that are typically heavy with ads (e.g., news sites, some free game sites).
- You should see fewer ads, or ads replaced by blank spaces.
- Note: Pi-hole won't block all ads (e.g., YouTube ads, Facebook sponsored posts, ads served from the same domain as content). For those, a browser extension is still useful.
Use Test Websites:
- Visit a website designed to test ad blockers, such as:
  - https://ads-blocker.com/testing/
  - https://canyoublockit.com/ (tests various types of ads)
- See how well Pi-hole (and any browser extension you might also be using) performs.
Check Pi-hole Query Log:
- In the Pi-hole admin interface, go to "Query Log."
- As you browse, you should see DNS queries appearing in real-time from your client devices.
- Look for entries where the "Status" is "Blocked (gravity)" or "Blocked (regex/wildcard)". These are ads/trackers Pi-hole has stopped.
- You'll also see "OK (forwarded)" or "OK (cached)" for legitimate domains.
Use Command Line Tools on a Client Device:
- Open a terminal or command prompt on a client device.
- Windows: nslookup flurry.com
- Linux/macOS: nslookup flurry.com or dig flurry.com
- flurry.com is a common mobile tracking domain usually included in blocklists.
- The output should show that the query was answered by your Pi-hole's IP address, and the address returned for flurry.com should be 0.0.0.0 or your Pi-hole's IP (depending on Pi-hole's blocking mode configuration - default is NULL blocking, 0.0.0.0).
```
# Example output showing Pi-hole blocked it
Server:         192.168.1.53  # This should be your Pi-hole's IP
Address:        192.168.1.53#53

Name:   flurry.com
Address: 0.0.0.0
```
  If it shows a public IP address for flurry.com and the Server is not your Pi-hole, then that client is not using Pi-hole correctly.

If you don't see ads being blocked or queries appearing in Pi-hole:

Double-check the DNS settings on your router/device.
Ensure the client device has renewed its DHCP lease or has been restarted.
Verify Pi-hole's static IP is correct and reachable.
Check that the pihole-FTL service is running on your Pi-hole (sudo systemctl status pihole-FTL.service).

Workshop Configuring Your Home Router and a Test Device

This workshop will walk you through the common scenario of configuring your home router to use Pi-hole, and then verifying its operation on a test client device.

Objective:

Configure your home router to distribute Pi-hole's IP as the DNS server.
Configure one specific test device (e.g., your computer or phone) to explicitly use Pi-hole for DNS (as a fallback or for initial testing).
Verify that Pi-hole is blocking ads for these devices.

Prerequisites:

Pi-hole installed and running with a known static IP (e.g., 192.168.1.53 from the previous workshop).
Access to your home router's admin interface and credentials.
A test client device (e.g., your main computer or smartphone).

Part 1: Router Configuration

Find Your Router's IP and Login:
- On your computer, find your "Default Gateway" IP.
  - Windows: ipconfig in Command Prompt.
  - macOS/Linux: ip route | grep default in Terminal.
- Open this IP in a web browser and log in to your router.
Locate DNS Settings:
- Navigate through your router's menus. Look for "DHCP Server," "LAN Setup," "Network Settings," or "DNS." This varies greatly by router.
- Self-Correction/Troubleshooting Tip: If you can't find it, search online: "[Your Router Model] change DNS settings".
Set Pi-hole as DNS Server:
- In the DNS server fields for your LAN/DHCP:
  - Primary DNS / DNS Server 1: Enter your Pi-hole's static IP (e.g., 192.168.1.53).
  - Secondary DNS / DNS Server 2:
    - Option 1 (Recommended): Leave blank if allowed.
    - Option 2 (If blank not allowed): Re-enter your Pi-hole's IP (192.168.1.53).
    - Option 3 (For temporary fallback during testing only): Enter a public DNS like 1.1.1.1. Remember the potential downsides mentioned earlier.
- Save/Apply the settings. Your router might restart or just apply them.
Renew DHCP Lease on a Test Client (e.g., your computer):
- Windows:
```
ipconfig /release
ipconfig /renew
ipconfig /all
```
  In the output of ipconfig /all, check the "DNS Servers" line. It should now list your Pi-hole's IP.
- macOS: System Settings > Network > [Your Connection] > Details... > TCP/IP > Renew DHCP Lease. Then check the DNS server listed under the DNS tab.
- Linux (NetworkManager):
```
sudo dhclient -r
sudo dhclient
cat /etc/resolv.conf
```
  /etc/resolv.conf should show nameserver 192.168.1.53.

Part 2: Manual Configuration on a Second Test Device (e.g., Your Smartphone - Optional but good for specific testing)

Let's say you want your smartphone to definitely use Pi-hole, or your router configuration isn't working as expected yet.

On Your Smartphone (Android/iOS):
- Follow the steps outlined previously in "Individual Device Configuration" for Android or iOS.
- Go to your Wi-Fi settings for your current network.
- Manually set the DNS server to your Pi-hole's IP address (192.168.1.53).
- Leave the secondary DNS blank or also set it to Pi-hole's IP.
- Save the settings.

Part 3: Verification

Access Pi-hole Dashboard:
- Open http://192.168.1.53/admin in a browser on any device on your network.
- Log in.
Generate Traffic from Test Devices:
- On your computer (which should now be getting DNS from Pi-hole via the router) and/or your smartphone (manually configured), browse several websites, especially those known for ads (e.g., news sites, speedtest.net which usually has ads).
- Open a few apps on your phone that typically show ads.
Observe Pi-hole Dashboard:
- You should see the "Total queries" count increasing.
- "Queries Blocked" and "Percent Blocked" should start to show non-zero values.
- Under "Top Clients" or in the "Clients (over time)" graph, you should see the IP addresses of your test computer and/or smartphone.
Check Query Log:
- Go to "Query Log" in the Pi-hole admin interface.
- You should see requests from your test devices.
- Look for domains being blocked (e.g., googleadservices.com, doubleclick.net, various analytics domains). Their status will be "Blocked (gravity)".
Test Ad Blocking Visually:
- On the test devices, revisit the ad-heavy websites. Do you see fewer ads? Are some ad slots blank?
- Visit https://ads-blocker.com/testing/. How does it score?
Command-Line DNS Test (from your computer):
- Open Command Prompt (Windows) or Terminal (macOS/Linux).
- Type: nslookup doubleclick.net
- Expected Output:
```
Server:  pihole.lan   # Or your Pi-hole's IP/hostname
Address: 192.168.1.53 # Your Pi-hole's IP

Name:    doubleclick.net
Addresses: ::          # If IPv6 NULL blocking
           0.0.0.0     # If IPv4 NULL blocking
```
  This confirms your Pi-hole intercepted and blocked the query. If it shows a public IP for doubleclick.net, that client isn't using Pi-hole correctly.

Troubleshooting during Workshop:

No queries on Pi-hole:
- Client device didn't get the new DNS settings: Reboot client or manually renew DHCP.
- Router settings didn't apply: Double-check router config, save, and reboot router if needed.
- Wrong Pi-hole IP set on router/client.
Ads still showing:
- Pi-hole might not block all ads (e.g., first-party ads, YouTube).
- The specific ad domain might not be on your current blocklists.
- Client might be using a secondary public DNS (check client's DNS config again).
- Browser or OS might have its own "Secure DNS" (DoH) feature enabled that bypasses Pi-hole (e.g., in Chrome, Firefox). You might need to disable this on the client for Pi-hole to be effective.

By completing this workshop, you've taken the most significant step in making Pi-hole the DNS guardian for your network. The following sections will delve into refining its configuration and understanding its features more deeply.

DNS Ad Blocker Pi-hole

Introduction to Pi-hole

What is Pi-hole?

How Pi-hole Works The Magic of DNS Sinkholing

Benefits of Using Pi-hole

System Requirements

Workshop Setting Up Your Learning Environment

1. Understanding DNS and Ad Blocking Fundamentals

What is DNS (Domain Name System)?

DNS Resolution Process

DNS Record Types

How Online Advertising Works

Ad Servers and Trackers

The Privacy Implications

Methods of Ad Blocking

Browser Extensions

Network-Level Blocking (Pi-hole's Approach)

Workshop Analyzing DNS Traffic with tcpdump

2. Pi-hole Installation and Initial Setup

Choosing Your Hardware

Raspberry Pi (Recommended)

Virtual Machines (VMs)

Docker Containers

Other Single-Board Computers (SBCs)

Preparing Your Operating System

Raspberry Pi OS (formerly Raspbian)

Debian/Ubuntu (for VMs or other hardware)

CentOS/Fedora (and other RPM-based distributions)

The One-Step Automated Install

Post-Installation Steps

Accessing the Web Interface

Setting a Static IP Address for Pi-hole

Understanding the Dashboard

Workshop Installing Pi-hole on a Raspberry Pi (or your VM)

3. Configuring Clients to Use Pi-hole

Router Configuration (Network-Wide Blocking)

Finding Your Router's DNS Settings

Potential Issues and Solutions

Individual Device Configuration

Windows (10/11)

macOS

Linux (NetworkManager Example)

Android

iOS (iPhone/iPad)

Verifying Pi-hole is Working

Workshop Configuring Your Home Router and a Test Device

Workshop Analyzing DNS Traffic with `tcpdump`