How to: operator runbook

Use this runbook to resolve common operational alerts for the Pi-hole snap. Run the diagnostic commands first, then apply only the remediation steps that match the observed failure.

Run commands in this guide from the Pi-hole host.

Use this procedure when snap logs pihole-by-rajannpatel reports that the daemon failed to start, or when DNS resolution stops after enabling the snap.

1. Run the snap diagnostic check:

   sudo pihole snap-check

2. Check whether another service is listening on port 53:

   sudo ss -tulpn | grep ':53 '

3. If systemd-resolved is using the port, disable its DNS stub listener:

   sudo mkdir -p /etc/systemd/resolved.conf.d
   printf '[Resolve]\nDNSStubListener=no\n' | sudo tee /etc/systemd/resolved.conf.d/pihole.conf
   sudo systemctl restart systemd-resolved

4. Verify that network-bind is connected:

   snap connections pihole-by-rajannpatel

5. Connect network-bind if it is disconnected, then start the daemon:

   sudo snap connect pihole-by-rajannpatel:network-bind
   sudo snap start pihole-by-rajannpatel.pihole-ftl

Use this procedure when Pi-hole DHCP is enabled but clients do not receive IP addresses.

1. Connect the DHCP interfaces:

   sudo snap connect pihole-by-rajannpatel:network-control
   sudo snap connect pihole-by-rajannpatel:firewall-control

2. Run the diagnostic check:

   sudo pihole snap-check

3. If ports 67 or 546 are already in use, stop the other DHCP service on the network before continuing.

4. Restart the daemon:

   sudo snap restart pihole-by-rajannpatel.pihole-ftl

5. Renew the lease on one client device and confirm that it receives an address from the Pi-hole DHCP range.

Use this procedure when a feature works in an upstream Pi-hole installation but fails in the strictly confined snap.

1. Connect system-observe so the diagnostic tool can read kernel logs:

   sudo snap connect pihole-by-rajannpatel:system-observe

2. Search for Pi-hole AppArmor denials:

   sudo dmesg | grep DENIED | grep pihole

3. If denials appear, create an issue in the project repository and include the denial log. The log identifies whether the snap needs another interface connection or a confinement layout change.

Use this procedure when an administrator leaves, a password is exposed, or routine credential rotation is required.

Set the password through Pi-hole FTL so it is hashed before storage:

sudo pihole setpassword