-
-
Notifications
You must be signed in to change notification settings - Fork 210
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Flesh out the Docker section, add some more detailed information abou…
…t configuration and upgrading (with dedicated section about upgrading from V5) Signed-off-by: Adam Warner <[email protected]>
- Loading branch information
Showing
5 changed files
with
259 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # Configuration | ||
|
|
||
| The recommended way to configure the Pi-hole docker contianer is by utilising [environment variables](https://docs.docker.com/compose/how-tos/environment-variables/), however if you are persisting your `/etc/pihole` directory, you choose instead to set them via the web interface, or by directly editing `pihole.toml` | ||
|
|
||
| ## Environment Variables | ||
|
|
||
| ### Recommended Variables | ||
|
|
||
| #### `TZ` (Default: `UTC`) | ||
|
|
||
| Set your [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to make sure logs rotate at local midnight instead of at UTC midnight. | ||
|
|
||
| #### `FTLCONF_webserver_api_password` (Default: `unset`) | ||
|
|
||
| To set a specific password for the web interface, use the environment variable `FTLCONF_webserver_api_password` (per the quickstart example). If this variable is not detected, and you have not already set one previously inside the container via `pihole setpassword` or `pihole-FTL --config webserver.api.password`, then a random password will be assigned on startup, and will be printed to the log. You can find this password with the command `docker logs pihole | grep random password` on your host to find this password. | ||
|
|
||
| #### `FTLCONF_dns_upstreams` (Default: `8.8.8.8;8.8.4.4`) | ||
|
|
||
| - Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon | ||
| - Supports non-standard ports with #[port number] e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4` | ||
| - Supports Docker service names and links instead of IPs e.g `upstream0;upstream1` where upstream0 and upstream1 are the service names of or links to docker services | ||
|
|
||
| ### Optional Variables | ||
|
|
||
| #### `FTLCONF_[SETTING]` | ||
|
|
||
| Set various `pihole.toml` settings via environment variable for persistence. Follows the syntax as setting a value on the CLI, e.g `pihole-FTL --config key.setting=value`. Replace `.` with `_` in the setting name, and prepend with `FTLCONF_` | ||
|
|
||
| For example, setting `FTLCONF_dns_dnssec: 'true'` is the functional equivalent of running `pihole-FTL --config dns.dnssec=true`, or setting the following in the toml file | ||
|
|
||
| ```toml | ||
| [dns] | ||
| dnssec = true | ||
| ``` | ||
|
|
||
| !!! info | ||
| FTL settings that are set via environment variables effectively become read-only, meaning that you will not be able to change them via the web interface or CLI. This is to ensure a "single source of truth" on the config. If you later unset or remove an environment variable, then FTL will revert to the default value for that setting | ||
|
|
||
| #### `TAIL_FTL_LOG` (Default: `1`) | ||
|
|
||
| Whether or not to output the FTL log when running the container. Can be disabled by setting the value to 0 | ||
|
|
||
| #### `PIHOLE_UID` (Default: `100`) | ||
|
|
||
| Overrides image's default pihole user id to match a host user id | ||
|
|
||
| #### `PIHOLE_GID` (Default: `100`) | ||
|
|
||
| Overrides image's default pihole group id to match a host group id | ||
|
|
||
| !!! Warning | ||
| For the above two settings, the `id` must not already be in use inside the container! | ||
|
|
||
| ### Advanced Variables | ||
|
|
||
| #### `FTL_CMD` (Default: `no-daemon`) | ||
|
|
||
| Customize the options with which dnsmasq gets started. e.g. `no-daemon -- --dns-forward-max 300` to increase max. number of concurrent dns queries on high load setups. | ||
|
|
||
| #### `DNSMASQ_USER` (Default: `pihole`) | ||
|
|
||
| Allows changing the user that FTLDNS runs as. Default: pihole, some systems such as Synology NAS may require you to change this to root (See [pihole/docker-pi-hole#963](https://github.com/pi-hole/docker-pi-hole/issues/963)) | ||
|
|
||
| #### `ADDITIONAL_PACKAGES` (Default: unset) | ||
|
|
||
| Mostly for development purposes, this just makes it easier for those of us that always like to have whatever additional tools we need inside the container for debugging. | ||
|
|
||
| Adding packages here is the same as running `apk add <package>` inside the container | ||
|
|
||
| #### `PH_VERBOSE` (Default: `0`) | ||
|
|
||
| Setting this environment variable to `1` will set `-x`, making the scripts that run on container startup more verbose. Useful for debugging only. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| The easiset way to get up and running with Pi-hole on Docker is to use our quickstart `docker-compose.yml` template. | ||
|
|
||
| Copy the below [Docker Compose](https://docs.docker.com/compose/) example and customise as needed | ||
|
|
||
| ```yaml | ||
| # More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/ | ||
| services: | ||
| pihole: | ||
| container_name: pihole | ||
| image: pihole/pihole:latest | ||
| ports: | ||
| # DNS Ports | ||
| - "53:53/tcp" | ||
| - "53:53/udp" | ||
| # Default HTTP Port | ||
| - "80:80/tcp" | ||
| # 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: | ||
| # Set the appropriate timezone for your location from | ||
| # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, e.g: | ||
| 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' | ||
| # If using Docker's default `bridge` network setting the dns listening mode should be set to 'all'3 | ||
| FTLCONF_dns_listeningMode: 'all' | ||
| # Volumes store your data between container upgrades | ||
| volumes: | ||
| # For persisting Pi-hole's databases and common configuration file | ||
| - './etc-pihole:/etc/pihole' | ||
| # For persisting custom dnsmasq config files. Most will not need this, and can be safely removed/commented out | ||
| - './etc-dnsmasq.d:/etc/dnsmasq.d' | ||
| cap_add: | ||
| # Required if you are using Pi-hole as your DHCP server, else not needed | ||
| # See Note On Capabilities below | ||
| - NET_ADMIN | ||
| restart: unless-stopped | ||
| ``` | ||
| Run `docker compose up -d` to build and start Pi-hole (on older systems, the syntax here may be `docker-compose up -d`) | ||
|
|
||
| The equivalent command for `docker run` would be: | ||
|
|
||
| ``` | ||
| docker run --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -p 443:443/tcp -e TZ=Europe/London -e FTLCONF_webserver_api_password="correct horse battery staple" -e FTLCONF_dns_listeningMode=all -v ./etc-pihole:/etc/pihole -v ./etc-dnsmasq.d:/etc/dnsmasq.d --cap-add NET_ADMIN --restart unless-stopped pihole/pihole:latest | ||
| ``` | ||
|
|
||
| ## Note On Capabilities | ||
|
|
||
| [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) | ||
| - `CAP_NET_ADMIN`: modify routing tables and other network-related operations (in particular inserting an entry in the neighbor table to answer DHCP requests using unicast packets) | ||
| - `CAP_SYS_NICE`: FTL sets itself as an important process to get some more processing time if the latter is running low | ||
| - `CAP_CHOWN`: we need to be able to change ownership of log files and databases in case FTL is started as a different user than `pihole` | ||
| - `CAP_SYS_TIME`: FTL needs to be able to set the system time to update it using the Network Time Protocol (NTP) in the background | ||
|
|
||
| !!! info | ||
| This image automatically grants those capabilities, if available, to the FTLDNS process, even when run as non-root. | ||
|
|
||
| By default, docker does not include the `NET_ADMIN` capability for non-privileged containers, and it is recommended to explicitly add it to the container using `--cap-add=NET_ADMIN`. | ||
|
|
||
| However, if DHCP and IPv6 Router Advertisements are not in use, it should be safe to skip it. For the most paranoid, it should even be possible to explicitly drop the `NET_RAW` capability to prevent FTLDNS from automatically gaining it. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| # Upgrading | ||
|
|
||
| The standard Pi-hole customization abilities apply to this docker, but with docker twists such as using docker volume mounts to map host stored file configurations over the container defaults. However, mounting these configuration files as read-only should be avoided. Volumes are also important to persist the configuration in case you have removed the Pi-hole container which is a typical docker upgrade pattern. | ||
|
|
||
| !!! tip "Always Read The Release Notes!" | ||
| Ensure you read the release notes for both the Docker Release and the main Pi-hole component releases. This will help you avoid common problems due to known issues with upgrading or newly required arguments or varables | ||
|
|
||
| ## Upgrading / Reconfiguring | ||
|
|
||
| !!! Warning | ||
| Do not attempt to upgrade (`pihole -up`) or reconfigure (`pihole -r`). New images will be released for upgrades, upgrading by replacing your old container with a fresh upgraded image is the 'docker way'. Long-living docker containers are not the docker way since they aim to be portable and reproducible, why not re-create them often! Just to prove you can. | ||
|
|
||
| ### Docker Compose | ||
|
|
||
| Navigate to the directory in which your `docker-compose.yml` file exists and run the following commands | ||
|
|
||
| ```bash | ||
| docker compose down | ||
| docker compose pull | ||
| docker compose up -d | ||
| ``` | ||
|
|
||
| ### Docker run | ||
|
|
||
| ```bash | ||
| docker stop pihole | ||
| docker rm pihole | ||
| docker pull pihole/pihole:latest | ||
| docker run [ ... arguments (see Getting Started) ... ] | ||
| ``` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| !!! info | ||
| The last image of the Pi-hole docker container which contained v5.x Pi-hole components was [`2024.07.0`](https://github.com/pi-hole/docker-pi-hole/releases/tag/2024.07.0) | ||
| <br><br> | ||
| Versions after this will be based on v6.x Pi-hole components. | ||
|
|
||
| ## Changed Environment Variables | ||
|
|
||
| Nearly all environment variables from previous versions have been removed, but functionality can be replicated by setting their `FTLCONF_` equivalent instead. (See [Configuration](../configuration.md#ftlconf_setting) page for more details) | ||
|
|
||
| ### Misc | ||
|
|
||
| | Old Variable | New Variable | | ||
| |:-------------|:-------------| | ||
| |`CUSTOM_CACHE_SIZE`|`FTLCONF_dns_cache_size`| | ||
| |`DNS_BOGUS_PRIV`|`FTLCONF_dns_bogusPriv`| | ||
| |`DNS_FQDN_REQUIRED`|`FTLCONF_dns_domainNeeded`| | ||
| |`DNSMASQ_LISTENING`|`FTLCONF_dns_listeningMode`| | ||
| |`DNSSEC`|`FTLCONF_dns_dnssec`| | ||
| |`INTERFACE`|`FTLCONF_dns_interface`| | ||
| |`PIHOLE_DNS_`|`FTLCONF_dns_upstreams`| | ||
| |`QUERY_LOGGING`|`FTLCONF_dns_queryLogging`| | ||
| |`WEBPASSWORD`|`FTLCONF_webserver_api_password`| | ||
| |`WEB_PORT`|`FTLCONF_webserver_port`| | ||
| |`WEBTHEME`|`FTLCONF_webserver_interface_theme`| | ||
| |`WEBUIBOXEDLAYOUT`|`FTLCONF_webserver_interface_boxed`| | ||
|
|
||
| ### DHCP Variables | ||
|
|
||
| |Old|New| | ||
| |:--|:--| | ||
| |`DHCP_ACTIVE`| `FTLCONF_dhcp_active`| | ||
| |`DHCP_START`| `FTLCONF_dhcp_start`| | ||
| |`DHCP_END`| `FTLCONF_dhcp_end`| | ||
| |`DHCP_ROUTER`| `FTLCONF_dhcp_router`| | ||
| |`DHCP_LEASETIME`| `FTLCONF_dhcp_leaseTime`| | ||
| |`PIHOLE_DOMAIN`| `FTLCONF_dns_domain`| | ||
| |`DHCP_IPv6`| `FTLCONF_dhcp_ipv6`| | ||
| |`DHCP_rapid_commit`| `FTLCONF_dhcp_rapidCommit`| | ||
|
|
||
| ### Conditional Forwarding Variables | ||
|
|
||
| Reverse server (`REV_SERVER*`) variables should be replaced with the single `FTLCONF_dns_revServers`, which accepts an array of reverse servers (delimted by `;`) in the following format: | ||
|
|
||
| ``` | ||
| <enabled>,<ip-address>[/<prefix-len>],<server>[#<port>],<domain> | ||
| ``` | ||
|
|
||
| If, for example, you had the following old style variables: | ||
|
|
||
| - `REV_SERVER: 'true'` | ||
| - `REV_SERVER_DOMAIN: 'lan'` | ||
| - `REV_SERVER_TARGET: '192.168.0.1#53'` | ||
| - `REV_SERVER_CIDR: '192.168.0.0/24'` | ||
|
|
||
| You would now set: | ||
|
|
||
| ``` | ||
| FTLCONF_dns_revServers: 'true,192.168.0.0/24,192.168.0.1#53,lan' | ||
| ``` | ||
|
|
||
| ### Removed Variables | ||
|
|
||
| The following variables can be removed without replacement, as they are no longer used: | ||
|
|
||
| - `CONDITIONAL_FORWARDING` | ||
| - `CONDITIONAL_FORWARDING_DOMAIN` | ||
| - `CONDITIONAL_FORWARDING_IP` | ||
| - `CONDITIONAL_FORWARDING_REVERSE` | ||
| - `CORS_HOSTS` | ||
| - `DNS1` | ||
| - `DNS2` | ||
| - `FTLCONF_REPLY_ADDR4` | ||
| - `FTLCONF_REPLY_ADDR6` | ||
| - `IPV6` | ||
| - `ServerIP` | ||
| - `ServerIPv6` | ||
| - `SKIPGRAVITYONBOOT` | ||
| - `TEMPERATUREUNIT` | ||
| - `VIRTUAL_HOST` | ||
| - `WEB_BIND_ADDR` | ||
| - `WEB_GID` | ||
| - `WEB_UID` | ||
| - `WEBLOGS_STDOUT` | ||
| - `WEBPASSWORD_FILE` | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters