gibdns-luadns

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

Uses the official luadns-go v0.3.0 client for the LuaDNS API and gibdns-go v0.2.0 for the exec-json binding, DNS validation, revisions, and RRset patch semantics.

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

Install

From this source directory, with Go 1.26.3 or newer:

make build
sudo make install PREFIX=/usr/local

The binary installs to /usr/local/libexec/gibdns/gibdns-luadns, not PATH. It reads one JSON request from stdin and writes one JSON response to stdout; it is not an interactive CLI. Confirm the installation with:

test -x /usr/local/libexec/gibdns/gibdns-luadns

GoReleaser configuration is included for static binary archives and Debian packages. Debian packages install to /usr/libexec/gibdns.

LuaDNS setup

Enable API access in LuaDNS settings. Create an API key, preferably restricted to the zone you need. LuaDNS authenticates with your account email and API key; see the official API documentation.

Config

• email (required string): LuaDNS account email.
• api_url (optional string): API base URL, default https://api.luadns.com/v1. A custom URL must be absolute HTTP(S), without embedded credentials, query, or fragment. Keep HTTPS for real credentials; HTTP is useful for a local test server.

Secrets

• api_key (required): LuaDNS API key. Hosts pass it in provider.secrets through stdin, not command-line arguments or environment variables.

Use with gibcert

Store the API key at /etc/gibcert/luadns-api-key with mode 0600, then:

provider luadns {
  type dns
  driver exec
  command /usr/local/libexec/gibdns/gibdns-luadns
  email user@example.com
  zone example.com.

  secret api_key {
    file /etc/gibcert/luadns-api-key
  }
}

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

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

zone is optional: discovery selects the longest matching accessible zone, including delegated subzones. An explicit zone is an exact selector and never falls back to its parent. For a Debian package, change command to /usr/libexec/gibdns/gibdns-luadns.

See Using gibdns and gibcert's external DNS providers guide for host configuration and DANE publication.

Behavior and constraints

Supported types: A, AAAA, CAA, CNAME, DS, MX, NS, OPENPGPKEY, PTR, SRV, SSHFP, TLSA, and TXT. RFC 3597 generic RDATA is decoded into native presentation for these types. LuaDNS pseudo-records such as ALIAS and REDIRECT are not Internet-class DNS record types and are not advertised.

• Reads paginate both zones and records, deduplicate semantic RDATA, and report the lowest member TTL when LuaDNS records have different TTLs.
• Writes use LuaDNS's bulk RRset update operation; deletion matches only the requested owner and type. Neither operation replaces the whole zone.
• Patch preserves observed, unmentioned RDATA and TTL. LuaDNS has no conditional-write API, so concurrent_safe_patch is false. Serialize writers to a shared RRset. The runtime's if_revision and if_absent checks are read-time preconditions, not atomic LuaDNS compare-and-swap.
• Default TTL is 300 seconds; minimum TTL is 60 seconds. Lower exact TTLs return constraint_violation. ttl_policy: "provider-adjust" raises them to 60 and returns a ttl_adjusted warning instead of silently accepting API clamping.
• TXT is quoted DNS presentation in gibdns and literal UTF-8 text in LuaDNS. Values must contain 1–2048 bytes; empty or oversized values are rejected before writing. Long values use 255-byte character-string chunks. Non-UTF-8 content and incompatible chunk boundaries return constraint_violation, preventing JSON encoding or text concatenation from silently changing DNS RDATA.
• Requests propagate their context/deadline through the SDK, whose per-HTTP-call timeout is 10 seconds. Authorization, rate-limit resets, and temporary network or server errors are mapped to gibdns errors. The runtime redacts secrets.

Development

make test-race
make lint
make build
make snapshot

Tests use a local HTTP server and the real LuaDNS client; no account or network credentials are required. Live LuaDNS behavior and public DNS propagation require a configured account and are not covered by these tests.

Configure an origin remote before using GoReleaser commands. Its configuration checker uses that URL to identify the repository even when nothing is published.

Publish a tagged release with make release. That target runs GoReleaser via go run; the remote repository and a GITEA_TOKEN with release access must exist first.