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.
Releases & Development Snapshots
Releases
You can subscribe to the atom feed to be notified of project releases.
The most recently released version of the package is 1.0.0.
1.0.0 Release (2024-10-30Z)
- Initial release.
The compiled artifacts for the release (and all previous releases) are available on Maven Central.
Development Snapshots
At the time of writing, the current unstable development version of the package is 1.0.1-SNAPSHOT.
Development snapshots may be available in the Central Portal Snapshots repository. Snapshots are published to this repository every time the project is built by the project's continuous integration system, but snapshots do expire after around ninety days and so may or may not be available depending on when a build of the package was last triggered.
Manual
This project does not have any user manuals or other documentation beyond what might be present on the page above.
Sources
This project uses Git to manage source code.
Repository: https://www.github.com/io7m-com/blockhead
$ git clone --recursive https://www.github.com/io7m-com/blockhead
Issues
This project uses GitHub Issues to track issues.
License
Copyright © 2024 Mark Raynsford <code@io7m.com> https://www.io7m.com Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.