Domains without a DNS API

If a domain is at a DNS provider sslbrain has no built-in support for, there are four ways to validate it. Use CNAME delegation whenever the DNS provider can create a CNAME record.

When you need this

Your DNS provider is not among the built-in providers, or it has no API.
You run your own DNS server.
You do not want to give sslbrain an API key that can change the whole zone.

The methods:

CNAME delegation: any DNS provider, including those without an API.
RFC 2136: your own DNS server with TSIG.
Your own REST provider: a REST API that sslbrain does not know.
Script: a script on the appliance.

CNAME delegation

You create a CNAME record once, from _acme-challenge.<domain> to the appliance’s CNAME target. sslbrain gets no key to your DNS. The appliance must be connected to sslbrain Cloud.

The procedure is under CNAME delegation in step 6.

Your own DNS server with RFC 2136

The appliance updates your DNS server with nsupdate under RFC 2136, signed with a TSIG key. It needs:

A name server that is authoritative for the zone and accepts updates signed with TSIG, for example BIND.
A TSIG key that may create and delete TXT and CNAME records under _acme-challenge in the zone.
An appliance that can reach the name server.
A zone that is visible from outside. The CA looks up the validation record in public DNS.

Click Add DNS API credential (DNS API). The form requires a built-in provider. Choose Hetzner DNS, for example, enter any text in Hetzner DNS API Token, and click Save. The text is not used.
Open the credential again under Credentials, and choose native (RFC 2136 nsupdate) under Executor adapter.

Fill in the fields. They are shown in Danish:

Field	Value
Nameserver (server)	The name server’s name or address, for example `ns1.internal.example.com`
Zone	The zone, for example `example.com`
TSIG algoritme	`hmac-sha256` (default), `hmac-sha384`, `hmac-sha512`, `hmac-sha224` or `hmac-sha1`
TTL (sekunder)	5 to 86400, default 60
Username	The TSIG key’s name
Password / Key	The TSIG key’s secret in base64

Enter the zone in Zone-bindinger (en pr linje), and save.

Your own REST provider

If the DNS provider has a REST API that sslbrain has no built-in support for, you describe the API in a form. sslbrain uses the description to find the zone, create the validation record and delete it again. The keys are kept encrypted in the vault on the credential.

Click Add DNS API credential and choose New custom REST DNS provider… under DNS-udbyder.

Describe the provider:

Section	Fields
The provider	Provider name, Description (optional), Base URL (HTTPS only, on a public address)
Sign-in	Auth type: Bearer token, Basic auth (username and password), a named header, key and secret in one header, or a query parameter. The options are shown in Danish. Then Header name, Header format or Query parameter, depending on the type
Zones	Path to the zone list (GET), JSON path to the list, JSON path to the zone id, JSON path to the zone name
Create record	Method (POST, PUT or PATCH), Path, Body template (JSON), TTL (seconds)
Delete record	Deletion: Single call (creating returns the record id, and deletion is one DELETE) or Two-step (list records, find the id with a JSON path, then DELETE), with the paths and JSON paths for them

Paths and body can use {zone_id}, {zone}, {name} (relative to the zone), {fqdn}, {type}, {value} and {ttl}. The deletion path can also use {record_id}. A JSON path is written with dots, for example data.records or result.

Enter the keys and click Test access. The test runs against the provider without saving anything.
Click Save.

The provider is always called directly from the appliance, never through the sslbrain Cloud proxy. A change to the description applies to every credential that uses the provider.

Script on the appliance

A DNS API credential can run a script on the appliance instead of calling a provider. The web interface cannot put the file on the appliance, so place it like this:

Virtual appliance: choose 9 Danger zone and 1 Open a root shell in the console menu. The root shell opens with an answer from sslbrain Cloud. Put the file in /opt/sslbrain/data/dns-scripts/, which is /data/dns-scripts/ inside the appliance.
Docker: put the file in the dns-scripts directory on the volume mounted as /data.

Make the file executable with chmod 755. If you cannot get to the appliance’s file system, use RFC 2136 or your own REST provider.

Create the credential as for RFC 2136, but choose script under Executor adapter. Fill in Sti til operator-script, for example /data/dns-scripts/<name>.sh, and if needed Script timeout (sekunder) (5 to 300, default 60). The fields are shown in Danish.

The script gets these environment variables:

Variable	Content
`SSLBRAIN_DNS_ACTION`	`create` or `remove`
`SSLBRAIN_DNS_RECORD_NAME`	The record’s name
`SSLBRAIN_DNS_RECORD_TYPE`	The record’s type
`SSLBRAIN_DNS_RECORD_VALUE`	The record’s value
`SSLBRAIN_DNS_FQDN`	The name being validated
`SSLBRAIN_DNS_AUTODNS_TARGET`	The appliance’s CNAME target
`SSLBRAIN_DNS_REQUIREMENT_ID`	The validation’s id, when there is one
`SSLBRAIN_DNS_USERNAME`	Username from the credential
`SSLBRAIN_DNS_SECRET_FILE`	Path to a file with permissions 0600 that holds Password / Key. The secret is never on the command line

Exit code 0 means done, 2 means done with a warning, and any other code means failure.

Check that it works

CNAME delegation: enter a name in the zone under Test a domain on Domain validation, and click Check domain.
Your own REST provider: open the credential under Credentials and click Test access.
RFC 2136 and script: there is no Test access. Create the rule as in step 8. The Domain validation panel in the wizard should show “Validated with the DNS API credential” and the credential’s name.

If issuance still fails, see Validation fails.