Domain Chief for libdns
This package implements the libdns interfaces for Domain Chief hosted DNS, allowing you to manage DNS records and solve ACME DNS-01 challenges.
import "github.com/libdns/domainchief"
provider := &domainchief.Provider{
APIToken: "ctt_...",
}| Field | JSON | Description |
|---|---|---|
APIToken |
api_token |
A Domain Chief API token (required). |
BaseURL |
base_url |
Overrides the API base URL, defaults to https://domain.chief.app/api/v1. |
HTTPClient |
- | Overrides the HTTP client used for API requests. |
WaitForPublication |
wait_for_publication |
Makes AppendRecords wait until every nameserver serves new ACME challenge values, see behavior. |
The zone is the domain name in Domain Chief, for example example.com.. The domain must use hosted DNS.
Create an API token in your Chief Tools account for the team that owns your domains. The scopes it needs depend on how you use the provider:
| Use | Scope |
|---|---|
| ACME DNS-01 challenges only | domainchief:acme:write |
| Reading DNS records | domainchief:dns:read |
| Reading and changing any DNS record | domainchief:dns:write |
ListZones |
domainchief:domains:read |
A write scope includes the matching read scope, so domainchief:dns:write also allows reading records.
The domainchief:acme:write scope only allows publishing and deleting TXT records on _acme-challenge names. It cannot read your domains or change any other record, so it is the recommended scope when you only need certificates. Anyone holding the token can still complete DNS-01 challenges and obtain certificates for the domains in your team, so treat it as a secret.
AppendRecordsandDeleteRecordssend TXT records on_acme-challengenames holding an ACME challenge value (base64url characters) to the dedicated ACME challenge endpoints. Those keep other values on the same name, so concurrent challenges for the same name (for exampleexample.comand*.example.com) work. Challenge values that are not deleted are removed automatically after 24 hours. Because the challenge endpoint does not report whether a value existed,DeleteRecordsalways returns challenge records as deleted.- With
WaitForPublicationenabled,AppendRecordsreturns once every hosted DNS nameserver serves the ACME challenge values, so the certificate authority can validate them right away. This usually takes one to three minutes, longer while other changes to the same domain are being published. A challenge that is not published within 10 minutes, or that fails to publish, is deleted and returned as an error. Pass a context with a deadline to wait less. Enable it when you solve ACME challenges: checking the nameservers yourself only reaches the ones near you, which can serve a value before the certificate authority's nameservers do. - All other records use the DNS record endpoints.
- Supported record types are
A,AAAA,ALIAS,CAA,CNAME,MX,NS,SRV,TLSAandTXT.ALIASandTLSArecords are returned aslibdns.RR. - TTLs are rounded to the closest TTL Domain Chief supports (
60,300,900,1800,3600,21600,43200,86400,172800,259200,604800,1209600or2592000seconds). A TTL of0uses3600seconds. SetRecordsis not atomic. For every name and type in the input it keeps records with the same value, updates other existing records to hold the remaining values and deletes leftover records. When an error is returned some of the changes may have been applied.- Requests are retried for a few seconds when another hosted DNS write for the same domain is still running or when the API is rate limiting requests.
- Other DNS changes, and ACME challenges without
WaitForPublication, are published to the hosted DNS nameservers asynchronously. They usually reach every nameserver within one to three minutes.
The unit tests run against a local fake API:
go test ./...The integration test changes records in a real zone. It needs a token with the domainchief:acme:write and domainchief:dns:write scopes:
DOMAINCHIEF_API_TOKEN=ctt_... DOMAINCHIEF_TEST_ZONE=example.com. go test -timeout 15m -run TestIntegration -v ./...CI also runs the integration test on pushes to master when the DOMAINCHIEF_TEST_ZONE repository variable and DOMAINCHIEF_API_TOKEN repository secret are set.
The shared libdns test suite runs from the libdnstest directory with the same environment variables.