gibdns

gibdns is a provider-neutral protocol for managing DNS records through an external program. It is intended for applications that need to publish DNS data without embedding every DNS provider's API client and dependencies.

If you want ACME DNS-01 or DANE TLSA with gibcert, start with Using gibdns: install a provider binary from the catalog, then point gibcert's command at it. You do not need to implement the protocol yourself unless you are writing a new provider or host.

Typical hosts include certificate managers, DANE/TLSA automation, ACME DNS challenge clients, and ECH configuration managers. The protocol itself does not contain operations specific to any of those applications. It exposes a small set of general DNS RRset operations instead.

The initial binding invokes a provider executable once per request:

the client writes one JSON request to the provider's standard input;
the provider writes one JSON response to standard output;
the provider may write human-readable diagnostics to standard error; and
configuration and secrets are structured JSON rather than protocol-specific environment variables.

Documentation

Using gibdns: install a provider and use it from a host
Provider catalog: Cloudflare, deSEC, Gcore, and how to add more
Software using gibdns
Protocol specification

The current protocol identifier is gibdns/draft-01. This draft is a frozen implementation target: incompatible or normative changes will use a new protocol identifier. The eventual stable first version will use gibdns/1.

Design principles

Model RRsets, because TTL and replacement semantics apply to an RRset rather than an individual resource record.
Keep record data type-neutral by using standard DNS presentation syntax.
Provide merge-style changes for safely adding or removing one RRset member.
Provide conditional replacement for read-modify-write use cases such as updating an ECH parameter in an HTTPS record.
Make every mutation idempotent so an uncertain or interrupted request can be retried.
Return structured errors and the effective DNS state, including the actual TTL when a provider adjusts it.
Treat DNS publication and DNS propagation as separate concerns.
Keep the abstract request model independent of the executable binding so a future long-running or remote binding can use the same operations.

Example applications

ACME DNS-01 adds a TXT value with rrset.patch, waits for authoritative DNS propagation, and removes precisely that value after validation.
TLSA automation uses rrset.patch to publish current and next key pins while preserving other pins during a rollover.
ECH automation reads an HTTPS or SVCB RRset, changes the complete RDATA member containing the ech SvcParam, and conditionally writes the updated RRset.

Provider success means that the provider's control plane accepted the requested state. The calling application remains responsible for checking authoritative DNS when propagation matters.