20220327 PiHole - master branch - PR 1 of 2 - continued

Adds material arising from SensorsIot#510 as an "example configuration".

Fixes a formatting issue with an escaped ampersand that shows up in the
mkdocs representation.

Reduces the nesting level of "advanced configurations".

Fixes some lingering code-fence hint inconsistencies.

Signed-off-by: Phill Kelley <[email protected]>

Author: Paraphraser

docs/Containers/Pi-hole.md

@@ -161,7 +161,7 @@ Pi-hole has its own built-in DNS server which can answer both kinds of queries.
 	4. *All* hosts on the 192.168.1 network (ie broadcast) is the reserved address "192.168.1.255". It is better to think of this as "the network prefix followed by all-one bits in the host portion".
 
 	When you set `REV_SERVER_CIDR=192.168.1.0/24` you are telling Pi-hole that *reverse queries* for the host range 192.168.1.1 through 192.168.1.254 should be sent to the `REV_SERVER_TARGET=192.168.1.5`.
-	
+
 ## <a name="webGUI"></a>Pi-hole Web GUI
 
 ### <a name="connectGUI"></a>Connecting to the GUI
@@ -206,7 +206,7 @@ Keep in mind that many Raspberry Pis have both Ethernet and WiFi interfaces. It
 
 You can use the following command to discover the MAC addresses for your Raspberry Pi's Ethernet and WiFi interfaces:
 
-```
+```bash
 $ for I in eth0 wlan0 ; do ip link show $I ; done
 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
     link/ether dc:a6:32:4c:89:f9 brd ff:ff:ff:ff:ff:ff
@@ -236,7 +236,11 @@ $ sudo resolvconf -u
 
 In words:
 
-1. `name_servers=127.0.0.1` instructs the Raspberry Pi to direct DNS queries to the loopback address. Port 53 is implied. Docker is listening to port 53 and forwards the queries to the Pi-hole container.
+1. `name_servers=127.0.0.1` instructs the Raspberry Pi to direct DNS queries to the loopback address. Port 53 is implied. If the Pi-hole container is running in:
+
+	- non-host mode, Docker is listening to port 53 and forwards the queries to the Pi-hole container;
+	- host mode, the Pi-hole container is listening to port 53.
+
 2. `name_servers_append=8.8.8.8` instructs the Raspberry Pi to fail-over to 8.8.8.8 if Pi-hole does not respond. You can replace `8.8.8.8` (a Google service) with:
 
 	* Another well-known public DNS server like `1.1.1.1` (Cloudflare).
@@ -246,13 +250,71 @@ In words:
 
 	You need slightly different syntax if you want to add multiple fallback servers. For example, suppose your fallback hosts are a local server (eg 192.168.1.2) running BIND9 and 8.8.8.8. The command would be:
 
-	```
+	```bash
 	$ echo 'name_servers_append="192.168.1.2 8.8.8.8"' | sudo tee -a /etc/resolvconf.conf
 	```
 
 3. `resolv_conf_local_only=NO` is needed so that 127.0.0.1 and 8.8.8.8 can coexist.
 4. The `resolvconf -u` command instructs Raspberry Pi OS to rebuild the active resolver configuration. In principle, that means parsing `/etc/resolvconf.conf` to derive `/etc/resolv.conf`. This command can sometimes return the error "Too few arguments". You should ignore that error.
 
+#### <a name="rpiDNSExample"></a>Example configuration
+
+Make these assumptions:
+
+1. You have followed the instructions above to add these lines to `/etc/resolvconf.conf`:
+
+	```
+	name_servers=127.0.0.1
+	name_servers_append=8.8.8.8
+	resolv_conf_local_only=NO
+	```
+
+2. The Raspberry Pi running Pi-hole has the IP address 192.168.1.50 which it obtains as a static assignment from your DHCP server.
+3. You have configured your DHCP server to provide 192.168.1.50 for client devices to use to obtain DNS services (ie, you are saying clients should use Pi-hole for DNS). 
+
+The result of the configuration appears in `/etc/resolv.conf`:
+
+```bash
+$ cat /etc/resolv.conf
+# Generated by resolvconf
+nameserver 127.0.0.1
+nameserver 192.168.1.50
+nameserver 8.8.8.8
+```
+
+Interpretation:
+
+* `nameserver 127.0.0.1` is present because of `name_servers=127.0.0.1`
+* `nameserver 192.168.1.50` is present because it was learned from DHCP
+* `nameserver 8.8.8.8` is present because of `name_servers_append=8.8.8.8`
+
+The fact that the Raspberry Pi is effectively represented twice (once as 127.0.0.1, and again as 192.168.1.50) does not matter. If the Pi-hole container stops running, the Raspberry Pi will bypass 192.168.1.50 and fail over to 8.8.8.8, failing back to 127.0.0.1 when the Pi-hole container starts again.
+
+Notes:
+
+* If you wish to prevent the Raspberry Pi from including the address(es) of DNS servers learned from DHCP, you can instruct the DHCP client running on the Raspberry Pi to ignore the information coming from the DHCP server:
+
+	```bash
+	$ echo 'nooption domain_name_servers' | sudo tee -a /etc/dhcpcd.conf
+	$ sudo service dhcpcd reload
+	$ sudo resolvconf -u 
+	```
+
+* If you have followed the steps in [Adding local domain names](#localNames) to define names for your local hosts, you can inform the Raspberry Pi of that fact like this:
+
+	```bash
+	$ echo 'search_domains=home.arpa' | sudo tee -a /etc/resolvconf.conf
+	$ sudo resolvconf -u 
+	```
+
+	That will add the following line to `/etc/resolv.conf`:
+
+	```
+	search home.arpa
+	```
+
+	Then, when you refer to a host by a short name (eg "fred") the Raspberry Pi will also consider "fred.home.arpa" when trying to discover the IP address.
+
 ## <a name="piholePrimary"></a>Using Pi-hole as your DNS resolver
 
 In order for Pi-hole to block ads or resolve anything, clients need to be told to use it as their DNS server. You can either:
@@ -272,15 +334,15 @@ Option 1 (whole-of-network) is the simplest approach. Assuming your Raspberry Pi
 
 Option 2 (case-by-case) generally involves finding the IP configuration options for each host and setting the DNS server manually. Manual changes are usually effective immediately without needing a reboot.
 
-#### <a name="advancedConfig"></a>advanced configurations
+### <a name="advancedConfig"></a>advanced configurations
 
 Setting up a combination of Pi-hole (for ad-blocking services), and/or a local upstream DNS resolver (eg BIND9) to be authoritative for a local domain and reverse-resolution for your local IP addresses, and decisions about where each DNS server forwards queries it can't answer (eg your ISP's DNS servers, or Google's 8.8.8.8, or Cloudflare's 1.1.1.1) is a complex topic and depends on your specific needs.
 
 The same applies to setting up a DHCP server (eg DHCPD) which is capable of distinguishing between the various clients on your network (ie by MAC address) to make case-by-case decisions as to where each client should obtain its DNS services. 
 
 If you need help, try asking questions on the [IOTstack Discord channel](https://discord.gg/ZpKHnks).
 
-## <a name="debugging"></a>Testing \& Troubleshooting
+## <a name="debugging"></a>Testing and Troubleshooting
 
 Install dig: