Quick first pass of Readme update. Probably still needs more work. Can happen as we go
Signed-off-by: Adam Warner <me@adamwarner.co.uk>
This commit is contained in:
Adam Warner
parent
429739d060
commit
48970d8bb7
61
README.md
61
README.md
|
|
@ -5,18 +5,16 @@
|
|||
</p>
|
||||
<!-- Delete above HTML and insert markdown for dockerhub :  -->
|
||||
|
||||
|
||||
## Upgrade Notes
|
||||
## !!! THIS VERSION CONTAINS BREAKING CHANGES !!!
|
||||
|
||||
### v[ChangeMeBeforeTagging] has been entirely redesigned from the ground up and contains many breaking changes. Environment variable names have changed, script locations may have changed. Please read the the Readme carefully before proceeding.
|
||||
|
||||
---
|
||||
|
||||
- **Using Watchtower? See the [Note on Watchtower](#note-on-watchtower) at the bottom of this readme**
|
||||
|
||||
- As of `2023.01`, if you have any modifications for lighttpd via an `external.conf` file, this file now needs to be mapped into `/etc/lighttpd/conf-enabled/whateverfile.conf` instead
|
||||
|
||||
- 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
|
||||
|
||||
## Quick Start
|
||||
|
|
@ -44,14 +42,14 @@ services:
|
|||
# Volumes store your data between container upgrades
|
||||
volumes:
|
||||
- './etc-pihole:/etc/pihole'
|
||||
- './etc-dnsmasq.d:/etc/dnsmasq.d'
|
||||
# https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
|
||||
# - './etc-dnsmasq.d:/etc/dnsmasq.d' # Only needed if you have some custom configs for dnsmasq
|
||||
# https://github.com/pi-hole/docker-pi-hole#note-on-capabilities
|
||||
cap_add:
|
||||
- NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
|
||||
restart: unless-stopped
|
||||
```
|
||||
2. Run `docker compose up -d` to build and start pi-hole (Syntax may be `docker-compose` on older systems)
|
||||
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`)
|
||||
3. If using Docker's default `bridge` network setting, set the environment variable `FTLCONF_dns_listeningMode` to `all`
|
||||
|
||||
[Here is an equivalent docker run script](https://github.com/pi-hole/docker-pi-hole/blob/master/examples/docker_run.sh).
|
||||
|
||||
|
|
@ -59,7 +57,7 @@ services:
|
|||
|
||||
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 [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.
|
||||
1) Install Docker. [Docker-compose](https://docs.docker.com/compose/install/) is also recommended.
|
||||
2) Use the above quick start example, customize if desired.
|
||||
3) Enjoy!
|
||||
|
||||
|
|
@ -73,14 +71,11 @@ If you're using a Red Hat based distribution with an SELinux Enforcing policy ad
|
|||
|
||||
```
|
||||
-v "$(pwd)/etc-pihole:/etc/pihole:z" \
|
||||
-v "$(pwd)/etc-dnsmasq.d:/etc/dnsmasq.d:z" \
|
||||
```
|
||||
|
||||
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.
|
||||
Volumes are recommended for persisting data across container re-creations for updating images.
|
||||
|
||||
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.
|
||||
**Automatic Ad List Updates** - `cron` is baked into the container and will grab the newest versions of your lists and flush your logs. This happens once per week in the small hours of Sunday morning.
|
||||
|
||||
## Running DHCP from Docker Pi-Hole
|
||||
|
||||
|
|
@ -95,37 +90,30 @@ There are other environment variables if you want to customize various things in
|
|||
| 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_webserver_api_password` | random | `<Admin password>` | http://pi.hole/admin password. Run `docker logs pihole \| grep random` to find your random pass.
|
||||
| `FTLCONF_dns_upstreams` | `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 |
|
||||
| `FTLCONF_LOCAL_IPV4` | unset | `<Host's IP>` | Set to your server's LAN IP, used by web block modes.
|
||||
|
||||
### Optional Variables
|
||||
|
||||
| Variable | Default | Value | Description |
|
||||
| -------- | ------- | ----- | ---------- |
|
||||
| `VIRTUAL_HOST` | `${HOSTNAME}` | `<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.
|
||||
| `QUERY_LOGGING` | `true` | `<"true"\|"false">` | Enable query logging or not.
|
||||
| `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`.
|
||||
| `TAIL_FTL_LOG` | unset | `<unset\|1>` | Whether or not to output the FTL log when running the. Useful for debugging/watching what FTL is doing.
|
||||
|
||||
### Advanced Variables
|
||||
| Variable | Default | Value | Description |
|
||||
| -------- | ------- | ----- | ---------- |
|
||||
| `WEB_BIND_ADDR` | unset | `<IP>` | Lighttpd's bind address. If left unset lighttpd will bind to every interface, except when running in host networking mode where it will use `FTLCONF_LOCAL_IPV4` instead.
|
||||
| `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`.
|
||||
| `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.
|
||||
| `FTLCONF_[SETTING]` | unset | As per documentation | Customize pihole-FTL.conf with settings described in the <!!!Add Link To New API docs here before release!!!>. Replace `.` with `_`, e.g for `dns.dnssec=true` use `FTLCONF_dns_dnssec: 'true'`
|
||||
| `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!|
|
||||
| `DNSMASQ_USER` | unset | `<pihole\|root>` | 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 [#963](https://github.com/pi-hole/docker-pi-hole/issues/963)) |
|
||||
|
||||
### Experimental Variables
|
||||
| Variable | Default | Value | Description |
|
||||
| -------- | ------- | ----- | ---------- |
|
||||
| `DNSMASQ_USER` | unset | `<pihole\|root>` | 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 [#963](https://github.com/pi-hole/docker-pi-hole/issues/963)) |
|
||||
| `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 |
|
||||
|Left Blank for future expansion| | | |
|
||||
|
||||
|
||||
To use these env vars in docker run format style them like: `-e DNS1=1.1.1.1`
|
||||
|
||||
|
|
@ -136,7 +124,6 @@ Here is a rundown of other arguments for your docker-compose / docker run.
|
|||
| `-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.
|
||||
|
|
@ -234,14 +221,6 @@ We install all pihole utilities so the the built in [pihole commands](https://di
|
|||
|
||||
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
|
||||
|
||||
### 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/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.
|
||||
|
||||
## Note on Capabilities
|
||||
|
||||
DNSMasq / [FTLDNS](https://docs.pi-hole.net/ftldns/in-depth/#linux-capabilities) expects to have the following capabilities available:
|
||||
|
|
|
|||
|
|
@ -2,6 +2,9 @@
|
|||
|
||||
# https://github.com/pi-hole/docker-pi-hole/blob/master/README.md
|
||||
|
||||
# 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.
|
||||
PIHOLE_BASE="${PIHOLE_BASE:-$(pwd)}"
|
||||
[[ -d "$PIHOLE_BASE" ]] || mkdir -p "$PIHOLE_BASE" || { echo "Couldn't create storage directory: $PIHOLE_BASE"; exit 1; }
|
||||
|
||||
|
|
@ -16,9 +19,6 @@ docker run -d \
|
|||
--dns=127.0.0.1 --dns=1.1.1.1 \
|
||||
--restart=unless-stopped \
|
||||
--hostname pi.hole \
|
||||
-e VIRTUAL_HOST="pi.hole" \
|
||||
-e PROXY_LOCATION="pi.hole" \
|
||||
-e FTLCONF_LOCAL_IPV4="127.0.0.1" \
|
||||
pihole/pihole:latest
|
||||
|
||||
printf 'Starting up pihole container '
|
||||
|
|
|
|||
Loading…
Reference in New Issue