Tidy up a few things in the readme and code.

Check that pihole-FTL is configured with upstream servers or it will not function!

Signed-off-by: Adam Warner <me@adamwarner.co.uk>

README.md

@@ -25,6 +25,8 @@ Using [Docker-compose](https://docs.docker.com/compose/install/):
 
 1. Copy the below docker compose example and update as needed
 
+
+
 ```yml
 version: "3"
 
@@ -33,23 +35,33 @@ services:
   pihole:
     container_name: pihole
     image: pihole/pihole:latest    
-    # For DHCP it is recommended to remove these ports and instead add: network_mode: "host"
     ports:
+      # DNS Ports
       - "53:53/tcp"
       - "53:53/udp"
-      - "67:67/udp" # Only required if you are using Pi-hole as your DHCP server
+      # Default HTTP Port
       - "80:80/tcp"
-      - "443:443/tcp" # By default, FTL will generate a self-signed certificate
+      # Default HTTPs Port. FTL Will generate a self-signed certificate
+      - "443:443/tcp"
+      # Uncomment the below if using Pi-hole as your DHCP Server
+      #- "67:67/udp"      
     environment:
-      TZ: 'America/Chicago'
+      # Set the appropriate timezone for your location (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), e.g:
-      # FTLCONF_webserver_api_password: 'set a secure password here or it will be random'
+      TZ: 'Europe/London'
+      # Set a password to access the web interface. Not setting one will result in a random password being assigned
+      FTLCONF_webserver_api_password: 'correct horse battery staple'
+      # Configure DNS upstream servers, e.g:
+      FTLCONF_dns_upstreams: '8.8.8.8, 8.8.4.4'
     # Volumes store your data between container upgrades
     volumes:
+      # For persisting Pi-hole's databases and common configuration file
       - './etc-pihole:/etc/pihole'
-     # - './etc-dnsmasq.d:/etc/dnsmasq.d' # Only needed if you have some custom configs for dnsmasq
+      # Uncomment the below if you have custom dnsmasq config files that you want to persist. Not needed for most.
-    # https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
+      #- './etc-dnsmasq.d:/etc/dnsmasq.d'    
     cap_add:
-      - NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
+      # See https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
+      # Required if you are using Pi-hole as your DHCP server, else not needed
+      - NET_ADMIN 
     restart: unless-stopped
 ```
 
@@ -72,7 +84,7 @@ It is recommended that you use environment variables to configure the Pi-hole do
 
 ### Web interface password
 
-To set a specific password for the web interface, use the environment variable `FTLCONF_webserver_api_password`. If this variable is not detected, and you have not already set one via `pihole setpassword` in the container, then a random password will be assigned on startup, this will be printed to the log. Run `docker logs pihole | grep random` to find it.
+To set a specific password for the web interface, use the environment variable `FTLCONF_webserver_api_password`. If this variable is not detected, and you have not already set one via `pihole setpassword` / `pihole-FTL --config webserver.api.password` inside the container, then a random password will be assigned on startup, this will be printed to the log. Run `docker logs pihole | grep random password` to find it.
 
 To explicitly set no password, set `FTLCONF_webserver_api_password: ''`
 
@@ -111,8 +123,7 @@ Here is a rundown of other arguments for your docker-compose / docker run.
 | `-v $(pwd)/etc-pihole:/etc/pihole`<br/> **Recommended** | Volumes for your Pi-hole configs help persist changes across docker image updates
 | `--net=host`<br/> _Optional_ | Alternative to `-p <port>:<port>` arguments (Cannot be used at same time as -p) if you don't run any other web application. DHCP runs best with --net=host, otherwise your router must support dhcp-relay settings.
 | `--cap-add=NET_ADMIN`<br/> _Recommended_ | Commonly added capability for DHCP, see [Note on Capabilities](#note-on-capabilities) below for other capabilities.
-| `--dns=127.0.0.1`<br/> _Optional_ | Sets your container's resolve settings to localhost so it can resolve DHCP hostnames from Pi-hole's DNSMasq, may fix resolution errors on container restart.
+| `--dns=n.n.n.n`<br/> _Optional_ | Explicitly set container's DNS server. It is **_not recommended_** to set this to `localhost`/`127.0.0.1`.
-| `--dns=1.1.1.1`<br/> _Optional_ | Sets a backup server of your choosing in case DNSMasq has problems starting
 | `--env-file .env` <br/> _Optional_ | File to store environment variables for docker replacing `-e key=value` settings. Here for convenience
 
 ## Tips and Tricks
@@ -165,7 +176,7 @@ The Date-based (including incremented "Patch" versions) do not relate to any kin
 | tag                 | description
 |---------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
 | `latest`            | Always latest release                                                                                                                      |
-| `2022.04`           | Date-based release                                                                                                                         |
+| `2022.04.0`         | Date-based release                                                                                                                         |
 | `2022.04.1`         | Second release in a given month                                                                                                            |
 | `dev`               | Similar to `latest`, but for the development branch (pushed occasionally)                                                                  |
 | `*beta`             | Early beta releases of upcoming versions - here be dragons                                                                                 |
@@ -184,7 +195,7 @@ Do not attempt to upgrade (`pihole -up`) or reconfigure (`pihole -r`).  New imag
     - We will try to put common break/fixes at the top of this readme too
 1. Download the latest version of the image: `docker pull pihole/pihole`
 2. Throw away your container: `docker rm -f pihole`
-    - **Warning** When removing your pihole container you may be stuck without DNS until step 3; **docker pull** before **docker rm -f** to avoid DNS interruption **OR** always have a fallback DNS server configured in DHCP to avoid this problem altogether.
+    - **Warning** When removing your pihole container you may be stuck without DNS until step 3; **docker pull** before **docker rm -f** to avoid DNS interruption.
     - If you care about your data (logs/customizations), make sure you have it volume-mapped or it will be deleted in this step.
 3. Start your container with the newer base image: `docker run <args> pihole/pihole` (`<args>` being your preferred run volumes and env vars)
 
@@ -216,11 +227,11 @@ We install all pihole utilities so the the built in [pihole commands](https://di
 
 ### Customizations
 
-The webserver and DNS service inside the container can be customized if necessary.  Any configuration files you volume mount into `/etc/dnsmasq.d/` will be loaded by dnsmasq when the container starts or restarts.
+The webserver and DNS service inside the container can be customized if necessary.  Any configuration files you volume mount into `/etc/dnsmasq.d/` will be loaded by pihole-FTL when the container starts or restarts.
 
 ## Note on Capabilities
 
-DNSMasq / [FTLDNS](https://docs.pi-hole.net/ftldns/in-depth/#linux-capabilities) expects to have the following capabilities available:
+[FTLDNS](https://docs.pi-hole.net/ftldns/in-depth/#linux-capabilities) expects to have the following capabilities available:
 
 - `CAP_NET_BIND_SERVICE`: Allows FTLDNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53)
 - `CAP_NET_RAW`: use raw and packet sockets (needed for handling DHCPv6 requests, and verifying that an IP is not in use before leasing it)

examples/docker-compose-caddy-proxy.yml

@@ -19,19 +19,12 @@ services:
       - caddy_data:/data # Use docker volumes here bc no need to access these files from host
       - caddy_config:/config # Use docker volumes here bc no need to access these files from host
 
-
   # More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
   pihole:
     depends_on:
       - caddy
     container_name: pihole
-    #dns:  # Optional. Specify desired upstream DNS servers here.
-    #  - 127.0.0.1
-    #  - 9.9.9.9
-    #  - 149.112.112.112
     image: pihole/pihole:latest
-    networks:
-      - caddy-net  # Need to plug into caddy net to access proxy
     ports:
       - "8081:80/tcp" # Pi-hole web admin interface, proxied through Caddy (configure port in Caddyfile)
       # Following are NOT proxied through Caddy, bound to host net instead:
@@ -41,14 +34,22 @@ services:
       #- "67:67/udp" # DHCP, if desired. If not bound to host net you need an mDNS proxy service configured somewhere on host net.
         # ref: https://docs.pi-hole.net/docker/DHCP/
     environment:
-      TZ: 'America/New_York' # Supported TZ database names: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#Time_Zone_abbreviations
+      # Set the appropriate timezone for your location (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), e.g:
-      FTLCONF_webserver_api_password: 'password'
+      TZ: 'Europe/London'
+      # Set a password to access the web interface. Not setting one will result in a random password being assigned
+      FTLCONF_webserver_api_password: 'correct horse battery staple'
+      # Configure DNS upstream servers, e.g:
+      FTLCONF_dns_upstreams: '8.8.8.8, 8.8.4.4'
+    # Volumes store your data between container upgrades
     volumes:
+      # For persisting Pi-hole's databases and common configuration file
       - './etc-pihole:/etc/pihole'
-      - './etc-dnsmasq.d:/etc/dnsmasq.d'
+      # Uncomment the below if you have custom dnsmasq config files that you want to persist. Not needed for most.
-    #cap_add:  # Uncomment if using Pi-hole as DHCP server
+      #- './etc-dnsmasq.d:/etc/dnsmasq.d'    
-      # https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
+    cap_add:
-      #- NET_ADMIN # ONLY required if you are using Pi-hole as your DHCP server, else remove for better security
+      # See https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
+      # Required if you are using Pi-hole as your DHCP server, else not needed
+      - NET_ADMIN
     restart: unless-stopped
 
 # ref: https://hub.docker.com/_/caddy

src/bash_functions.sh

@@ -1,9 +1,5 @@
 #!/bin/bash
 
-# If user has set QUERY_LOGGING Env Var, copy it out to _OVERRIDE,
-# else it will get overridden itself when we source basic-install.sh
-[ -n "${QUERY_LOGGING}" ] && export QUERY_LOGGING_OVERRIDE="${QUERY_LOGGING}"
-
 # Some of the bash_functions use utilities from Pi-hole's utils.sh
 # shellcheck disable=SC2154
 # shellcheck source=/dev/null
@@ -34,13 +30,17 @@ setFTLConfigValue() {
 
 # shellcheck disable=SC2034
 ensure_basic_configuration() {
+    # Force a check of pihole-FTL --config, this will read any environment variables and set them in the config file
+    # suppress the output as we don't need to see the default values.
+    getFTLConfigValue >/dev/null
+
+    echo ""
     echo "  [i] Ensuring basic configuration by re-running select functions from basic-install.sh"
 
     mkdir -p /var/run/pihole /var/log/pihole
     touch /var/log/pihole/FTL.log /var/log/pihole/pihole.log
     chown -R pihole:pihole /var/run/pihole /var/log/pihole
 
-
     if [[ -z "${PYTEST}" ]]; then
         if [[ ! -f /etc/pihole/adlists.list ]]; then
             echo "https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts" >/etc/pihole/adlists.list
@@ -49,6 +49,11 @@ ensure_basic_configuration() {
 
     chown -R pihole:pihole /etc/pihole
 
+    # Install the logrotate config file - this is done already in Dockerfile
+    # but if a user has mounted a volume over /etc/pihole, it will have been lost
+    # pihole-FTL-prestart.sh will set the ownership of the file to root:root
+    install -Dm644 -t /etc/pihole /etc/.pihole/advanced/Templates/logrotate
+
     # If FTLCONF_files_macvendor is not set
     if [[ -z "${FTLCONF_files_macvendor:-}" ]]; then
         # User is not passing in a custom location - so force FTL to use the file we moved to / during the build
@@ -56,43 +61,38 @@ ensure_basic_configuration() {
         chown pihole:pihole /macvendor.db
     fi
 
-    # Install the logrotate config file - this is done already in Dockerfile
+    # If getFTLConfigValue "dns.upstreams" returns [], exit the container. We need upstream servers to function!
-    # but if a user has mounted a volume over /etc/pihole, it will have been lost
+    if [[ $(getFTLConfigValue "dns.upstreams") == "[]" ]]; then
-    # pihole-FTL-prestart.sh will set the ownership of the file to root:root
+        echo ""
-    install -Dm644 -t /etc/pihole /etc/.pihole/advanced/Templates/logrotate
+        echo "  [X] No DNS upstream servers are set!"
-}
+        echo "  [i] Recommended: Set the upstream DNS servers in the environment variable FTLCONF_dns_upstream"
-
+        echo ""
-setup_web_password() {
+        exit 1
-    echo "  [i] Checking web password"
-    # If the web password variable is not set...
-    if [ -z "${FTLCONF_webserver_api_password+x}" ]; then
-        # is the variable FTLCONF_ENV_ONLY set to true?
-        if [ "${FTLCONF_ENV_ONLY}" == "true" ]; then
-            echo "  [i] No password supplied via FTLCONF_webserver_api_password, but FTLCONF_ENV_ONLY is set to true, using default (none)"
-            # If so, return - the password will be set to FTL's default (no password)
-            return
     fi
 
-        # Exit if password is already set in config file
+    # If FTLCONF_webserver_api_password is not set
+    if [ -z "${FTLCONF_webserver_api_password+x}" ]; then
+        # Is this already set to something other than blank (default) in FTL's config file? (maybe in a volume mount)
         if [[ $(pihole-FTL --config webserver.api.pwhash) = \$BALLOON-SHA256* ]]; then
             echo "  [i] Password already set in config file"
             return
-        fi
+        else
-
+            # If we are here, the password is set in neither the environment nor the config file
-        # If we have got here, we will now generate a random passwor
+            # We will generate a random password.
             RANDOMPASSWORD=$(tr -dc _A-Z-a-z-0-9 </dev/urandom | head -c 8)
             echo "  [i] No password set in environment or config file, assigning random password: $RANDOMPASSWORD"
 
             # Explicitly turn off bash printing when working with secrets
             { set +x; } 2>/dev/null
 
-        pihole setpassword "$RANDOMPASSWORD"
+            pihole-FTL --config webserver.api.password "$RANDOMPASSWORD" >/dev/null
 
             # To avoid printing this if conditional in bash debug, turn off  debug above..
             # then re-enable debug if necessary (more code but cleaner printed output)
             if [ "${PH_VERBOSE:-0}" -gt 0 ]; then
                 set -x
             fi
+        fi
     else
         echo "  [i] Assigning password defined by Environment Variable"
     fi

src/start.sh

@@ -14,13 +14,7 @@ start() {
 
   echo "  [i] Starting docker specific checks & setup for docker pihole/pihole"
 
-  # TODO:
+  # ===========================
-  #if [ ! -f /.piholeFirstBoot ] ; then
-  #    echo "   [i] Not first container startup so not running docker's setup, re-create container to run setup again"
-  #else
-  #    regular_setup_functions
-  #fi
-
   # Initial checks
   # ===========================
 
@@ -47,9 +41,6 @@ start() {
   fi
 
   ensure_basic_configuration
-  setup_web_password
-
-  # [ -f /.piholeFirstBoot ] && rm /.piholeFirstBoot
 
   # Install additional packages inside the container if requested
   if [ -n "${ADDITIONAL_PACKAGES}" ]; then