- Single docker compose file to spin up a Caddy and a Pi-hole container
- I put plenty of comments in compose file for user ref. Looks kinda
messy but I figured the more info the better and they can cull out
what they dont need.
- DHCP server is disabled by default in Pi-hole so I disabled the port
binding and NET_ADMIN capability by default as well, with brief
instructions and refs included.
- Caddy docker compose example ref: https://hub.docker.com/_/caddy
- Pi-hole Caddy config ref: https://docs.pi-hole.net/guides/webserver/caddy/
Signed-off-by: William Trelawny <william@trelawny.family>
Simplify the test suite now that we use buildx to build the final image
Remove tests that were never run/skipped in previous runs (same number of tests passing as were before)
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
- Moves most code in start.sh into functions in bash_functions.sh
- Removes code from 20-start.sh and moves it inside start.sh
- Removes unused variables and code, making it easier to find our way around
- Removes dependency on webpage.sh, which had to be modified in order to source it properly (thus breaking pihole checkout), use utils.sh instead
- Replaces all uses of ServerIP/v6 with new FTLCONF_REPLY_ADDR4/6 variables
- No need to symlink echo to whiptail any more (probably hasn't been needed for a while)
- removes huge list of exported env vars at the top of start.sh - no longer appear to be needed
- rename some functions in bash_functions to more logical names, group their usages in start.sh
- adjust/fix tests to match changes
- remove some dead tests
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
- Update urllib3 from v1.25.9 to v1.26.5
- Update requests from v2.22.0 to v2.28.1
There's a medium severity CVE in urllib3, before v1.26.5, but we can't
only just update urllib3 because there will be a dependency conflict.
requests also needs to be updated.
CVE reference:
https://www.cve.org/CVERecord?id=CVE-2021-33503
> An issue was discovered in urllib3 before 1.26.5. When provided with a
> URL containing many @ characters in the authority component, the
> authority regular expression exhibits catastrophic backtracking,
> causing a denial of service if a URL were passed as a parameter or
> redirected to via an HTTP redirect.
Signed-off-by: Peter Dave Hello <hsu@peterdavehello.org>
https://www.cve.org/CVERecord?id=CVE-2020-26137
> urllib3 before 1.25.9 allows CRLF injection if the attacker controls
> the HTTP request method, as demonstrated by inserting CR and LF
> control characters in the first argument of putrequest(). NOTE: this
> is similar to CVE-2020-26116.
Signed-off-by: Peter Dave Hello <hsu@peterdavehello.org>
Privileged containers do not list each cap by name,
instead they lead with =eip and selectively remove
caps with cap_foo_bar-eip.
Instead we can use the --has-p flag of capsh to check
for the permitted cap.
Signed-off-by: Kyle Harding <kyle@balena.io>
Additionally, move the logic from start() into the end of restart(), and have start() call restart, ensures multiple calls of start cannot start multple processes
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
Update fix_capabilities to only apply net_admin and sys_nice if they are actually available to the container
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
If the process does not exist, the error message of `kill` command is a
little bit confusing:
`kill: usage: kill [-s sigspec | -n signum | -sigspec] pid | jobspec ... or kill -l [sigspec]`
Using `killall` in `/s6/debian-root/etc/services.d/pihole-FTL/finish` to
kill the process, like what we do in `cron/finish` & `lighttpd/finish`,
will make the usage in this project more consistent, and also, the
command `killall` will provide better & friendly output, like:
`pihole-FTL: no process found`
Close#986, cc #973
Signed-off-by: Peter Dave Hello <hsu@peterdavehello.org>
* Trailing slashes on volumes fail on newer versions of docker-compose
See [Issue 947](https://github.com/pi-hole/docker-pi-hole/issues/947)
for the background.
This PR proposes removing trailing slashes from all documentation,
examples and scripts.
Signed-off-by: Phill Kelley <pmk.57t49@lgosys.com>
- reorder some stuff in the main Dockerfile
- Remove the CORE/WEB/FTL_VERSION args/env vars
- tweaks to GHA build script after some hints from @crazy-max
- always checkout dev versions of Pi-hole for nightly build, also make sure we're using dev branch of this repo
- keep pihole checkout enabled for dev and nightly tags
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
use dev images for the dev branch build.
Only disable pihole checkout on released tags - allow it in dev and nightly tags
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
The example seems to no longer be using jwilder/nginx-proxy but the very similar nginxproxy/nginx-proxy. Additionally the link to the example was broken.
* Use the namespace from secrets so others can build too.
* Add DOCKERHUB_NAMESPACE variable.
* Use hub namepace in all actions.
Signed-off-by: Dan Schaper <dan.schaper@pi-hole.net>
Migrate build and push step to native github actions using docker buildX - which should _hopefully_ resolve#735
Make some adjustments to Dockerfile/build.yml/install.sh to allow both gh-actions-test.sh to build using the test suite, and github actions native commands to build online
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
This is closer to mimicking the installation of Pi-hole on bare metal, and also shaves about 40MB off of the size of a container not using custom branches.
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
Since piholeFTL test properly spins down it's no longer
necessary to kill it. He's dead Jim
Merge #300, added `piholeFTL test` to the startup sequence to
replace dnsmasq as a dependency for validate_env and gravity.sh.
kill -9 was kept as a work around to a standing issue that
`piholeFTL test` didn't spin down on it's own. This was fixed
in pi-hole/FTL#1067, landed on Apr 14 2021 and confirmed
working, as evinced by #834 which was filed the same day it
that fix landed.
Signed-off-by: D.Rect <48034372+DistractionRectangle@users.noreply.github.com>
piholeFTL exposes configuration to relocate/rename gravityDB so
we cannot just check a hard coded location. This commit greps
pihole-FTL.conf for a custom location. Since pihole-FTL.conf
will eventually be replaced by TOML, some verbosity is added to
denote what config file is being checked and what location it
ultimately ended up checking.
Signed-off-by: D.Rect <48034372+DistractionRectangle@users.noreply.github.com>
First git clone the repos, next checkout the relevant branches and finally run the install script. Simples.
`sed`ed out a couple of other unsupported functions
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
Proposed solution to #834
I believe the correct way to solve this issue is to change when "Gravity on Boot" is run.
The s6 init system has different stages. Currently, "gravity on boot" is run during Stage 2.ii: cont-init.d. One instance of pihole-FTL is started during cont-init, but it is only there to check the validity of the config files; it exits soon after starting. The final "service mode" instance of pihole-FTL is not started until Stage 2.iii, when the supervisor starts doing work.
If gravity.sh is counting on FTL to do its DNS lookups, then we should not run gravity until the supervised instance of FTL is running. We can accomplish this by moving "Gravity on Boot" to a @reboot line in /etc/cron.d/gravity-on-boot, and making that file's existence dependent on the value of SKIPGRAVITYONBOOT.
This will work because cron isn't started until we've reached Stage 2.iii.
Signed-off-by: Matt Winter <MattWinter@gmail.com>
When setting the password, explicitly disable bash logging. Leave the
re-enable code so that other functions work as expected. Additionally,
do not remove the print in generate_password so randomly generated
passwords are still logged for user consistency.
Signed-off-by: Kyle Kurz <kyle@doublekaudio.com>
From the docs:
> If a repository has any files in its own .github/ISSUE_TEMPLATE folder, including issue templates or a config.yml file, none of the contents of the default .github/ISSUE_TEMPLATE folder will be used.
So we need to copy the config.yml since it will be ignored.
The distro_check function includes updating the APT cache, checking for dependencies, which is both not required on Docker start where all required packages are installed already. The only required steps from this function is the webserver user and config file names, which can be applied directly instead since we know that the Pi-hole Docker container is based on Debian.
Furthermore this solves the issue that updating the APT cache fails, when Pi-hole itself is used for DNS resolution, since pihole-FTL has not yet been started at this stage. That failure was not visible since "apt-get update" does not exist with error code (currently) when facing DNS resolving issues, even if not a single list could have been updated, and no other step is done that would require DNS resolving, until pihole-FTL is started. For a regular (non-Docker) install or update it is however reasonable to error out directly when the APT cache could not have been updated, to not defer the exit unnecessarily to a harder-to-debug stage.
Signed-off-by: MichaIng <micha@dietpi.com>
To be consistent with the parameter already defined in docker_run.sh
(leaving the jwilder-proxy example to pihole.yourDomain.lan to be
consistent with the rest of that file's content, namely DEFAULT_HOST)
If not set, keep existing values in setupVars
if no existing values in setupVars - fall back to defaults
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
* Added new docker tag variations to specify the debian version ('stretch', and 'buster').
* Arch images are alway as specific as possible: pihole/pihole:master-amd64-stretch
* Multiarch images have both the specific debian version tags as well as the generic non-debian tags: pihole/pihole:master-stretch & pihole/pihole:master
* Currently, the non-specific tags point to the 'stretch' images. Eventaully it can be migrated to 'buster'.
* Use GitHub actions to do the builds. Although the script names include 'gh-actions' to differentiate them from the 'circle' scripts, there is zero logic that is specific to Github (ie. no Github environment variables).
* 'armhf:buster' & 'arm64:buster' has an issue with `ip route get`. I think the issue is related to 'qemu', but I'm not sure. Update the `validate_env` function to only use `ip route get` if `nc` reports something strange.
Signed-off-by: Daniel <daniel@developerdan.com>
* Simplify docker builds by consolidating all arch's into a single Dockerfile and using ARGS for various differences
* Introduce docker-compose based builds (build.yml) for simple management of the various args differences
Signed-off-by: Daniel <daniel@developerdan.com>
The trailing backslash must be the last character on the line for it to
be interpreted as a continuation command.
Signed-off-by: Fazlul Shahriar <fshahriar@gmail.com>
* Refactored the prepare_configs function in bash_functions.sh
* Now able to set settings via the UI or ENV Variables - ENV Variables override when restarted
* Added ENV Variables for ADMIN_EMAIL, TEMPERATUREUNIT, and WEBUIBOXEDLAYOUT
- Created setup_temp_unit function in bash_functions.sh
- Created setup_ui_layout function in bash_functions.sh
- Created setup_admin_email function in bash_functions.sh
* Updated README.md
- Added docs on new ENV Variables
- Updated True/False settings docs so they were quoted, otherwise misleading to k8s users and not "true" booleans
Signed-off-by: Andrew J. Huffman <ahuffman@vmware.com>
Latest CI error is a build script failure not a real build/test failure. Its trying to push an image with this branch name as the docker tag but the image was built with v5 branch tag. merging shouldn't hurt
If 'WEBPASSWORD' is set, 'WEBPASSWORD_FILE' is ignored. If 'WEBPASSWORD' is empty, and 'WEBPASSWORD_FILE' is set to a valid readable file, then 'WEBPASSWORD' will be set to the contents of 'WEBPASSWORD_FILE'.
Signed-off-by: Daniel <daniel@developerdan.com>
By default, dig will retry 2 times (for a total of 3 attempts) to get a response back. Each attempt defaults to 5 seconds. Before this change, a single docker healtcheck failure would really mean three failures and would take a total of 15 seconds before failing. By default, docker healthchecks will retry 3 times before considering a service unhealhy (with a 30 second interval). Combined with dig retries, this means it would take a total of 9 failed DNS responses before it considers the pihole to be unhealthy. Combining the retry between dig and docker, dig considers it a success if even 1/3 responses are recieved - and docker considers it a success if only 1/3 of those successes are successful. I'm not great at math - and order does make a difference - but I think that means as long as 1/9th of DNS queries are being answered - then docker thinks its healthy. Anyways, long story sort, dig doesn't need to have its own retry logic since docker already has a configuarable retry. I also disable recurse since the goal is to test this specific instance.
Also removed duplicate import statement.
Signed-off-by: Daniel <daniel@developerdan.com>
- Tox py3.7 + pipenv
- Python3 Dockerfile.py
- Dockerfile.py tags remote instead of just local image names now
- Circle.sh instead of in-line circle.yml script breakout
- probably other stuff I forgot
- Docker images build during the tests should hopefullly now be available at the deploy job workflow thanks to shared docker layers.
- Rename aarch64 to arm64 to reduce custom map
This new optional env variable will allow control over the 'Never
forward non-FQDNs' advanced DNS setting.
Signed-off-by: Jeff Billimek <jeff@billimek.com>
Currently `docker_run.sh` bind-mounts some directories rooted at the
working directory when the script is invoked. Add an environment variable
so that this storage location can be specified at invocation time without
having to change to a different directory.
Also creates PIHOLE_BASE if it doesn't exist already.
Shallow clone pihole and webinterface repos to target branch.
Only install curl and procps dependencies, as well as
ca-certificates for curl'ing against https
Cuts image size down by ~30MB (304MB -> 274MB)
Signed-off-by: DistractionRectangle <48034372+DistractionRectangle@users.noreply.github.com>
Clarify that people running --net=host should set ServerIP for Pi-hole to function correctly.
I'll have to try to add some automation around this later to try to warn only the network host mode users if they miss it.
Signed-off-by: Martin Buchleitner <mabunixda@gmail.com>
- Add a new container environment variable allowing to specify the user to run the pihole-FTL process as. Defaults to root.
- Set inherited capabilities attributes on the pihole-FTL file to automatically grant runtime permitted capabilities when available in the bounding set. This allows dropping root before starting pihole-FTL without failing with a permission error if the capabilities are not available to the container (the process may still error out if performing an operation requiring the capability).
- Add some information on capabilities to the Readme file.
Signed-off-by: Mathieu Hofman <86499+mhofman@users.noreply.github.com>
Signed-off-by: Martin Buchleitner <mabunixda@gmail.com>
Clarify that people running --net=host should set ServerIP for Pi-hole to function correctly.
I'll have to try to add some automation around this later to try to warn only the network host mode users if they miss it.
- Add a new container environment variable allowing to specify the user to run the pihole-FTL process as. Defaults to root.
- Set inherited capabilities attributes on the pihole-FTL file to automatically grant runtime permitted capabilities when available in the bounding set. This allows dropping root before starting pihole-FTL without failing with a permission error if the capabilities are not available to the container (the process may still error out if performing an operation requiring the capability).
- Add some information on capabilities to the Readme file.
Signed-off-by: Mathieu Hofman <86499+mhofman@users.noreply.github.com>
* split out arg fixture to improve grainularity of test overriding
* README points out new arguments that improve likelihood of success
Signed-off-by: Adam Hill <adam@diginc.us>
* Removed some old switch statements from alpine no longer required
* Limit parallel tests to 2 to help prevent test failure caused by race condition starting parallel tests/containers
* Began introducing a new ENV NO_SETUP to skip the majority of startup script 'setup' functions eventually
Signed-off-by: Adam Hill <adam@diginc.us>
<!-- Provide a general summary of the issue in the Title above -->
<!-- Note: these are comments that don't show up in the actual issue, no need to delete them as you fill out the template -->
<!-- IMPORTANT Complete the entire template please, the info gathered here is usually needed to debug issues anyway so it saves time in the long run. Incomplete/stock template issues may be closed -->
<!-- pick ONE: Bug,
Feature Request,
Run Issue (running Pi-hole container failing),
Build Issue (Building image failing)
Enter in line below: -->
This is a: **FILL ME IN**
## Details
<!-- Provide a more detailed introduction to the issue or feature, try not to duplicate info from lower sections by reviewing the entire template first -->
## Related Issues
- [ ] I have searched this repository/Pi-hole forums for existing issues and pull requests that look similar
<!-- Add links below! -->
<!------- FEATURE REQUESTS CAN STOP FILLING IN TEMPLATE HERE -------->
<!------- ISSUES SHOULD FILL OUT REMAINDER OF TEMPLATE -------->
stale-issue-message:'This issue is stale because it has been open 30 days with no activity. Please comment or update this issue or it will be closed in 5 days.'
stale-issue-label:'stale'
exempt-issue-labels:'pinned, Fixed in next release, bug, never-stale, documentation, investigating'
Notes about releases will be documented on [docker-pi-hole's github releases page](https://github.com/pi-hole/docker-pi-hole/releases). Breaking changes will be copied to the top of the docker repo's README file to assist with common upgrade issues.
See the [Pi-hole releases](https://github.com/pi-hole/pi-hole/releases) for details on updates unrelated to docker image releases
@@ -6,5 +6,5 @@ Please review the following before opening a pull request (PR) to help your PR g
* To ensure proper testing and quality control, target any code change pull requests against `dev` branch.
* Make sure the tests pass
* Take a look at [TESTING.md](TESTING.md) to see how to run tests locally so you do not have to push all your code to a PR and have travis-ci run it.
* Take a look at [TESTING.md](test/TESTING.md) to see how to run tests locally so you do not have to push all your code to a PR and have GitHub Actions run it.
* Your tests will probably run faster locally and you get a faster feedback loop.
**Debian is now the only supported base OS for `diginc/pi-hole`** to improve consistency and updates. Alpine OS was dropped and ARM has moved to a new image/tag name. The ARM Debian tag was removed from `diginc/pi-hole` but is still supported at its new image repository home, [diginc/pi-hole-multiarch](https://hub.docker.com/r/diginc/pi-hole-multiarch/tags/) where it has both an `:debian_armhf` and `:debian_aarch64` version
<!-- Delete above HTML and insert markdown for dockerhub :  -->
## Upgrade Notes
- **Using Watchtower? See the [Note on Watchtower](#note-on-watchtower) at the bottom of this readme**
- Due to [a known issue with Docker and libseccomp <2.5](https://github.com/moby/moby/issues/40734), you may run into issues running `2022.04` and later on host systems with an older version of `libseccomp2` ([Such as Debian/Raspbian buster or Ubuntu 20.04](https://pkgs.org/download/libseccomp2), and maybe [CentOS 7](https://pkgs.org/download/libseccomp)).
The first recommendation is to upgrade your host OS, which will include a more up to date (and fixed) version of `libseccomp`.
_If you absolutely cannot do this, some users [have reported](https://github.com/pi-hole/docker-pi-hole/issues/1042#issuecomment-1086728157) success in updating `libseccomp2` via backports on debian, or similar via updates on Ubuntu. You can try this workaround at your own risk_ (Note, you may also find that you need the latest `docker.io` (more details [here](https://blog.samcater.com/fix-workaround-rpi4-docker-libseccomp2-docker-20/))
- Some users [have reported issues](https://github.com/pi-hole/docker-pi-hole/issues/963#issuecomment-1095602502) with using the `--privileged` flag on `2022.04` and above. TL;DR, don't use that mode, and be [explicit with the permitted caps](https://github.com/pi-hole/docker-pi-hole#note-on-capabilities) (if needed) instead
- As of `2022.04.01`, setting `CAP_NET_ADMIN` is only required if you are using Pi-hole as your DHCP server. The container will only try to set caps that are explicitly granted (or natively available)
- In `2022.01` and later, the default `DNSMASQ_USER` has been changed to `pihole`, however this may cause issues on some systems such as Synology, see Issue [#963](https://github.com/pi-hole/docker-pi-hole/issues/963) for more information.
If the container won't start due to issues setting capabilities, set `DNSMASQ_USER` to `root` in your environment.
## Quick Start
1. Copy docker-compose.yml.example to docker-compose.yml and update as needed. See example below:
- NET_ADMIN# Required if you are using Pi-hole as your DHCP server, else not needed
restart:unless-stopped
```
2. Run `docker compose -f docker-compose.yml up -d` to build and start pi-hole
3. Use the Pi-hole web UI to change the DNS settings *Interface listening behavior* to "Listen on all interfaces, permit all origins", if using Docker's default `bridge` network setting. (This can also be achieved by setting the environment variable `DNSMASQ_LISTENING` to `all`)
[Here is an equivalent docker run script](https://github.com/pi-hole/docker-pi-hole/blob/master/examples/docker_run.sh).
## Overview
A [Docker](https://www.docker.com/what-docker) project to make a lightweight x86 ~~and ARM~~ container with [pi-hole](https://pi-hole.net) functionality.
A [Docker](https://www.docker.com/what-docker) project to make a lightweight x86 and ARM container with [Pi-hole](https://pi-hole.net) functionality.
1) Install docker for your [x86-64 system](https://www.docker.com/community-edition) or [ARMv6l/ARMv7 system](https://www.raspberrypi.org/blog/docker-comes-to-raspberry-pi/) using those links.
2) Use the appropriate tag (x86 can use default tag, ARM users need to use images from `diginc/pi-hole-multiarch:debian_armhf`) in the below `docker run` command
1) Install docker for your [x86-64 system](https://www.docker.com/community-edition) or [ARMv7 system](https://www.raspberrypi.org/blog/docker-comes-to-raspberry-pi/) using those links. [Docker-compose](https://docs.docker.com/compose/install/) is also recommended.
2) Use the above quick start example, customize if desired.
[](https://gitter.im/diginc/docker-pi-hole?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
## Running Pi-hole Docker
## Running Pi-Hole Docker
This container uses 2 popular ports, port 53 and port 80, so **may conflict with existing applications ports**. If you have no other services or docker containers using port 53/80 (if you do, keep reading below for a reverse proxy example), the minimum arguments required to run this container are in the script [docker_run.sh](https://github.com/pi-hole/docker-pi-hole/blob/master/examples/docker_run.sh)
[DockerCloud](https://store.docker.com/community/images/diginc/pi-hole) automatically builds the latest docker-pi-hole changes into images which can easily be pulled and ran with a simple `docker run` command. Changes and updates under development or testing can be found in the [dev tags](#development) section.
One crucial thing to know before starting is this container needs port 53 and port 80, two very popular ports that may conflict with existing applications. If you have no other services or dockers using port 53/80 (if you do, keep reading below for a reverse proxy example), the minimum arguments required to run this container are in the script [docker_run.sh](https://github.com/diginc/docker-pi-hole/blob/master/docker_run.sh) or summarized here:
If you're using a Red Hat based distribution with an SELinux Enforcing policy add `:z` to line with volumes like so:
```
IP_LOOKUP="$(ip route get 8.8.8.8 | awk '{ print $NF; exit }')" # May not work for VPN / tun0
IPv6_LOOKUP="$(ip -6 route get 2001:4860:4860::8888 | awk '{ print $10; exit }')" # May not work for VPN / tun0
IP="${IP:-$IP_LOOKUP}" # use $IP, if set, otherwise IP_LOOKUP
IPv6="${IPv6:-$IPv6_LOOKUP}" # use $IPv6, if set, otherwise IP_LOOKUP
DOCKER_CONFIGS="$(pwd)" # Default of directory you run this from, update to where ever.
**This is just an example and might need changing.** Volumes are stored in the directory `$DOCKER_CONFIGS` and aren't required but are recommended for persisting data across docker re-creations for updating images. As mentioned on line 2, the auto `IP_LOOKUP` variable may not work for VPN tunnel interfaces.
Volumes are recommended for persisting data across container re-creations for updating images. The IP lookup variables may not work for everyone, please review their values and hard code IP and IPv6 if necessary.
You can customize where to store persistent data by setting the `PIHOLE_BASE` environment variable when invoking `docker_run.sh` (e.g. `PIHOLE_BASE=/opt/pihole-storage ./docker_run.sh`). If `PIHOLE_BASE` is not set, files are stored in your current directory when you invoke the script.
**Automatic Ad List Updates** - since the 3.0+ release, `cron` is baked into the container and will grab the newest versions of your lists and flush your logs. **Set your TZ** environment variable to make sure the midnight log rotation syncs up with your timezone's midnight.
## Running DHCP from Docker Pi-Hole
There are multiple different ways to run DHCP from within your Docker Pi-hole container but it is slightly more advanced and one size does not fit all. DHCP and Docker's multiple network modes are covered in detail on our docs site: [Docker DHCP and Network Modes](https://docs.pi-hole.net/docker/DHCP/)
## Environment Variables
There are other environment variables if you want to customize various things inside the docker container:
| Docker Environment Var. | Description |
| ----------------------- | ----------- |
| `-e ServerIP=<Host's IP>`<br/>**Required** | Set to your server's external IP to block ads fully
| `-e ServerIPv6=<Host's IPv6>`<br/>*Required if using IPv6* | **If you have a v6 network** set to your server's external IPv6 to block IPv6 ads fully
| `-e TZ=<Timezone>`<br/>**Recommended***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.
| `-e WEBPASSWORD=<Admin password>`<br/>**Recommended***Default: random* | http://pi.hole/admin password. Run `docker logs pihole \| grep random` to find your random pass.
| `-e DNS1=<IP>`<br/>*Optional**Default: 8.8.8.8* | Primary upstream DNS provider, default is google DNS
| `-e DNS2=<IP>`<br/>*Optional**Default: 8.8.4.4* | Secondary upstream DNS provider, default is google DNS
| `-e VIRTUAL_HOST=<Custom Hostname>`<br/>*Optional**Default: $ServerIP* | What your web server 'virtual host' is, accessing admin through this Hostname/IP allows you to make changes to the whitelist / blacklists in addition to the default 'http://pi.hole/admin/' address
| `-e IPv6=<True\|False>`<br/>*Optional**Default: True* | For unraid compatibility, strips out all the IPv6 configuration from DNS/Web services when false.
| `-e INTERFACE=<NIC>`<br/>*Advanced/Optional* | The default works fine with our basic example docker run commands. If you're trying to use DHCP with `--net host` mode then you may have to customize this or DNSMASQ_LISTENING.
| `-e DNSMASQ_LISTENING=<local\|all\|NIC>`<br/>*Advanced/Optional* | `local` listens on all local subnets, `all` permits listening on internet origin subnets in addition to local.
| `-e WEB_PORT=<PORT>`<br/>*Advanced/Optional* | **This will break the 'webpage blocked' functionality of pi-hole** however it may help advanced setups like those running synology or `--net=host` docker argument. This guide explains how to restore webpage blocked functionality using a linux router DNAT rule: [Alternagtive Synology installation method](https://discourse.pi-hole.net/t/alternative-synology-installation-method/5454?u=diginc)
### Recommended Variables
Here is a rundown of the other arguments passed into the example `docker run`:
| Variable | Default | Value | Description |
| -------- | ------- | ----- | ---------- |
| `TZ` | UTC | `<Timezone>` | 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.
| `WEBPASSWORD` | random | `<Admin password>` | http://pi.hole/admin password. Run `docker logs pihole \| grep random` to find your random pass.
| `FTLCONF_LOCAL_IPV4` | unset | `<Host's IP>` | Set to your server's LAN IP, used by web block modes and lighttpd bind address.
### Optional Variables
| Variable | Default | Value | Description |
| -------- | ------- | ----- | ---------- |
| `PIHOLE_DNS_` | `8.8.8.8;8.8.4.4` | IPs delimited by `;` | Upstream DNS server(s) for Pi-hole to forward queries to, separated by a semicolon <br/> (supports non-standard ports with `#[port number]`) e.g `127.0.0.1#5053;8.8.8.8;8.8.4.4`<br/> (supports [Docker service names and links](https://docs.docker.com/compose/networking/) instead of IPs) e.g `upstream0;upstream1` where `upstream0` and `upstream1` are the service names of or links to docker services <br/> Note: The existence of this environment variable assumes this as the _sole_ management of upstream DNS. Upstream DNS added via the web interface will be overwritten on container restart/recreation |
| `DNS_BOGUS_PRIV` | `true` |`<"true"\|"false">`| Never forward reverse lookups for private ranges |
| `DNS_FQDN_REQUIRED` | `true` | `<"true"\|"false">`| Never forward non-FQDNs |
| `REV_SERVER` | `false` | `<"true"\|"false">` | Enable DNS conditional forwarding for device name resolution |
| `REV_SERVER_DOMAIN` | unset | Network Domain | If conditional forwarding is enabled, set the domain of the local network router |
| `REV_SERVER_TARGET` | unset | Router's IP | If conditional forwarding is enabled, set the IP of the local network router |
| `REV_SERVER_CIDR` | unset | Reverse DNS | If conditional forwarding is enabled, set the reverse DNS zone (e.g. `192.168.0.0/24`) |
| `DHCP_ACTIVE` | `false` | `<"true"\|"false">` | Enable DHCP server. Static DHCP leases can be configured with a custom `/etc/dnsmasq.d/04-pihole-static-dhcp.conf`
| `DHCP_START` | unset | `<Start IP>` | Start of the range of IP addresses to hand out by the DHCP server (mandatory if DHCP server is enabled).
| `DHCP_END` | unset | `<End IP>` | End of the range of IP addresses to hand out by the DHCP server (mandatory if DHCP server is enabled).
| `DHCP_ROUTER` | unset | `<Router's IP>` | Router (gateway) IP address sent by the DHCP server (mandatory if DHCP server is enabled).
| `DHCP_LEASETIME` | 24 | `<hours>` | DHCP lease time in hours.
| `PIHOLE_DOMAIN` | `lan` | `<domain>` | Domain name sent by the DHCP server.
| `DHCP_IPv6` | `false` | `<"true"\|"false">` | Enable DHCP server IPv6 support (SLAAC + RA).
| `VIRTUAL_HOST` | `$FTLCONF_LOCAL_IPV4` | `<Custom Hostname>` | What your web server 'virtual host' is, accessing admin through this Hostname/IP allows you to make changes to the whitelist / blacklists in addition to the default 'http://pi.hole/admin/' address
| `IPv6` | `true` | `<"true"\|"false">` | For unraid compatibility, strips out all the IPv6 configuration from DNS/Web services when false.
| `TEMPERATUREUNIT` | `c` | `<c\|k\|f>` | Set preferred temperature unit to `c`: Celsius, `k`: Kelvin, or `f` Fahrenheit units.
| `WEBUIBOXEDLAYOUT` | `boxed` | `<boxed\|traditional>` | Use boxed layout (helpful when working on large screens)
| `WEBTHEME` | `default-light` | `<"default-dark"\|"default-darker"\|"default-light"\|"default-auto"\|"lcars">`| User interface theme to use.
| `WEBPASSWORD_FILE`| unset | `<Docker secret path>` |Set an Admin password using [Docker secrets](https://docs.docker.com/engine/swarm/secrets/). If `WEBPASSWORD` is set, `WEBPASSWORD_FILE` is ignored. If `WEBPASSWORD` is empty, and `WEBPASSWORD_FILE` is set to a valid readable file path, then `WEBPASSWORD` will be set to the contents of `WEBPASSWORD_FILE`.
### Advanced Variables
| Variable | Default | Value | Description |
| -------- | ------- | ----- | ---------- |
| `INTERFACE` | unset | `<NIC>` | The default works fine with our basic example docker run commands. If you're trying to use DHCP with `--net host` mode then you may have to customize this or DNSMASQ_LISTENING.
| `DNSMASQ_LISTENING` | unset | `<local\|all\|single>` | `local` listens on all local subnets, `all` permits listening on internet origin subnets in addition to local, `single` listens only on the interface specified.
| `WEB_PORT` | unset | `<PORT>` | **This will break the 'webpage blocked' functionality of Pi-hole** however it may help advanced setups like those running synology or `--net=host` docker argument. This guide explains how to restore webpage blocked functionality using a linux router DNAT rule: [Alternative Synology installation method](https://discourse.pi-hole.net/t/alternative-synology-installation-method/5454?u=diginc)
| `SKIPGRAVITYONBOOT` | unset | `<unset\|1>` | Use this option to skip updating the Gravity Database when booting up the container. By default this environment variable is not set so the Gravity Database will be updated when the container starts up. Setting this environment variable to 1 (or anything) will cause the Gravity Database to not be updated when container starts up.
| `CORS_HOSTS` | unset | `<FQDNs delimited by ,>` | List of domains/subdomains on which CORS is allowed. Wildcards are not supported. Eg: `CORS_HOSTS: domain.com,home.domain.com,www.domain.com`.
| `CUSTOM_CACHE_SIZE` | `10000` | Number | Set the cache size for dnsmasq. Useful for increasing the default cache size or to set it to 0. Note that when `DNSSEC` is "true", then this setting is ignored.
| `FTL_CMD` | `no-daemon` | `no-daemon -- <dnsmasq option>` | 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. |
| `FTLCONF_[SETTING]` | unset | As per documentation | Customize pihole-FTL.conf with settings described in the [FTLDNS Configuration page](https://docs.pi-hole.net/ftldns/configfile/). For example, to customize LOCAL_IPV4, ensure you have the `FTLCONF_LOCAL_IPV4` environment variable set.
### Experimental Variables
| Variable | Default | Value | Description |
| -------- | ------- | ----- | ---------- |
| `DNSMASQ_USER` | unset | `<pihole\|root>` | Allows changing the user that FTLDNS runs as. Default: `pihole`|
| `PIHOLE_UID` | `999` | Number | Overrides image's default pihole user id to match a host user id<br/>**IMPORTANT**: id must not already be in use inside the container! |
| `PIHOLE_GID` | `999` | Number | Overrides image's default pihole group id to match a host group id<br/>**IMPORTANT**: id must not already be in use inside the container!|
| `WEB_UID` | `33` | Number | Overrides image's default www-data user id to match a host user id<br/>**IMPORTANT**: id must not already be in use inside the container! (Make sure it is different to `PIHOLE_UID` if you are using that, also)|
| `WEB_GID` | `33` | Number | Overrides image's default www-data group id to match a host group id<br/>**IMPORTANT**: id must not already be in use inside the container! (Make sure it is different to `PIHOLE_GID` if you are using that, also)|
| `WEBLOGS_STDOUT` | 0 | 0|1 | 0 logs to defined files, 1 redirect access and error logs to stdout |
## Deprecated environment variables:
While these may still work, they are likely to be removed in a future version. Where applicable, alternative variable names are indicated. Please review the table above for usage of the alternative variables
| Docker Environment Var. | Description | Replaced By |
| `CONDITIONAL_FORWARDING` | Enable DNS conditional forwarding for device name resolution | `REV_SERVER`|
| `CONDITIONAL_FORWARDING_IP` | If conditional forwarding is enabled, set the IP of the local network router | `REV_SERVER_TARGET` |
| `CONDITIONAL_FORWARDING_DOMAIN` | If conditional forwarding is enabled, set the domain of the local network router | `REV_SERVER_DOMAIN` |
| `CONDITIONAL_FORWARDING_REVERSE` | If conditional forwarding is enabled, set the reverse DNS of the local network router (e.g. `0.168.192.in-addr.arpa`) | `REV_SERVER_CIDR` |
| `DNS1` | Primary upstream DNS provider, default is google DNS | `PIHOLE_DNS_` |
| `DNS2` | Secondary upstream DNS provider, default is google DNS, `no` if only one DNS should used | `PIHOLE_DNS_` |
| `ServerIP` | Set to your server's LAN IP, used by web block modes and lighttpd bind address | `FTLCONF_REPLY_ADDR4` |
| `ServerIPv6` | **If you have a v6 network** set to your server's LAN IPv6 to block IPv6 ads fully | `FTLCONF_REPLY_ADDR6` |
| `FTLCONF_REPLY_ADDR4` | Set to your server's LAN IP, used by web block modes and lighttpd bind address | `FTLCONF_LOCAL_IPV4` |
| `FTLCONF_REPLY_ADDR6` | **If you have a v6 network** set to your server's LAN IPv6 to block IPv6 ads fully | `FTLCONF_LOCAL_IPV6` |
To use these env vars in docker run format style them like: `-e DNS1=1.1.1.1`
Here is a rundown of other arguments for your docker-compose / docker run.
| Docker Arguments | Description |
| ---------------- | ----------- |
| `-p 80:80`<br/>`-p 53:53/tcp -p 53:53/udp`<br/>**Recommended** | Ports to expose, the bare minimum ports required for pi-holes HTTP and DNS services
| `--restart=unless-stopped`<br/>**Recommended** | Automatically (re)start your pihole on boot or in the event of a crash
| `-v /dir/for/pihole:/etc/pihole`<br/>**Recommended** | Volumes for your pihole configs help persist changes across docker image updates
| `-v /dir/for/dnsmasq.d:/etc/dnsmasq.d`<br/>**Recommended** | Volumes for your dnsmasq 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
| `--cap-add=NET_ADMIN`<br/>*Optional* | If you want to attempt DHCP (not fully tested or supported) I'd suggest this with --net=host
If you're a fan of [docker-compose](https://docs.docker.com/compose/install/) I have [example docker-compose.yml files](https://github.com/diginc/docker-pi-hole/blob/master/doco-example.yml) in github which I think are a nicer way to represent such long run commands.
| `-p <port>:<port>`**Recommended** | Ports to expose (53, 80, 67), the bare minimum ports required for Pi-holes HTTP and DNS services
| `--restart=unless-stopped`<br/>**Recommended** | Automatically (re)start your Pi-hole on boot or in the event of a crash
| `-v $(pwd)/etc-pihole:/etc/pihole`<br/>**Recommended** | Volumes for your Pi-hole configs help persist changes across docker image updates
| `-v $(pwd)/etc-dnsmasq.d:/etc/dnsmasq.d`<br/>**Recommended** | Volumes for your dnsmasq 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=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
* A good way to test things are working right is by loading this page: [http://pi.hole/admin/](http://pi.hole/admin/)
* [How do I set or reset the Web interface Password?](https://discourse.pi-hole.net/t/how-do-i-set-or-reset-the-web-interface-password/1328)
*`docker exec pihole_container_name pihole -a -p supersecurepassword`
*`docker exec -it pihole_container_name pihole -a -p` - then enter yourpassword into the prompt
* Port conflicts? Stop your server's existing DNS / Web services.
* Ubuntu users especially may need to shut off dns on your docker server so it can run in the container on port 53
* 17.04 and later should disable dnsmasq.
* 17.10 should disable systemd-resolved service. See this page: [How to disable systemd-resolved in Ubuntu](https://askubuntu.com/questions/907246/how-to-disable-systemd-resolved-in-ubuntu)
* Don't forget to stop your services from auto-starting again after you reboot
*Port 80 is highly recommended because if you have another site/service using port 80 by default then the ads may not transform into blank ads correctly. To make sure docker-pi-hole plays nicely with an existing webserver you run you'll probably need a reverse proxy webserver config if you don't have one already. Pi-Hole must be the default web app on the proxy e.g. if you go to your host by IP instead of domain then pi-hole is served out instead of any other sites hosted by the proxy. This is the '[default_server](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen)' in nginx or ['_default_' virtual host](https://httpd.apache.org/docs/2.4/vhosts/examples.html#default) in Apache and is taken advantage of so any undefined ad domain can be directed to your webserver and get a 'blocked' response instead of ads.
* You can still map other ports to pi-hole port 80 using docker's port forwarding like this `-p 8080:80`, but again the ads won't render properly. Changing the inner port 80 shouldn't be required unless you run docker host networking mode.
* [Here is an example of running with jwilder/proxy](https://github.com/diginc/docker-pi-hole/blob/master/jwilder-proxy-example-doco.yml) (an nginx auto-configuring docker reverse proxy for docker) on my port 80 with pihole on another port. Pi-hole needs to be `DEFAULT_HOST` env in jwilder/proxy and you need to set the matching `VIRTUAL_HOST` for the pihole's container. Please read jwilder/proxy readme for more info if you have trouble. I tested this basic example which is based off what I run.
*Ubuntu users see below for more detailed information
* You can map other ports to Pi-hole port 80 using docker's port forwarding like this `-p 8080:80` if you are using the default blocking mode. If you are using the legacy IP blocking mode, you should not remap this port.
* [Here is an example of running with nginxproxy/nginx-proxy](https://github.com/pi-hole/docker-pi-hole/blob/master/examples/docker-compose-nginx-proxy.yml) (an nginx auto-configuring docker reverse proxy for docker) on my port 80 with Pi-hole on another port. Pi-hole needs to be `DEFAULT_HOST` env in nginxproxy/nginx-proxy and you need to set the matching `VIRTUAL_HOST` for the Pi-hole's container. Please read nginxproxy/nginx-proxy readme for more info if you have trouble.
* Docker's default network mode `bridge` isolates the container from the host's network. This is a more secure setting, but requires setting the Pi-hole DNS option for *Interface listening behavior* to "Listen on all interfaces, permit all origins".
### Installing on Ubuntu or Fedora
Modern releases of Ubuntu (17.10+) and Fedora (33+) include [`systemd-resolved`](http://manpages.ubuntu.com/manpages/bionic/man8/systemd-resolved.service.8.html) which is configured by default to implement a caching DNS stub resolver. This will prevent pi-hole from listening on port 53.
The stub resolver should be disabled with: `sudo sed -r -i.orig 's/#?DNSStubListener=yes/DNSStubListener=no/g' /etc/systemd/resolved.conf`
This will not change the nameserver settings, which point to the stub resolver thus preventing DNS resolution. Change the `/etc/resolv.conf` symlink to point to `/run/systemd/resolve/resolv.conf`, which is automatically updated to follow the system's [`netplan`](https://netplan.io/):
`sudo sh -c 'rm /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf'`
After making these changes, you should restart systemd-resolved using `systemctl restart systemd-resolved`
Once pi-hole is installed, you'll want to configure your clients to use it ([see here](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245)). If you used the symlink above, your docker host will either use whatever is served by DHCP, or whatever static setting you've configured. If you want to explicitly set your docker host's nameservers you can edit the netplan(s) found at `/etc/netplan`, then run `sudo netplan apply`.
Example netplan:
```yaml
network:
ethernets:
ens160:
dhcp4:true
dhcp4-overrides:
use-dns:false
nameservers:
addresses:[127.0.0.1]
version:2
```
Note that it is also possible to disable `systemd-resolved` entirely. However, this can cause problems with name resolution in vpns ([see bug report](https://bugs.launchpad.net/network-manager/+bug/1624317)). It also disables the functionality of netplan since systemd-resolved is used as the default renderer ([see `man netplan`](http://manpages.ubuntu.com/manpages/bionic/man5/netplan.5.html#description)). If you choose to disable the service, you will need to manually set the nameservers, for example by creating a new `/etc/resolv.conf`.
Users of older Ubuntu releases (circa 17.04) will need to disable dnsmasq.
## Installing on Dokku
@Rikj000 has produced a guide to assist users [installing Pi-hole on Dokku](https://github.com/Rikj000/Pihole-Dokku-Installation)
## Docker tags and versioning
The primary docker tags / versions are explained in the following table. [Click here to see the full list of tags](https://store.docker.com/community/images/diginc/pi-hole/tags), I also try to tag with the specific version of Pi-Hole Core for version pinning purposes, the web version that comes with the core releases should be in the [GitHub Release notes](https://github.com/diginc/docker-pi-hole/releases).
The primary docker tags are explained in the following table. [Click here to see the full list of tags](https://store.docker.com/community/images/pihole/pihole/tags). See [GitHub Release notes](https://github.com/pi-hole/docker-pi-hole/releases) to see the specific version of Pi-hole Core, Web, and FTL included in the release.
| tag | architecture | description | Dockerfile |
| --- | ------------ | ----------- | ----------|
| `debian` / `latest`| x86 | Debian x86 image, container running lighttpd and dnsmasq | [Dockerfile](https://github.com/diginc/docker-pi-hole/blob/master/debian.docker) |
### `diginc/pi-hole:debian` [](https://microbadger.com/images/diginc/pi-hole "Get your own image badge on microbadger.com") [](https://microbadger.com/images/diginc/pi-hole "Get your own version badge on microbadger.com") [](https://microbadger.com/images/diginc/pi-hole "Get your own version badge on microbadger.com")
This version of the docker aims to be as close to a standard pi-hole installation by using the recommended base OS and the exact configs and scripts (minimally modified to get them working). This enables fast updating when an update comes from pi-hole.
### `diginc/pi-hole-multiarch:debian_armhf` [](https://microbadger.com/images/diginc/pi-hole-multiarch "Get your own image badge on microbadger.com")
### `diginc/pi-hole-multiarch:debian_aarch64` [](https://microbadger.com/images/diginc/pi-hole-multiarch "Get your own image badge on microbadger.com")
| `2022.04` | Date-based release that can receive bugfix updates |
| `2022.04.1` | A specific image that will not receive updates |
| `dev` | Similar to `latest`, but for the development branch (pushed occasionally) |
| `*beta` | Early beta releases of upcoming versions - here be dragons |
| `nightly` | Like `dev` but pushed every night and pulls from the latest `development` branches of the core Pi-hole components (Pi-hole, AdminLTE, FTL) |
## Upgrading, Persistence, and Customizations
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. Volumes are also important to persist the configuration in case you have removed the pi-hole container which is a typical docker upgrade pattern.
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.
### Upgrading
### Upgrading / Reconfiguring
`pihole -up` is disabled. Upgrade the docker way instead, please. Long-living docker containers are not the docker way.
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.
1.Download the latest version of the image: `docker pull diginc/pi-hole`
0.Read the release notes for both this Docker release and the Pi-hole release
* This will help you avoid common problems due to any known issues with upgrading or newly required arguments or variables
* 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 inturruption **OR** always have a fallback DNS server configured in DHCP to avoid this problem altogether.
* 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> diginc/pi-hole` (`<args>` being your preferred run volumes and env vars)
* **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.
* 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)
Why is this style of upgrading good? A couple reasons: Everyone is starting from the same base image which has been tested to know it works. No worrying about upgrading from A to B, B to C, or A to C is required when rolling out updates, it reducing complexity, and simply allows a 'fresh start' every time while preserving customizations with volumes. Basically I'm encouraging [phoenix servers](https://www.google.com/?q=phoenix+servers) principles for your containers.
Why is this style of upgrading good? A couple reasons: Everyone is starting from the same base image which has been tested to known it works. No worrying about upgrading from A to B, B to C, or A to C is required when rolling out updates, it reduces complexity, and simply allows a 'fresh start' every time while preserving customizations with volumes. Basically I'm encouraging [phoenix server](https://www.google.com/?q=phoenix+servers) principles for your containers.
To reconfigure Pi-hole you'll either need to use an existing container environment variables or if there is no a variable for what you need, use the web UI or CLI commands.
### Pihole features
### Pi-hole features
Here are some relevant wiki pages from [pi-hole's documentation](https://github.com/pi-hole/pi-hole/blob/master/README.md#get-help-or-connect-with-us-on-the-web). The web interface or command line tools can be used to implement changes to pihole.
Here are some relevant wiki pages from [Pi-hole's documentation](https://github.com/pi-hole/pi-hole/blob/master/README.md#get-help-or-connect-with-us-on-the-web). The web interface or command line tools can be used to implement changes to pihole.
We install all pihole utilities so the the built in [pihole commands](https://discourse.pi-hole.net/t/the-pihole-command-with-examples/738) will work via `docker exec <container> <command>` like so:
@@ -138,24 +270,41 @@ 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 or if you need to modify the pi-hole config it is located at `/etc/dnsmasq.d/01-pihole.conf`. The docker start scripts runs a config test prior to starting so it will tell you about any errors in the docker log.
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 or if you need to modify the Pi-hole config it is located at `/etc/dnsmasq.d/01-pihole.conf`. The docker start scripts runs a config test prior to starting so it will tell you about any errors in the docker log.
Similarly for the webserver you can customize configs in /etc/lighttpd (*:debian* tag).
Similarly for the webserver you can customize configs in /etc/lighttpd
### Systemd init script
As long as your docker system service auto starts on boot and you run your container with `--restart=unless-stopped` your container should always start on boot and restart on crashes. If you prefer to have your docker container run as a systemd service instead, add the file [pihole.service](https://raw.githubusercontent.com/diginc/docker-pi-hole/master/pihole.service) to "/etc/systemd/system"; customize whatever your container name is and remove `--restart=unless-stopped` from your docker run. Then after you have initially created the docker container using the docker run command above, you can control it with "systemctl start pihole" or "systemctl stop pihole" (instead of `docker start`/`docker stop`). You can also enable it to auto-start on boot with "systemctl enable pihole" (as opposed to `--restart=unless-stopped` and making sure docker service auto-starts on boot).
As long as your docker system service auto starts on boot and you run your container with `--restart=unless-stopped` your container should always start on boot and restart on crashes. If you prefer to have your docker container run as a systemd service instead, add the file [pihole.service](https://raw.githubusercontent.com/pi-hole/docker-pi-hole/master/examples/pihole.service) to "/etc/systemd/system"; customize whatever your container name is and remove `--restart=unless-stopped` from your docker run. Then after you have initially created the docker container using the docker run command above, you can control it with "systemctl start pihole" or "systemctl stop pihole" (instead of `docker start`/`docker stop`). You can also enable it to auto-start on boot with "systemctl enable pihole" (as opposed to `--restart=unless-stopped` and making sure docker service auto-starts on boot).
NOTE: After initial run you may need to manually stop the docker container with "docker stop pihole" before the systemctl can start controlling the container.
## Development
## Note on Capabilities
[](https://travis-ci.org/diginc/docker-pi-hole) If you plan on making a contribution please pull request to the dev branch. I also build tags of the dev branch for bug fix testing after merges have been made:
DNSMasq / [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`
| tag | architecture | description | Dockerfile |
| --- | ------------ | ----------- | ---------- |
| `debian_dev` | x86 | Debian x86 image, container running lighttpd and dnsmasq | [Dockerfile](https://github.com/diginc/docker-pi-hole/blob/dev/debian.docker) |
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.
## Note on Watchtower
We have noticed that a lot of people use Watchtower to keep their Pi-hole containers up to date. For the same reason we don't provide an auto-update feature on a bare metal install, you _should not_ have a system automatically update your Pi-hole container. Especially unattended. As much as we try to ensure nothing will go wrong, sometimes things do go wrong - and you need to set aside time to _manually_ pull and update to the version of the container you wish to run. The upgrade process should be along the lines of:
- **Important**: Read the release notes. Sometimes you will need to make changes other than just updating the image
- Pull the new image
- Stop and _remove_ the running Pi-hole container
- If you care about your data (logs/customizations), make sure you have it volume-mapped or it will be deleted in this step.
- Recreate the container using the new image
Pi-hole is an integral part of your network, don't let it fall over because of an unattended update in the middle of the night.
# User Feedback
Please report issues on the [GitHub project](https://github.com/diginc/docker-pi-hole) when you suspect something docker related. Pi-Hole questions are best answered on their [user forums](https://github.com/pi-hole/pi-hole/blob/master/README.md#get-help-or-connect-with-us-on-the-web). Ping me (@diginc) on there if it's a docker and you're not sure if it's docker related.
Please report issues on the [GitHub project](https://github.com/pi-hole/docker-pi-hole) when you suspect something docker related. Pi-hole or general docker questions are best answered on our [user forums](https://discourse.pi-hole.net/c/bugs-problems-issues/docker/30).
Make sure you have docker, python, and pip. I won't cover how to install those here, please search the internet for that info if you need it.
# Running tests locally
Travis-ci auto runs tests during pull requests (PR) but it only has 2 cores and if you have more/faster cpus your PC's local tests will be faster and you'll have quicker feedback loops than continually pushing to have your PR run travis-ci
After you have the prereqs, to get the required pip packages run: `pip install -r requirements.txt`
To run the Dockerfile templating, image build, and tests all in one command just run: `tox`
# Local image names
Docker images built by `tox` or `python Dockerfile.py` are named the same but stripped of the `diginc/` docker repository namespace.
e.g. `pi-hole:debian_amd64` or `pi-hole-multiarch:debian_aarch64`
You can run the multiarch images on an amd64 development system if you [enable binfmt-support as described in the multiarch image docs](https://hub.docker.com/r/multiarch/multiarch/debian-debootstrap/)
`docker run --rm --privileged multiarch/qemu-user-static:register --reset`
echo"ERROR: To function correctly you must pass an environment variables of 'ServerIP' into the docker container with the IP of your docker host from which you are passing web (80) and dns (53) ports from"
exit1
fi;
# Required ServerIP is a valid IP
# nc won't throw any text based errors when it times out connecting to a valid IP, otherwise it complains about the DNS name being garbage
# if nc doesn't behave as we expect on a valid IP the routing table should be able to look it up and return a 0 retcode
if[["$(nc -4 -w1 -z "$ServerIP"53 2>&1)" !=""]]|| ! ip route get "$ServerIP" > /dev/null ;then
echo"ERROR: ServerIP Environment variable ($ServerIP) doesn't appear to be a valid IPv4 address"
exit1
fi
# Optional IPv6 is a valid address
if[[ -n "$ServerIPv6"]];then
if[["$ServerIPv6"=='kernel']];then
echo"ERROR: You passed in IPv6 with a value of 'kernel', this maybe beacuse you do not have IPv6 enabled on your network"
unset ServerIPv6
exit1
fi
if[["$(nc -6 -w1 -z "$ServerIPv6"53 2>&1)" !=""]]|| ! ip route get "$ServerIPv6" > /dev/null ;then
echo"ERROR: ServerIPv6 Environment variable ($ServerIPv6) doesn't appear to be a valid IPv6 address"
echo" TIP: If your server is not IPv6 enabled just remove '-e ServerIPv6' from your docker container"
echo" SKIPGRAVITYONBOOT is set, however ${gravityDBfile} does not exist (Likely due to a fresh volume). This is a required file for Pi-hole to operate."
echo" Ignoring SKIPGRAVITYONBOOT on this occaision."
fi
pihole -g
else
echo" Skipping Gravity Database Update."
fi
# Run update checker to check for newer container, and display version output
# Legacy Env Vars preserved for backwards compatibility - convert them to FTLCONF_ equivalents
[ -n "${ServerIP}"]&&echo"ServerIP is deprecated. Converting to FTLCONF_LOCAL_IPV4"&&export"FTLCONF_LOCAL_IPV4"="$ServerIP"
[ -n "${ServerIPv6}"]&&echo"ServerIPv6 is deprecated. Converting to FTLCONF_LOCAL_IPV6"&&export"FTLCONF_LOCAL_IPV6"="$ServerIPv6"
# Previously used FTLCONF_ equivalent has since been deprecated, also convert this one
[ -n "${FTLCONF_REPLY_ADDR4}"]&&echo"FTLCONF_REPLY_ADDR4 is deprecated. Converting to FTLCONF_LOCAL_IPV4"&&export"FTLCONF_LOCAL_IPV4"="$FTLCONF_REPLY_ADDR4"
[ -n "${FTLCONF_REPLY_ADDR6}"]&&echo"FTLCONF_REPLY_ADDR6 is deprecated. Converting to FTLCONF_LOCAL_IPV6"&&export"FTLCONF_LOCAL_IPV6"="$FTLCONF_REPLY_ADDR6"
# Some of the bash_functions use utilities from Pi-hole's utils.sh
# FTL can also use CAP_NET_ADMIN and CAP_SYS_NICE. If we try to set them when they haven't been explicitly enabled, FTL will not start. Test for them first:
echo" [i] Setting capabilities on pihole-FTL where possible"
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
