blockhead

JVM	Platform	Status
OpenJDK (Temurin) Current	Linux
OpenJDK (Temurin) LTS	Linux
OpenJDK (Temurin) Current	Windows
OpenJDK (Temurin) LTS	Windows

blockhead

The blockhead package provides a trivial command-line tool to download Domains-syntax DNS blocklists and export them in a format usable as input to an unbound DNS server.

Features

• Download blocklists on a regular schedule and export them to unbound.
• Fully instrumented with OpenTelemetry for service monitoring.
• Platform independence. No platform-dependent code is included in any form, and installations can largely be carried between platforms without changes.
• OCI-ready: Ready to run as an immutable, stateless, read-only, unprivileged container for maximum security and reliability.
• ISC license.

Usage

To run the service, execute:

$ java -jar com.io7m.blockhead.jar run \
  --output-file-temporary list.txt.tmp \
  --output-file list.txt \
  --source https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/domains/ultimate.txt

By default, the service will download the blocklist from the given URL every 24 hours, process and write the results to list.txt.tmp, and then atomically replace list.txt with list.txt.tmp. The practice of atomically renaming ensures that, if list.txt exists, it can always be trusted to be the most recently downloaded blocklist - there is no risk of observing a half-written file.

For service monitoring, OpenTelemetry can be enabled. The application produces traces, and will produce a blockhead_up metric set to 1 whenever the service is up.

$ java -jar com.io7m.blockhead.jar run \
  --output-file-temporary list.txt.tmp \
  --output-file list.txt \
  --telemetry-service-name blockhead01 \
  --telemetry-metrics-address http://metrics.telemetry.example.com:4317 \
  --telemetry-metrics-protocol GRPC \
  --telemetry-logs-address http://logs.telemetry.example.com:4317 \
  --telemetry-logs-protocol GRPC \
  --telemetry-traces-address http://traces.telemetry.example.com:4317 \
  --telemetry-traces-protocol GRPC \
  --source https://cdn.jsdelivr.net/gh/hagezi/dns-blocklists@latest/domains/ultimate.txt

OCI

Container images are available at Quay.io.

The container image exposes an interface identical to the command-line interface above, so simply replace "java -jar com.io7m.blockhead.jar" with a podman invocation.