ricariel/cn2pihole repository overview

⁠core-networks2pihole-docker

Mirrors the DNS records of a Core Networks⁠ account into a Pi-hole⁠ instance, so that names managed at the provider resolve locally without leaving the network.

The container polls the Core Networks API in a loop, renders the records into the two file formats Pi-hole understands, and drops them into Pi-hole's configuration directories.

⁠How It Works

1. Authenticate against the API with login and password, receive a bearer token.
2. List all DNS zones of the account.
3. For every zone, fetch the A, AAAA and CNAME records.
4. Render them into two files:
   • A and AAAA records become a hosts file at /etc/pihole/cn.list
   • CNAME records become dnsmasq directives at /etc/dnsmasq.d/99-cn-import.conf
5. Sleep for WAIT_INTERVAL seconds, then start over.

On the first run the container also writes /etc/dnsmasq.d/99-a-aaaa-import.conf containing addn-hosts=/etc/pihole/cn.list, which is what makes Pi-hole read the generated hosts file.

Files are written to a .new temporary name first and only moved into place if they are non-empty. If the API is unreachable, the previous state therefore stays active instead of being replaced by an empty file.

⁠Quickstart

The container needs write access to Pi-hole's /etc/pihole and /etc/dnsmasq.d directories, so it is typically run as a sidecar sharing those volumes:

docker run -d --name core-networks2pihole \
  -e CORE_API_LOGIN=api-user \
  -e CORE_API_PASSWORD=secret \
  -v pihole-etc:/etc/pihole \
  -v pihole-dnsmasq:/etc/dnsmasq.d \
  core-networks2pihole-docker

Pi-hole picks up the generated files on its next reload.

⁠Configuration

Credentials are read from the environment on every loop iteration and a fresh token is requested each time, so a rotated password takes effect within one interval without a restart.

Pass credentials through a secret store or an env file rather than on the command line — they end up in the process list otherwise.

⁠Building

docker build -t core-networks2pihole-docker .

The image is based on Debian 12 and contains only curl and jq on top of it.

⁠Limitations

• Only A, AAAA and CNAME record types are mirrored. MX, TXT, SRV and others are ignored by design — they are not useful as local hosts entries.
• All zones of the account are imported; there is no filter.
• The loop runs forever and has no health endpoint. Container logs report each zone update and whether a file was skipped as empty.

⁠Contributing

This project uses pre-commit for style and quality checks, Conventional Commits for the history, and Renovate for dependency updates.

⁠License

MIT — see LICENSE⁠.