gonemaster

module
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 2, 2026 License: BSD-2-Clause

README

Gonemaster

Gonemaster is a Go implementation of the DNS test framework Zonemaster engine and CLI.

Key features:

  1. Parallel-safe engine runs with per-run state isolation
  2. Streaming output with JSON, JSONL, and raw log modes
  3. Built-in API server with job queueing, batches, and progress tracking
  4. Tunable resolver behavior (timeouts, retries, fallback, caching)
  5. Minimal external dependencies (focused, standard Go libraries)

Installation

go install codeberg.org/pawal/gonemaster/cmd/gonemaster@latest

Or build from source:

git clone https://codeberg.org/pawal/gonemaster.git
cd gonemaster
make help
go test ./...
go build -o gonemaster ./cmd/gonemaster
sudo install -m 0755 gonemaster /usr/local/bin/gonemaster

The project includes a Makefile with common targets like build, test, and ui-build. Run make help to see the full list.

CLI

The CLI runs Zonemaster tests and can output human‑readable text, JSON, or raw log streams. See docs/cli.md for full usage, options, and examples.

Quick examples:

gonemaster --domain example.com
gonemaster --json --domain example.com | jq
gonemaster --domain example.com --ns ns1.example.com/192.0.2.10 --ns ns2.example.net
gonemaster --domain example.com --ns ns1.example.com/192.0.2.10 --ns ns1.example.com/2001:db8::10

ascii animation

API Server and UI

Gonemaster includes an API server with an included Web User Interface. Please read the documentation in docs/server.md to know more.

UI screenshot

There is also a CLI for testing domains through the API - gonemaster-client also has support for batch operations.

The API also has extensive metrics endpoints that can be used for server and jobs monitoring, and the Web UI includes this in a separated tab.

Metrics screenshot

Nagios plugin

Nagios documentation has moved to docs/nagios.md.

Engine usage

Developer usage (engine APIs, callbacks, profiles, and localization) is covered in docs/dev.md.

Testcase Specifications

Canonical specifications for all 73 implemented testcases are in docs/specifications/.

The make spec-validate and make spec-check-tags targets verify that specs and code metadata stay in sync.

Development

Run test coverage:

go test --cover ./...

Directories

Path Synopsis
cmd
gonemaster command
Package main implements the gonemaster command.
 Package main implements the gonemaster command.
gonemaster-client command
Package main implements the gonemaster-client command.
 Package main implements the gonemaster-client command.
gonemaster-nagios command
Package main implements the gonemaster-nagios command.
 Package main implements the gonemaster-nagios command.
gonemaster-server command
Package main implements the gonemaster-server command.
 Package main implements the gonemaster-server command.
Package engine provides the public entry points for running Gonemaster test plans and collecting normalized log output.
 Package engine provides the public entry points for running Gonemaster test plans and collecting normalized log output.
asnlookup
Package asnlookup provides ASN and prefix lookup helpers used by test cases.
 Package asnlookup provides ASN and prefix lookup helpers used by test cases.
cache
Package cache provides small cache key and strategy helpers.
 Package cache provides small cache key and strategy helpers.
constants
Package constants contains shared constants and embedded reference datasets.
 Package constants contains shared constants and embedded reference datasets.
dnsname
Package dnsname provides DNS name parsing and hierarchy helpers.
 Package dnsname provides DNS name parsing and hierarchy helpers.
hints
Package hints parses root hints text into nameserver/address mappings.
 Package hints parses root hints text into nameserver/address mappings.
i18n
Package i18n provides translation helpers for emitted test tags.
 Package i18n provides translation helpers for emitted test tags.
internal/parallel
Package parallel provides bounded, ordered parallel task execution helpers.
 Package parallel provides bounded, ordered parallel task execution helpers.
internal/testhelpers
Package testhelpers contains common setup utilities for engine tests.
 Package testhelpers contains common setup utilities for engine tests.
logger
Package logger provides structured run-time logging and filtering.
 Package logger provides structured run-time logging and filtering.
methods
Package methods implements shared test specification methods.
 Package methods implements shared test specification methods.
methodsv2
Package methodsv2 implements version 2 shared test specification methods.
 Package methodsv2 implements version 2 shared test specification methods.
nameserver
Package nameserver provides DNS nameserver endpoint querying and caching.
 Package nameserver provides DNS nameserver endpoint querying and caching.
normalization
Package normalization validates and canonicalizes user-provided domain names.
 Package normalization validates and canonicalizes user-provided domain names.
packet
Package packet wraps dns.Msg with helpers mirroring Zonemaster semantics.
 Package packet wraps dns.Msg with helpers mirroring Zonemaster semantics.
profile
Package profile models, loads, and merges Zonemaster profile settings.
 Package profile models, loads, and merges Zonemaster profile settings.
recursor
Package recursor performs iterative DNS recursion for lookup helpers.
 Package recursor performs iterative DNS recursion for lookup helpers.
test/address
Package address implements ADDRESS module test cases.
 Package address implements ADDRESS module test cases.
test/basic
Package basic implements BASIC module test cases.
 Package basic implements BASIC module test cases.
test/connectivity
Package connectivity implements CONNECTIVITY module test cases.
 Package connectivity implements CONNECTIVITY module test cases.
test/consistency
Package consistency implements CONSISTENCY module test cases.
 Package consistency implements CONSISTENCY module test cases.
test/delegation
Package delegation implements DELEGATION module test cases.
 Package delegation implements DELEGATION module test cases.
test/dnssec
Package dnssec implements DNSSEC module test cases.
 Package dnssec implements DNSSEC module test cases.
test/internal/runner
Package runner provides test harness helpers for running test cases.
 Package runner provides test harness helpers for running test cases.
test/internal/testcase
Package testcase provides shared test case utilities.
 Package testcase provides shared test case utilities.
test/internal/testlogger
Package testlogger provides buffered logger helpers for tests.
 Package testlogger provides buffered logger helpers for tests.
test/nameserver
Package nameserver implements NAMESERVER module test cases.
 Package nameserver implements NAMESERVER module test cases.
test/syntax
Package syntax implements SYNTAX module test cases.
 Package syntax implements SYNTAX module test cases.
test/zone
Package zone implements ZONE module test cases.
 Package zone implements ZONE module test cases.
transport
Package transport provides DNS transport clients and query limiting.
 Package transport provides DNS transport clients and query limiting.
util
Package util provides cross-module helper functions.
 Package util provides cross-module helper functions.
validation
Package validation provides domain and label validation helpers.
 Package validation provides domain and label validation helpers.
zone
Package zone models a tested DNS zone and its parent/delegation helpers.
 Package zone models a tested DNS zone and its parent/delegation helpers.
Package server implements the Gonemaster HTTP API, in-memory queue/store backends, worker orchestration, and runtime metrics endpoints.
 Package server implements the Gonemaster HTTP API, in-memory queue/store backends, worker orchestration, and runtime metrics endpoints.
ui
Package ui serves the embedded web UI assets for the API server.
 Package ui serves the embedded web UI assets for the API server.
Package share exposes embedded static assets and default data files.
 Package share exposes embedded static assets and default data files.
tools
server-perf-kit/cmd/registrable command
specifications/export-implemented command
specifications/export-tags command
specifications/generate-tag-catalog command
generate-tag-catalog generates per-module tag catalog markdown files under docs/specifications/tags/ from live code metadata and share/profile.json.
 generate-tag-catalog generates per-module tag catalog markdown files under docs/specifications/tags/ from live code metadata and share/profile.json.
specifications/internal/specdata
specifications/validate command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.