woahbase/alpine-pdnsd repository overview

⁠Alpine-PDNSd⁠

⁠Container for Alpine Linux + Proxy DNS Daemon (caching recursive DNS Server)

This image⁠ containerizes the PDNSd⁠ DNS server with persistent caching-to-disk and recursion/forwarding, mainly used to resolve domain names (both local devices and outsiders) and blocking ads inside the local network.

Based on Alpine Linux⁠ from my alpine-s6⁠ image with the s6⁠ init system overlayed⁠ in it.

The image is tagged respectively for the following architectures,

• armhf
• x86_64 (retagged as the latest )

armhf builds have embedded binfmt_misc support and contain the qemu-user-static⁠ binary that allows for running it also inside an x64 environment that has it.

⁠Get the Image

Pull the image for your architecture it's already available from Docker Hub.

# make pull
docker pull woahbase/alpine-pdnsd:x86_64

⁠Run

Before you run..

• Default configuration is at /etc/pdnsd.conf, the default is provided in root/defaults, put your custom config file at /data/pdnsd.conf at it will be copied over at start.

• Local names are served from /data/hosts/hosts.local, if not found, /etc/hosts is copied.

• A default blocklist from the following sources are provided as default at /etc/hosts.blocked. On start, this is copied over to /data/hosts/hosts.blocked, if not existing already. Replace this file to use your own blocking list. Current build combines the following lists ..

  • AdAway's Sources⁠
  • Someonewhocares⁠
  • StevenBlack's List⁠
  • hpHosts⁠

• To unblock a specific domain from the blocklist, put it inside /data/hosts/hosts.whitelisted ( Needs restart ). To manually unblock using sed..

sed -i \
  -e 's/\([ . ]\)rt.com/\1notrt.com/g' \
  /data/hosts/*

• On many systemd derivations e.g. ArchLinux, 53/udp may be already taken by systemd-resolved. In that case, it will need to be stopped first before dns server is started. Run,

sudo systemctl stop systed-resolved

If you want to run images for other architectures, you will need to have binfmt support configured for your machine. multiarch⁠, has made it easy for us containing that into a docker container.

# make regbinfmt
docker run --rm --privileged multiarch/qemu-user-static:register --reset

Without the above, you can still run the image that is made for your architecture, e.g for an x86_64 machine..

Running make starts the service.

# make
docker run --rm -it \
  --name docker_pdnsd --hostname pdnsd \
  -e PGID=1000 -e PUID=1000 \
  -c 256 -m 400m -p 53:53/tcp -p 53:53/udp \
  -v data:/data \
  -v /etc/hosts:/etc/hosts:ro \
  -v /etc/localtime:/etc/localtime:ro \
  woahbase/alpine-pdnsd:x86_64

Stop the container with a timeout, (defaults to 2 seconds)

# make stop
docker stop -t 2 docker_pdnsd

Removes the container, (always better to stop it first and -f only when needed most)

# make rm
docker rm -f docker_pdnsd

Restart the container with

# make restart
docker restart docker_pdnsd

⁠Shell access

Get a shell inside a already running container,

# make shell
docker exec -it docker_pdnsd /bin/bash

set user or login as root,

# make rshell
docker exec -u root -it docker_pdnsd /bin/bash

To check logs of a running container in real time

# make logs
docker logs -f docker_pdnsd

⁠Development

If you have the repository access, you can clone and build the image yourself for your own system, and can push after.

⁠Setup

Before you clone the repo⁠, you must have Git⁠, GNU make⁠, and Docker⁠ setup on the machine.

git clone https://github.com/woahbase/alpine-pdnsd
cd alpine-pdnsd

You can always skip installing make but you will have to type the whole docker commands then instead of using the sweet make targets.

⁠Build

You need to have binfmt_misc configured in your system to be able to build images for other architectures.

Otherwise to locally build the image for your system. [ARCH defaults to x86_64, need to be explicit when building for other architectures.]

# make ARCH=x86_64 build
# sets up binfmt if not x86_64
docker build --rm --compress --force-rm \
  --no-cache=true --pull \
  -f ./Dockerfile_x86_64 \
  --build-arg ARCH=x86_64 \
  --build-arg DOCKERSRC=alpine-s6 \
  --build-arg PGID=1000 \
  --build-arg PUID=1000 \
  --build-arg USERNAME=woahbase \
  -t woahbase/alpine-pdnsd:x86_64 \
  .

To check if its working..

# make ARCH=x86_64 test
docker run --rm -it \
  --name docker_pdnsd --hostname pdnsd \
  -e PGID=1000 -e PUID=1000 \
  --entrypoint pdnsd
  woahbase/alpine-pdnsd:x86_64 \
  '--version'

And finally, if you have push access,

# make ARCH=x86_64 push
docker push woahbase/alpine-pdnsd:x86_64

⁠Maintenance

Sources at Github⁠. Built at Travis-CI.org⁠ (armhf / x64 builds). Images at Docker hub⁠. Metadata at Microbadger⁠.

Maintained by WOAHBase⁠.