From 6116250ea2baa2705448f8549d47cc88c73858ae Mon Sep 17 00:00:00 2001 From: stuartofmt Date: Wed, 8 Jun 2022 01:13:19 -0600 Subject: [PATCH] Update README.md (#371) The Readme.md for run-pihole is difficult to use. There are some contradictory instructions and some of the explanations are unclear. This can lead to an unsuccessful install. This is a suggested rewrite --- run-pihole/README.md | 148 ++++++++++++++++++++++++++++++------------- 1 file changed, 103 insertions(+), 45 deletions(-) diff --git a/run-pihole/README.md b/run-pihole/README.md index 511ff60..4293354 100644 --- a/run-pihole/README.md +++ b/run-pihole/README.md @@ -9,48 +9,102 @@ 1. You have successfully setup the on boot script described [here](https://github.com/boostchicken-dev/udm-utilities/tree/master/on-boot-script) -## Customization +## Customizations -* Feel free to change [`20-dns.conflist`](../cni-plugins/20-dns.conflist) to change the IP address and MAC address of the container. -* Update [`10-dns.sh`](../dns-common/on_boot.d/10-dns.sh) with your own values -* If you want IPv6 support use [`20-dnsipv6.conflist`](../cni-plugins/20-dnsipv6.conflist) and update [`10-dns.sh`](../dns-common/on_boot.d/10-dns.sh) with the IPv6 addresses. Also, please provide IPv6 servers to podman using --dns arguments. +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 -1. Copy [`05-install-cni-plugins.sh`](../cni-plugins/05-install-cni-plugins.sh) to `/mnt/data/on_boot.d` -1. Execute `/mnt/data/on_boot.d/05-install-cni-plugins.sh` -1. On your controller, make a Corporate network with no DHCP server and give it a VLAN. For this example we are using VLAN 5. -1. Copy [`20-dns.conflist`](../cni-plugins/20-dns.conflist) to `/mnt/data/podman/cni`. This will create your podman `macvlan` network - +### 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 create dns - curl -L https://github.com/boostchicken-dev/udm-utilities/raw/master/cni-plugins/20-dns.conflist -o /etc/cni/net.d/dns.conflist + podman network inspect dns ``` - -1. Copy [`10-dns.sh`](../dns-common/on_boot.d/10-dns.sh) to `/mnt/data/on_boot.d` and update its values to reflect your environment - - ```sh - ... - VLAN=5 - IPV4_IP="10.0.5.3" - IPV4_GW="10.0.5.1/24" - ... - CONTAINER=pihole - ... - ``` + You should see a copy of your 20-dns.conflist displayed. -6. Execute `/mnt/data/on_boot.d/10-dns.sh` -1. Create directories for persistent Pi-hole configuration +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 ``` - -1. Create and run the Pi-hole docker container. 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/)). +### Create the pihole container + +Note: + --name MUST match the name you set in 10-dns.sh + -e ServerIP MUST be in the range you set for your ihole 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 \ + +5.0 Run the following (or your modified version) by copy / pasting the entire set. + ```sh - podman run -d \ + podman run -d \ --network dns \ --restart always \ --name pihole \ @@ -75,21 +129,31 @@ > ERRO[0022] unable to get systemd connection to start healthchecks: dial unix /run/systemd/private: connect: no such file or directory > ``` -1. Set pihole password +6.0 Set the pihole admin password ```sh podman exec -it pihole pihole -a -p YOURNEWPASSHERE ``` +## Set the new DNS in your UDM -1. 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) -1. Access the pihole like you would normally, e.g. http://10.0.5.3 if using examples above +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` -## PiHole with CloudFlareD Command +## 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 @@ -111,6 +175,12 @@ ### 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 \ @@ -129,17 +199,5 @@ -e IPv6="False" \ boostchicken/pihole-dote:latest -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. -#### Custom Build Instructions -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/ - -New releases will be made when PiHole updates their labels +## New releases will be made when PiHole updates their labels