BTCPay Server

# Pi-hole

Pi-hole (opens new window) is a DNS-based network advertisement blocker.

The integration is intended only for a trusted local network. The fragment publishes TCP and UDP port 53 on every host interface and configures Pi-hole to listen on all interfaces. Do not enable it on a public VPS or any host where WAN clients can reach port 53; an exposed recursive resolver can be abused.

Before enabling the fragment, confirm that host port 53 is unused and enforce a default-deny firewall rule that permits it only from the trusted LAN. Docker published ports can bypass simple UFW rules, so use a provider firewall or a verified Docker-aware host policy such as DOCKER-USER. Verify from outside the LAN that both TCP and UDP port 53 are blocked before advertising Pi-hole through DHCP.

# How to use

Assume the local IP address of the BTCPay Server host is 192.168.1.2. From a root login shell on an existing BTCPay Server Docker deployment, enable the fragment:

btcpay-fragments add opt-add-pihole

Configure the router's DHCP server to advertise 192.168.1.2 as the DNS server. Advertising another resolver may allow clients to bypass Pi-hole.

# Using the dashboard

Set PIHOLE_SERVERIP to the host's LAN address so Pi-hole returns the correct address for its local dashboard hostname. This variable does not enable or disable the dashboard:

cd "$BTCPAY_BASE_DIRECTORY/btcpayserver-docker"
export PIHOLE_SERVERIP="192.168.1.2"
. ./btcpay-setup.sh -i

From a device using Pi-hole for DNS, browse to http://pi.hole/admin.

Set the admin password:

pihole.sh setpassword

← Electrum X →