README
¶
Wegweiser
An authoritative DNS server with a web interface you don't need a manual for.
[!WARNING] Pre-alpha. There is no release yet, and no upgrade path between commits. It answers queries and most of the v0.1 feature set is in place, but none of it has run in production and the on-disk format may still change without a migration. Follow the changelog.
Wegweiser is a single static binary that runs an authoritative DNS server. It is a side project, written by one person who got tired of editing zonefiles by hand. Wegweiser is German for signpost.
What it does today
Start the binary, open the web interface, have a working zone in five minutes, without learning zonefile syntax first.
Reverse zones manage themselves. Add an A record, get the matching PTR in the right
reverse zone. IPv6 nibble zones and RFC 2317 classless delegation included. Delete it, the
PTR goes too. Conflicts are shown, never silently overwritten.
Every change is reversible. Each edit is a journal event, so zone history, a diff of any change, an audit trail and rollback to an earlier state all come from one mechanism.
Two clients, one API. A dense, keyboard-driven web interface with a command palette and a live query stream, and a CLI that reaches everything the interface does.
Also here: authoritative UDP and TCP with EDNS0, zonefile import and export, SQLite persistence, token-authenticated REST API, Prometheus metrics. Single node.
What it does not do
Not built, and not in v0.1: clustering, weg tui, DNSSEC, recursion and caching, outbound
AXFR/IXFR, DoT/DoH/DoQ, PostgreSQL, split-horizon views. Some of these are planned and the
journal and Store interface are shaped to fit them later; none of them exists today.
Nothing here has run in production, and the numbers in docs/decisions.md D12 are targets rather than measurements of a real deployment.
Installing
A release carries a static binary for linux/amd64 and linux/arm64, with checksums.
$ curl -LO https://github.com/wegweiserzone/wegweiser/releases/latest/download/checksums.txt
$ curl -LO https://github.com/wegweiserzone/wegweiser/releases/latest/download/weg_0.1.0_linux_amd64.tar.gz
$ sha256sum -c --ignore-missing checksums.txt
$ tar xzf weg_0.1.0_linux_amd64.tar.gz && ./weg version
Or as a container, which is scratch with the one binary in it:
$ podman run --rm --cap-add=NET_BIND_SERVICE -p 53:53/udp -p 53:53/tcp -p 8053:8053 \
-v weg:/var/lib/wegweiser ghcr.io/wegweiserzone/wegweiser:latest
--cap-add=NET_BIND_SERVICE is what binding port 53 needs; the server never wants root.
Building
Requires Go 1.26.5 or newer. No cgo, no C toolchain.
$ git clone https://github.com/wegweiserzone/wegweiser
$ cd wegweiser
$ make build
$ ./bin/weg version
$ make check # everything CI runs: tidy, format, vet, lint, tests
$ make test # tests with the race detector
$ make help # all targets
Documentation
| Document | What it covers |
|---|---|
| Decisions | Settled design questions and the reasoning |
| ADRs | Architecture decision records |
| Conventions | Product thesis, invariants, scope fence, the design bar |
Contributing
See CONTRIBUTING.md. Contributions are certified with a Signed-off-by
line (DCO); there is no CLA.
Security issues: please follow SECURITY.md rather than opening a public issue.
License
GNU Affero General Public License v3.0.
Chosen deliberately for a network-facing server: if you run a modified Wegweiser as a service, its users are entitled to the source. Note that this is more restrictive than PowerDNS (GPLv2), Knot DNS (GPLv3) and CoreDNS (Apache-2.0).
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
weg
command
Command weg runs and operates a Wegweiser DNS server.
|
Command weg runs and operates a Wegweiser DNS server. |
|
internal
|
|
|
api
Package api is the HTTP interface every Wegweiser client speaks.
|
Package api is the HTTP interface every Wegweiser client speaks. |
|
api/gen
Package gen provides primitives to interact with the openapi HTTP API.
|
Package gen provides primitives to interact with the openapi HTTP API. |
|
apply
Package apply is the write path, and the only thing that changes zone data.
|
Package apply is the write path, and the only thing that changes zone data. |
|
buildinfo
Package buildinfo exposes the version of the running binary.
|
Package buildinfo exposes the version of the running binary. |
|
cli
Package cli assembles the weg command tree.
|
Package cli assembles the weg command tree. |
|
cli/output
Package output renders command results in the three formats every weg command supports: human-readable text, JSON and YAML.
|
Package output renders command results in the three formats every weg command supports: human-readable text, JSON and YAML. |
|
config
Package config assembles the settings a Wegweiser process starts with.
|
Package config assembles the settings a Wegweiser process starts with. |
|
dns
Package dns is the data plane: it answers queries and does nothing else.
|
Package dns is the data plane: it answers queries and does nothing else. |
|
id
Package id generates the identifiers Wegweiser uses as primary keys.
|
Package id generates the identifiers Wegweiser uses as primary keys. |
|
journal
Package journal records every change to a zone as an ordered sequence of commits.
|
Package journal records every change to a zone as an ordered sequence of commits. |
|
metrics
Package metrics is what this server tells a monitoring system.
|
Package metrics is what this server tells a monitoring system. |
|
store
Package store defines the persistence boundary of Wegweiser.
|
Package store defines the persistence boundary of Wegweiser. |
|
store/sqlite
Package sqlite implements the Wegweiser store on SQLite.
|
Package sqlite implements the Wegweiser store on SQLite. |
|
store/storetest
Package storetest is the conformance suite every store.Store implementation has to pass.
|
Package storetest is the conformance suite every store.Store implementation has to pass. |
|
stream
Package stream carries answered queries to whoever is watching them.
|
Package stream carries answered queries to whoever is watching them. |
|
zone
Package zone holds the domain model: names, zones, records, validation and the reverse-mapping rules.
|
Package zone holds the domain model: names, zones, records, validation and the reverse-mapping rules. |
|
zonefile
Package zonefile reads and writes zone data in the presentation format of RFC 1035 §5: what everybody calls a zonefile.
|
Package zonefile reads and writes zone data in the presentation format of RFC 1035 §5: what everybody calls a zonefile. |