allancoding/pihole-libseccomp2-fix repository overview

⁠Docker Pi-hole

⁠Changes!

⁠Changes from the pihole/pihole:

• ⁠libseccomp2 is fixed

⁠Upgrade Notes

• Using Watchtower? See the Note on Watchtower⁠ at the bottom of this readme

• Due to a known issue with Docker and libseccomp <2.5⁠, 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⁠, and maybe CentOS 7⁠).

  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⁠ 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⁠)

• Some users have reported issues⁠ with using the --privileged flag on 2022.04 and above. TL;DR, don't use that mode, and be explicit with the permitted caps⁠ (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⁠ 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: Docker-compose⁠ example:

version: "3"

# 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
    # For DHCP it is recommended to remove these ports and instead add: network_mode: "host"
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "67:67/udp" # Only required if you are using Pi-hole as your DHCP server
      - "80:80/tcp"
    environment:
      TZ: 'America/Chicago'
      # WEBPASSWORD: 'set a secure password here or it will be random'
    # 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
    cap_add:
      - NET_ADMIN # Required if you are using Pi-hole as your DHCP server, else not needed
    restart: unless-stopped

1. Run docker-compose up -d to build and start pi-hole
2. 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⁠.

⁠Overview

A Docker⁠ project to make a lightweight x86 and ARM container with Pi-hole⁠ functionality.

1. Install docker for your x86-64 system⁠ or ARMv7 system⁠ using those links. Docker-compose⁠ is also recommended.
2. Use the above quick start example, customize if desired.
3. Enjoy!

⁠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⁠

If you're using a Red Hat based distribution with an SELinux Enforcing policy add :z to line with volumes like so:

    -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.

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⁠

⁠Environment Variables

There are other environment variables if you want to customize various things inside the docker container:

⁠Recommended Variables

⁠Optional Variables

⁠Advanced Variables

⁠Experimental Variables

⁠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

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.

⁠Tips and Tricks

• A good way to test things are working right is by loading this page: http://pi.hole/admin/⁠
• How do I set or reset the Web interface Password?⁠
  • docker exec -it pihole_container_name pihole -a -p - then enter your password into the prompt
• Port conflicts? Stop your server's existing DNS / Web services.
  • Don't forget to stop your services from auto-starting again after you reboot
  • 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⁠ (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⁠ 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⁠: 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⁠). 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:

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⁠). It also disables the functionality of netplan since systemd-resolved is used as the default renderer (see man netplan⁠). 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⁠

⁠Docker tags and versioning

The primary docker tags are explained in the following table. Click here to see the full list of tags⁠. See GitHub Release notes⁠ to see the specific version of Pi-hole Core, Web, and FTL included in the release.

⁠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. 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 / Reconfiguring

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. 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
2. Download the latest version of the image: docker pull pihole/pihole
3. Throw away your container: docker rm -f pihole
   • Warning When removing your pihole container you may be stuck without DNS until step 3; docker pull before docker rm -f to avoid DNS interruption OR always have a fallback DNS server configured in DHCP to avoid this problem altogether.
   • If you care about your data (logs/customizations), make sure you have it volume-mapped or it will be deleted in this step.
4. Start your container with the newer base image: `docker run pihole/