Jkotran: Corrected booleans

2026-05-28T03:44:24Z

Corrected booleans

← Older revision		Revision as of 03:44, 28 May 2026
Line 154:		Line 154:
	settings = {		settings = {
	Resolve = {		Resolve = {
	DNSStubListener = ~~"no"~~;		DNSStubListener = false;
	MulticastDNS = ~~"no"~~;		MulticastDNS = false;
	};		};
	};		};

Jkotran: Corrected MulticastDNS boolean

2026-05-28T03:41:31Z

Corrected MulticastDNS boolean

← Older revision		Revision as of 03:41, 28 May 2026
Line 155:		Line 155:
	Resolve = {		Resolve = {
	DNSStubListener = "no";		DNSStubListener = "no";
	MulticastDNS = "~~off~~";		MulticastDNS = "no";
	};		};
	};		};

Jkotran: Updated services.resolved for NixOS 26.05 Yarara syntax.

2026-05-28T03:39:43Z

Updated services.resolved for NixOS 26.05 Yarara syntax.

← Older revision		Revision as of 03:39, 28 May 2026
Line 5:		Line 5:
	'''Presumptions'''		'''Presumptions'''

	* NixOS 25.~~11 xantusia~~ (or newer)		* NixOS 26.05 Yarara (or newer)
	* Classic channels configuration		* Classic channels configuration
	* Personal home network		* Personal home network
Line 152:		Line 152:

	resolved = {		resolved = {
	~~extraConfig~~ = ''		settings = {
	DNSStubListener=no		Resolve = {
	MulticastDNS=off		DNSStubListener = "no";
	'';		MulticastDNS = "off";
			};
			};
	};		};
	};		};

Jkotran: Initial commit

2025-12-18T22:47:45Z

Initial commit

New page

Pi-hole is software that blocks ads and trackers across your entire network.

It provides a mature, trusted, integrated service that includes a web interface, DHCP server, and DNS server.

'''Presumptions'''

* NixOS 25.11 xantusia (or newer)
* Classic channels configuration
* Personal home network
* IPv4
* Homelab skills
* Patient users while you tinker and stabilize

''Please extrapolate for other NixOS versions, configurations, flakes, et cetera.''


== Basic Setup ==

<ol style="list-style-type: decimal;">
<li>Create /etc/nixos/pi-hole.nix and add the following. Replace ''homelab.me'' and the IPs with your own DNS domain and network addresses. If you don’t have a DNS domain, you can create your own. No fee or registration is required. It’s private to your network.
<syntaxhighlight lang="nix">#
# pi-hole.nix
#
# Notes
# - Pi-hole doesn't have a mechanism to manage Groups, Clients, or
# Domains. Use the web gui.
# - https://docs.pi-hole.net/group_management/example/
#
{lib, ...}: {
#
# Networking
#
# Essential infrastructure
# - List your most essential network resources here
networking = {
hosts = {
"192.168.33.1" = ["gateway.homelab.me" "gateway"];
"192.168.33.2" = ["pi-hole.homelab.me" "pi-hole"];
"192.168.33.15" = ["nas.homelab.me" "nas"];
};
};

#
# Services
#
services = {
# I'm not actually using the dnsmasq service. Pi-hole provides
# it's own dnsmasq. I'm using Nix' ability to manage the
# dnsmasq-style configuration file that Pi-hole utilizes.
dnsmasq = {
enable = false;
settings = {
address = [
"/feelinsonice-hrd.appspot.com/ # Block Snapchat"
"/feelinsonice.appspot.com/ # Block Snapchat"
"/snapchat.com/ # Block Snapchat"
];
dhcp-name-match = [
"set:hostname-ignore,wpad"
"set:hostname-ignore,localhost"
];
# Set DHCP option 6 to the DNS server you nodes should use.
dhcp-option = [
"vendor:MSFT,2,1i"
"6,192.168.33.2"
];
domain = [
"homelab.me,192.168.33.0/24,local"
];
};
};

pihole-ftl = {
enable = true;
lists = [
{
url = "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts";
type = "block";
enabled = true;
description = "Steven Black's HOSTS";
}
];
openFirewallDNS = true;
openFirewallDHCP = true;
openFirewallWebserver = true;
queryLogDeleter.enable = true;
settings = {
dhcp = {
active = false; # <-- SET TO TRUE ONLY WHEN YOU'RE READY!
end = "192.168.33.254";
hosts = [
"00:00:5e:00:53:01,192.168.33.22,jane-laptop"
"00:00:5e:00:53:ab,bill-desktop"
"00:00:5e:00:53:ff,office-printer"
];
ipv6 = false;
leaseTime = "24h";
start = "192.168.33.61";
rapidCommit = true;
resolver = {
resolveIPv6 = false;
};
router = "192.168.33.1";
};
# misc.readOnly = false;
dns = {
cnameRecords = [
"color-printer,office-printer"
"color-printer.homelab.me,office-printer.homelab.me"
];
domain = "homelab.me";
domainNeeded = true;
expandHosts = true;
interface = "eth0";
hosts = [
"192.168.33.1 gateway"
"192.168.33.2 pi-hole"
"192.168.33.15 nas"
];
upstreams = ["1.1.1.1" "1.1.1.2"];
};
# Let's not use Pi-hole time service. My home router provides clock.
ntp = {
ipv4.active = false;
ipv6.active = false;
sync.active = false;
};
webserver = {
api = {
# To manage the web login:
# 1) Temporarily set misc.readOnly to false in
# configuration.nix and switch to it.
# 2) Manually set a password:
# Pi-hole web console > Settings > All settings >
# Webserver and API > webserver.api.password > Value: ******
# 3) Read the generated hash:
# sudo pihole-FTL --config webserver.api.pwhash
pwhash = "$BALLOON-SHA256...";
};
session = {
timeout = 43200; # 12h
};
};
};
useDnsmasqConfig = true;
};

pihole-web = {
enable = true;
ports = [80];
};

resolved = {
extraConfig = ''
DNSStubListener=no
MulticastDNS=off
'';
};
};

#
# System
#
system.activationScripts = {
print-pi-hole = {
text = builtins.trace "building the pi-hole configuration..." "";
};
};

#
# Systemd
#
# The following silences a benign FTL.log warning:
# WARNING API: Failed to read /etc/pihole/versions (key: internal_error)
systemd.tmpfiles.rules = [
# Type Path Mode User Group Age Argument
"f /etc/pihole/versions 0644 pihole pihole - -"
];
}</syntaxhighlight></li>
<li>Update your configuration.nix to import ./pi-hole.nix
<syntaxhighlight lang="nix"> imports =
[
./hardware-configuration.nix
./pi-hole.nix
]</syntaxhighlight></li>
<li><code>nixos-switch rebuild --upgrade</code>
'''Note'''
<ul>
<li>This command presumes that you are using classic NixOS channels and not an experimental flakes configuration.</li>
<li>This command will freshen all installed packages and configuration settings.</li></ul>
</li>
<li>Browse to your new Pi-Hole service to review it and learn more.
Example: http://192.168.33.2
Avoid making settings in the GUI. Most are managed via configuration.nix, except for Group Management: Groups, Clients, and Domains. You can also temporarily disable ad/tracking blocking in the web GUI.</li></ol>


== Commentary ==

I’ve been running Pi-hole for at least three years. It’s a gem of a service that markedly improves your web browsing experience.

It was my last non-NixOS homelab service. I’m pleased that 25.11 xantusia now supports it. Please consider donating to NixOS and Pi-hole. They provide value to the public and would appreciate you reciprocating.

https://nixos.org/donate/

https://pi-hole.net/donate/

I’ve had almost no problems or negative feedback, with one notable exception. When family was applying for jobs online, I had to temporarily disable ad/tracker blocking via Pi-hole > DNS Control > Disable Blocking. I was irked to learn that mainstream companies utilize ads/trackers when submitting a resume. I’m not talking about sites like LinkedIn, which works fine. I’m talking about the employers themselves.

I host my NixOS Pi-hole in a lightweight LXC. I use two of them and a service called Keepalived to reduce the risk of an outage.

[[Category:Cookbook]]

Pi-hole - Revision history

Jkotran: Corrected booleans

Jkotran: Corrected MulticastDNS boolean

Jkotran: Updated services.resolved for NixOS 26.05 Yarara syntax.

Jkotran: Initial commit