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.
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)
go build -o bin/blipd ./cmd/blipd
go build -o bin/blipctl ./cmd/blipctl
go build -o bin/blipc ./cmd/blipc
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-depsPrefer 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-depscurl -sL https://raw.githubusercontent.com/twobip/BlipDNS/master/scripts/install-blipd.sh | sudo bash
# or: sudo bash -s stable # pin to the latest tagged releaseInstalls:
blipdbinary →/usr/local/bin/blipd- Default config →
/etc/blipd/blipd.yaml(chmod 600, secureadmin_tokengenerated 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.yamlcurl -sL https://raw.githubusercontent.com/twobip/BlipDNS/master/scripts/install-blipc.sh | sudo bash
# or: sudo bash -s stableInstalls:
blipc(web dashboard) andblipctl(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.yamlCopy 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.
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.
./bin/blipd -config config.example.yaml
It listens on:
dns_addrclassic DNS over UDP + TCPdoh_addrDNS-over-HTTPS atGET/POST /dns-query(RFC 8484)admin_addrmanagement API (token-protected, HTTPS by default using the DoH certificate;-admin-tls-cert/-admin-tls-keyoverride with own files)
The upstream field accepts space/comma-separated specs with failover:
udp://host:port(or a bareip/host:port; missing port defaults to 53)tls://host(DNS-over-TLS, port 853)https://host/dns-queryordoh://host/dns-query
Example: upstream: "https://1.1.1.1/dns-query https://8.8.8.8/dns-query"
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 setsADon secure answers; ADis served only from trusted upstreams and only to clients that asked withDOorAD(RFC 6840), withCD=0;- trust defaults to
tls://(DoT) andhttps:///doh://(DoH). Plain UDP/TCP is untrusted unless the server setstrust_ad: true— for example a local validating Unbound.trust_ad: falseopts an encrypted server out. Only do this on a trusted path (loopback/LAN): a plaintext AD bit is forgeable on the wire. The legacyupstream:string and per-policyupstreamoverrides 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 DNSIn 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.
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.
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
go test ./...
