Skip to content
twobipPublic

About

A fast DNS resolver in Go with per-client filtering and DNS-over-HTTPS

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

BlipDNS

BlipDNS logo

Beta software: BlipDNS is currently in beta — expect rough edges and breaking changes between updates.

A fast DNS server in Go with per-client filtering, DNS-over-HTTPS (RFC 8484), a controller (blipc) with a web dashboard that manages fleets of instances, and a CLI (blipctl) for driving instances directly.

Layout

cmd/blipd     the resolver daemon (classic DNS + DoH + management API)
cmd/blipc     the controller: web dashboard + fleet manager
cmd/blipctl   the controller CLI (connects to managed instances)
internal/
  filter/     per-client CIDR policy store + suffix/wildcard domain matching
  cache/      TTL-aware DNS response cache with singleflight coalescing
  upstream/   DoH + UDP resolvers with failover
  control/    management API server + controller client (shared types)
  controller/ fleet manager, web dashboard, setup/auth (used by blipc)
  dnsserver/  unified UDP/TCP/DoH query path: filter -> cache -> upstream
  config/     YAML configuration loader
  blocklist/  global DNS blocklist feeds (AdBlock Plus / hosts format)
  certgen/    self-signed TLS certificates for DoH
  ha/         high-availability virtual-IP failover (keepalived)
  update/     blipd self-updater (unprivileged download + install helper)

Build

go build -o bin/blipd ./cmd/blipd
go build -o bin/blipctl ./cmd/blipctl
go build -o bin/blipc ./cmd/blipc

Install (one-liner)

The installers require root privileges. They download the pre-built static binary from the latest signed release by default — no Go toolchain, no git. --install-deps installs the runtime dependencies (CA certificates, curl, openssh-client for the release-signature check) with the detected system package manager. Pass --build-from-source (with --install-deps when Go is missing) to clone the pinned ref and build locally instead; that path needs Go 1.27.4+ (GO-2026-6859) and installs the official Go archive under /usr/local/go-blipdns-1.27.4 when the distro Go is older. Later runs reuse that installation and do not download Go again:

curl -sL https://raw.githubusercontent.com/twobip/BlipDNS/master/scripts/install-blipd.sh | sudo bash -s -- --install-deps
curl -sL https://raw.githubusercontent.com/twobip/BlipDNS/master/scripts/install-blipc.sh | sudo bash -s -- --install-deps

Prefer download-then-inspect over piping to root: the installers refuse unsigned releases (missing .sig is fatal), but a pipe executes whatever the mirror serves before you can read it.

curl -sL https://raw.githubusercontent.com/twobip/BlipDNS/master/scripts/install-blipd.sh -o /tmp/install-blipd.sh
less /tmp/install-blipd.sh   # inspect, then:
sudo bash /tmp/install-blipd.sh --install-deps

Resolver daemon (blipd)

curl -sL https://raw.githubusercontent.com/twobip/BlipDNS/master/scripts/install-blipd.sh | sudo bash
# or: sudo bash -s stable   # pin to the latest tagged release

Installs:

  • blipd binary → /usr/local/bin/blipd
  • Default config → /etc/blipd/blipd.yaml (chmod 600, secure admin_token generated automatically)
  • systemd unit → /etc/systemd/system/blipd.service

The installer generates a secure random admin_token in the config automatically. It preserves that token on later installer runs. Keep the token private; it authenticates the blipd management API and is needed when adding the instance to blipc.

Then:

sudo systemctl enable --now blipd
sudo grep '^admin_token:' /etc/blipd/blipd.yaml

Controller (blipc + blipctl)

curl -sL https://raw.githubusercontent.com/twobip/BlipDNS/master/scripts/install-blipc.sh | sudo bash
# or: sudo bash -s stable

Installs:

  • blipc (web dashboard) and blipctl (CLI) → /usr/local/bin/
  • Default config → /etc/blipc/blipc.yaml (chmod 600)
  • systemd unit → /etc/systemd/system/blipc.service

On the first start, blipc prints a first-run setup URL in the service log. Create the administrator account through the web UI:

sudo systemctl enable --now blipc
sudo journalctl -u blipc -n 50 --no-pager | grep 'setup'

If systemd is not available, run blipc manually and keep it running:

sudo /usr/local/bin/blipc -config /etc/blipc/blipc.yaml

Copy the setup URL printed by blipc. Open it in a browser. The setup wizard walks through three steps: administrator account (an 8–72 character password, you are signed in automatically), dashboard bind address (applies after a controller restart), and adopting a blipd instance (skippable). After the account is created, setup is disabled and you can manage instances from the dashboard. No token is needed: whoever opens the setup page first claims the controller, so use it on a trusted network or over HTTPS, and start the service only when you are ready to claim it.

Both scripts accept an optional argument: master (default), stable, or a version tag (e.g. v1.2.3), plus the --install-deps option. They clone the repo, build from source, and install under /usr/local/bin with secure config directories.

Update signing

Self-updates (blipd-update / blipc-update, elevated through the root install helpers) verify an ed25519 signature over the release's SHA256SUMS before installing: the root helper checks SHA256SUMS.sig against a public key embedded in the helper itself, then binds each staged binary to a hash taken from the signed sums. A compromised mirror — or a release publisher without the signing key — cannot get an unsigned binary installed. The release workflows sign with the RELEASE_SIGNING_KEY repository secret (ssh-keygen -Y sign, namespace blipdns-release).

Two honest limits: the one-line installer remains trust-on-first-use (verify it against a pinned ref before piping to root), and releases cut before signing existed carry no .sig — the first signed stable release is 0.8.0. Re-run the installer once on each node, then update onto a signed release. To rotate the key: add the new public key line beside the old one in both scripts/*-install.sh helpers, release, re-run the installers on the nodes, then swap the CI secret.

Run blipd

./bin/blipd -config config.example.yaml

It listens on:

  • dns_addr classic DNS over UDP + TCP
  • doh_addr DNS-over-HTTPS at GET/POST /dns-query (RFC 8484)
  • admin_addr management API (token-protected, HTTPS by default using the DoH certificate; -admin-tls-cert/-admin-tls-key override with own files)

The upstream field accepts space/comma-separated specs with failover:

  • udp://host:port (or a bare ip/host:port; missing port defaults to 53)
  • tls://host (DNS-over-TLS, port 853)
  • https://host/dns-query or doh://host/dns-query

Example: upstream: "https://1.1.1.1/dns-query https://8.8.8.8/dns-query"

DNSSEC

blipd is a forwarder and does not validate DNSSEC itself. dnssec: true in blipd.yaml (or Upstream → Use DNSSEC in blipc) delegates validation to the upstream resolver:

  • upstream queries get DO=1, so a validating upstream returns signatures and sets AD on secure answers;
  • AD is served only from trusted upstreams and only to clients that asked with DO or AD (RFC 6840), with CD=0;
  • trust defaults to tls:// (DoT) and https:///doh:// (DoH). Plain UDP/TCP is untrusted unless the server sets trust_ad: true — for example a local validating Unbound. trust_ad: false opts an encrypted server out. Only do this on a trusted path (loopback/LAN): a plaintext AD bit is forgeable on the wire. The legacy upstream: string and per-policy upstream overrides have no per-server metadata and follow the transport default;
  • DNSSEC records are stripped from answers to clients that did not set DO (except a type they explicitly queried), per RFC 4035.
upstream_servers:
  - name: unbound
    address: "udp://127.0.0.1:53"
    priority: 1
    trust_ad: true      # Unbound validates; trust its AD over plain DNS

In blipc, tick All upstream servers to trust the whole list, or untick it and open the Select resolvers picker to search and tick individual resolvers. The setting is pushed live and reconciled after an instance restarts; blipd purges its response cache when the mode or upstream trust changes. When blipc manages an instance, its fleet default/override is authoritative — the blipd.yaml value only seeds the mode until the first push.

This is the AdGuard-Home-style "trusted forwarder" model, not Pi-hole-style local validation: a bogus signed answer is only rejected if the upstream rejects it. A validating client (browser, OS stub) can still validate end-to-end because RRSIGs pass through when it sets DO. dnssec: false (the default) keeps the previous behavior: AD is always cleared.

Per-client filtering

Policies map a client source IP (longest-prefix CIDR match) to an allow/block list. Matching supports exact names, suffix (ads.example.com matches sub.ads.example.com), and wildcard (*.tracker.net matches any subdomain but not tracker.net). The allowlist takes precedence over the blocklist. A default_policy applies to clients with no matching network.

block_action is one of: nxdomain (default), refused, zero.

Controller: blipctl

blipctl [--token TOKEN] <instance-url|instance-id> <command> [args]
blipctl --socket <path> <command> [args]   # local blipd admin socket, no token

  health                 show instance health
  stats                  show live stats
  policies               list filter policies
  set-policy <file.yml>  push a policy
  block <cidr> <domain>  add a block policy for a client CIDR
  del-policy <id>        remove a policy
  adopt-status           show adoption state (no token needed)
  adopt <code>           claim this instance once; prints its admin token
  watch                  stream events (SSE)

On the controller host an instance id is enough (the token is read from the local blipc config); --token-file is preferred over --token.

Example:

blipctl --token SECRET http://10.0.0.5:8444 set-policy kids.yaml
blipctl --token SECRET http://10.0.0.5:8444 block 192.168.10.0/24 ads.net

Test

go test ./...

About

A fast DNS resolver in Go with per-client filtering and DNS-over-HTTPS

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages