casperklein/homeassistant-pi-hole repository overview

⁠Pi-hole for Home Assistant

The Pi-hole⁠ is a DNS sinkhole that protects your devices from unwanted content without installing any client-side software.

⁠Support

If you like the add-on and would like to support my work, you might

⁠Installation

1. Add this⁠ Home Assistant add-ons repository to your Home Assistant instance or use the button above.
2. Install the Pi-hole add-on.
3. Start the add-on.

⁠How to use DNSCrypt or DNS over HTTPS (DoH) with Pi-hole

This is achieved by using dnscrypt-proxy⁠. You have to configure one or more DNS servers for use with dnscrypt-proxy. To use Cloudflare DNS, for example, put this in the add-on configuration:

dnscrypt:
  - name: "Cloudflare 1.1.1.1"
    stamp: "sdns://AgcAAAAAAAAABzEuMS4xLjEAEmNsb3VkZmxhcmUtZG5zLmNvbQovZG5zLXF1ZXJ5"
  - name: "Cloudflare 1.0.0.1"
    stamp: "sdns://AgcAAAAAAAAABzEuMC4wLjEAEmNsb3VkZmxhcmUtZG5zLmNvbQovZG5zLXF1ZXJ5"

DNS stamps contain all the parameters required to connect to a secure DNS server as a single string. To create own stamps, you can use: https://dnscrypt.info/stamps/⁠. Or you can just use any of these public servers⁠.

In Pi-hole the following must be configured:

• Custom DNS server: 127.0.0.1#5335
• Disable all other configured DNS servers

To test your setup, visit https://1.1.1.1/help⁠. If you see "Using DNS over HTTPS (DoH): yes", all should be fine :)

⁠Pi-hole integration and custom card

If you want to integrate Pi-hole with Home Assistant, I highly recommend Bastgau's custom integration⁠. It’s better maintained and provides more features than the built-in native integration.

To set up the integration:

1. Use http://127.0.0.1:31415/api as the Address.

2. Leave the Password field blank.

Once you've set up the integration, you can also use this⁠ custom Pi-hole card.

⁠Direct HTTP/HTTPS access

You can open the Pi-hole Web UI in Home Assistant using Ingress. Simply click Open Web UI on the add-on page.

If you also want to enable direct HTTP/HTTPS access, open the add-on's Network settings and assign a port to HTTP/HTTPS.

For HTTPS, you can configure a certificate and key file located in /ssl in the add-on settings. If no certificate is provided, a self-signed certificate will be generated and used.

You can secure direct access by enabling the Authentication option in the add-on configuration. Any valid Home Assistant user account can be used to log in.