unifios-utilities/run-pihole/README.md

# Run Pi-hole on your UDM

## Features

1. Run Pi-hole on your UDM with a completely isolated network stack.  This will not port conflict or be influenced by any changes on by Ubiquiti
2. Persists through reboots and firmware updates.

## Requirements

1. You have successfully setup the on boot script described [here](https://github.com/boostchicken-dev/udm-utilities/tree/master/on-boot-script)

## Customizations

Note: IP and VLAN settings for you pihole network, 20-dns-conflist and 10-dns.sh MUST all match each other.

* Example settings for pihole network:
  Network Name:         Pihole
  Host address:         10.0.5.1
  Netmask:              24
  VLAN ID:              5
  Network Type:         Standard
  Multicast DNS:		Enable
  DHCP:                 None
  Ipv6 Interface Type:  None


* YOU WILL NEED TO CHANGE [`20-dns.conflist`](../cni-plugins/20-dns.conflist)
  Change the line:
  "mac": "add 3 fake hex portions, replacing x's here 00:1c:b4:xx:xx:xx",
  to create a legitimate mac address that matches some vendor space(first 6 digits ).  It needs to be unique on your network.
  The example gives one option.  Locally administered mac addresses do not work.
  
  If you are using a different IP address than the example:
  Change these lines to match your settings:
            "address": "10.0.5.3/24",
            "gateway": "10.0.5.1"
			
  If you are using a different VLAN than the example:
  Change this line to match your VLAN number:
            "master": "br5",
			
* You MAY need to change[`10-dns.sh`](../dns-common/on_boot.d/10-dns.sh).
  If you are using a different IP address than the example:
  Change these lines to match your settings:
            IPV4_IP="10.0.5.3"
            IPV4_GW="10.0.5.1/24"
			
  If you are using a different VLAN than the example:
  Change this line to match your VLAN number:
            VLAN=5
			
  If you want the pihole container to have a different name than the example:
  Change this line to match the different name:
            CONTAINER=pihole
			
* If you want IPv6 support
  Use 20-dnsipv6.conflist and update 10-dns.sh with the IPv6 addresses.
  Also, please provide IPv6 servers to podman using --dns arguments.			
			
## Steps

### Configuration files and scripts

1.0 Copy [`05-install-cni-plugins.sh`](../cni-plugins/05-install-cni-plugins.sh) to `/mnt/data/on_boot.d`
1.1 Execute `chmod +x /mnt/data/on_boot.d/05-install-cni-plugins.sh`
1.2 Execute `/mnt/data/on_boot.d/05-install-cni-plugins.sh`

2.0 On your controller, create a network with no DHCP server and give it a VLAN.(see example settings above).
2.1 Copy YOUR modified [`20-dns.conflist`] to `/mnt/data/podman/cni`
2.2 Execute `chmod +x /mnt/data/podman/cni/20-dns.conflist`
2.3 Execute `cp /mnt/data/podman/cni/20-dns.conflist /etc/cni/net.d/dns.conflist`

    To check progress - run the command:
    ```shell
    podman network inspect dns
    ```
	You should see a copy of your 20-dns.conflist displayed.

3.0 Copy your [`10-dns.sh`] to `/mnt/data/on_boot.d`
3.1 Execute `chmod +x /mnt/data/on_boot.d/10-dns.sh`
3.2 Execute `/mnt/data/on_boot.d/10-dns.sh`


### Create directories for persistent Pi-hole configuration

4.0 Execute the following commands:
   ```sh
   mkdir -p /mnt/data/etc-pihole
   mkdir -p /mnt/data/pihole/etc-dnsmasq.d
   ```

### Create the pihole container

Note:
  --name MUST match the name you set in 10-dns.sh
  -e FTLCONF_REPLY_ADDR4 MUST be in the range you set for your pihole network
  -e TZ MUST match the timezone for your controller
   
The example uses these upstream DNS servers The following command sets the upstream DNS servers to `1.1.1.1` ([Cloudflare DNS](https://1.1.1.1/)) and `8.8.8.8` ([Google DNS](https://developers.google.com/speed/public-dns/)).
If you want to use different upstream DNS servers, change the following lines:
    --dns=1.1.1.1 \
    --dns=8.8.8.8 \
    
If you want to run a DHCP server as well you need to add the following lines:
    --cap-add=NET_ADMIN
		   
5.0 Run the following (or your modified version) by copy / pasting the entire set.	   
   
    ```sh
    podman run -d \ 
        --network dns \
        --restart always \
        --name pihole \
        -e TZ="America/Los Angeles" \
	--cap-add=NET_ADMIN \
        -v "/mnt/data/etc-pihole/:/etc/pihole/" \
        -v "/mnt/data/pihole/etc-dnsmasq.d/:/etc/dnsmasq.d/" \
        --dns=127.0.0.1 \
        --dns=1.1.1.1 \
        --dns=8.8.8.8 \
        --hostname pi.hole \
        -e VIRTUAL_HOST="pi.hole" \
        -e PROXY_LOCATION="pi.hole" \
        -e FTLCONF_REPLY_ADDR4="10.0.5.3" \
        -e IPv6="False" \
        pihole/pihole:latest
    ```
    
    The below errors are expected and acceptable:
      
    > ```
    > ERRO[0022] unable to get systemd connection to add healthchecks: dial unix /run/systemd/private: connect: no such file or directory
    > ERRO[0022] unable to get systemd connection to start healthchecks: dial unix /run/systemd/private: connect: no such file or directory
    > ```     

6.0 Set the pihole admin password

    ```sh
    podman exec -it pihole pihole -a -p YOURNEWPASSHERE
    ```
## Set the new DNS in your UDM

7.0 Update your DNS Servers to `10.0.5.3` (or your custom ip) for each of your Networks (UDM GUI | Networks | Advanced | DHCP Name Server)
7.1 Access the pihole web interface like you would normally, e.g. http://10.0.5.3 if using the example

## Upgrading your PiHole container

1. Edit `upd_pihole.sh` script to use the same `podman run` command you used at installation. 
2. Copy the `upd_pihole.sh` script to /mnt/data/scripts
3. Anytime you want to update your pihole installation, simply run `/mnt/data/scripts/upd_pihole.sh`

## Optional Builds

The cloudflared command is written in Go and is not very lightweight.  In my
experience, it's not made for long-term running.  Instead, the project DoTe
has a tiny memory footprint and operates on an event loop with some major
optimisations for connection caching.  It allows you to forward traffic to any
DNS-over-TLS provider.

### PiHole with CloudFlareD Command
    
    podman run -d \
        --network dns 
        --restart always \
        --name pihole \
        -e TZ="America/Los Angeles" \
        -v "/mnt/data/etc-pihole/:/etc/pihole/" \
        -v "/mnt/data/pihole/etc-dnsmasq.d/:/etc/dnsmasq.d/" \
        --dns=127.0.0.1 \
        --dns=1.1.1.1 \
        --hostname pi.hole \
        -e CLOUDFLARED_OPTS="--port 5053 --address 0.0.0.0" \
        -e VIRTUAL_HOST="pi.hole" \
        -e PROXY_LOCATION="pi.hole" \
        -e ServerIP="10.0.5.3" \
        -e PIHOLE_DNS_="127.0.0.1#5053" \
        -e IPv6="False" \
        boostchicken/pihole:latest

### PiHole with DoTe

Simply copy the `custom_pihole_dote.sh` script to `/mnt/data/scripts` and run it
to forward all DNS traffic over TLS to Cloudflare 1.1.1.1.  You can modify the
script to forward to different services with ease and full configuration
options including certificate pinning is available in the DoTe README here:
https://github.com/chrisstaite/DoTe/

    podman run -d \
        --network dns \
        --restart always \
        --name pihole \
        -e TZ="America/Los Angeles" \
        -v "/mnt/data/etc-pihole/:/etc/pihole/" \
        -v "/mnt/data/pihole/etc-dnsmasq.d/:/etc/dnsmasq.d/" \
        --dns=127.0.0.1 \
        --dns=1.1.1.1 \
        --hostname pi.hole \
        -e CLOUDFLARED_OPTS="--port 5053 --address 0.0.0.0" \
        -e VIRTUAL_HOST="pi.hole" \
        -e PROXY_LOCATION="pi.hole" \
        -e ServerIP="10.0.5.3" \
        -e PIHOLE_DNS_="127.0.0.1#5053" \
        -e IPv6="False" \
        boostchicken/pihole-dote:latest
     

##  New releases will be made when PiHole updates their labels