gibdns-desec

gibdns provider for deSEC. Hosts such as gibcert execute this binary to publish ACME DNS-01 TXT records and DANE TLSA records.

Protocol	TXT	TLSA	Zone discovery
gibdns/draft-01	yes	yes	yes
gibdns/draft-02	yes	yes	yes

Install

Download the archive or .deb for your OS from the releases page.

Debian package (installs to /usr/libexec/gibdns):

sudo dpkg -i gibdns-desec_*_linux_amd64.deb

Tarball:

sudo install -D -m 0755 gibdns-desec /usr/local/libexec/gibdns/gibdns-desec

From source:

make install PREFIX=/usr/local

The binary is not an interactive CLI and is intentionally not installed on PATH. Confirm the installation, then let the host invoke it:

# Debian package:
test -x /usr/libexec/gibdns/gibdns-desec
# Source or tarball install:
test -x /usr/local/libexec/gibdns/gibdns-desec

Use /usr/libexec/gibdns/gibdns-desec for a Debian package or /usr/local/libexec/gibdns/gibdns-desec for a source or tarball install in host configuration. See Using gibdns for the host and provider split.

Use with gibcert

Store a deSEC token at /etc/gibcert/desec-token with mode 0600. The token must not have token-management permission. Then:

provider desec {
  type dns
  driver exec
  command /usr/libexec/gibdns/gibdns-desec
  zone example.com.

  secret token {
    file /etc/gibcert/desec-token
  }
}

certificate wildcard-example.com {
  account letsencrypt
  names example.com *.example.com

  challenge dns-01 {
    provider desec
    propagation-timeout 120s
  }
}

zone is optional because this provider advertises zone discovery. Set it when you want an exact zone selector. If installed from source or a tarball, use /usr/local/libexec/gibdns/gibdns-desec instead.

gibcert binding details are in External DNS Providers.

Secrets

• token (required): a deSEC token without token-management permission

Config

• api_url (optional)

deSEC RRsets have a default minimum TTL of 3600 seconds. The provider advertises that constraint and honors ttl_policy. Patch is implemented as GET then PUT of the complete RRset, so concurrent_safe_patch is false. Clients such as gibcert should use if_revision.

Batching

rrset.batch (gibdns/draft-02 only) is atomic here: features.batch.atomic is true, so atomic: true and atomic: false are both accepted. All changes of a batch are sent to deSEC as one bulk PATCH of /domains/{zone}/rrsets/, which deSEC documents as all-or-nothing. A deletion is an RRset with records: []. RRsets that need no change are not sent. When every operation is a no-op, no write request is made. The provider sets no maximum_batch_ops; it does not limit the number of operations itself.

Before writing, the provider reads each addressed RRset with one GET per RRset. When deSEC rejects the bulk request with a per-RRset error list, the first rejected RRset is reported with its op_index and the rejected request applies nothing. With atomic: false the operations before the failing one are then applied in a second bulk request, as the batch semantics require.

deSEC rate-limits writes per domain. When it answers 429, the provider waits for Retry-After only if the wait fits the request deadline and a total of 30 seconds for the invocation. Otherwise it returns rate_limited with retry_after_seconds immediately.

In gibdns/draft-02 the if_revision and if_absent preconditions are advertised as check_then_write: the provider evaluates the precondition against freshly read state and then writes. The deSEC API has no conditional write, so a concurrent writer between the read and the write can be overwritten. A client that cannot tolerate that window must not rely on this provider for it.

Development

make test
make build
make snapshot

Publish a tagged release with make release. That target runs GoReleaser via go run; a GITEA_TOKEN with package/release access is required.