Domains without a DNS API

sslbrain has 19 built-in DNS providers. If a domain is hosted elsewhere, there are four ways to validate it.

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 for internal or external zones.
You do not want to give sslbrain an API key that can change the whole zone.

Situation	Method
Any provider, including those without an API	CNAME delegation
Your own DNS server that accepts dynamic updates signed with TSIG	RFC 2136
A provider with a REST API that sslbrain does not know	Your own REST provider
A script that is already on the appliance	Script

CNAME delegation

You create a CNAME record once, from _acme-challenge.<domain> to the appliance’s CNAME target. After that, DNS for the domain need not be touched again, and sslbrain gets no key to your DNS. All it takes is a DNS provider that can create a CNAME record, and an appliance connected to sslbrain Cloud.

The procedure is under CNAME delegation in step 6.

Your own DNS server with RFC 2136

sslbrain can update your own DNS server with RFC 2136 (dynamic update), signed with a TSIG key. The appliance runs nsupdate against the name server itself.

Requirements:

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

Create a DNS API credential with Add DNS API credential, as described in DNS API. The form for a new credential requires a built-in provider. Choose Hetzner DNS, for example, and enter any text in Hetzner DNS API Token; the field is not used once the adapter has been changed in step 2. Click Save.
Open the credential again under Credentials, and choose native (RFC 2136 nsupdate) under Executor adapter (the field has this name in every language).

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. It replaces the text from step 1

Enter the zone in Zone-bindinger (en pr linje), so the credential is used for names in the zone, and save.

Your own REST provider

If the DNS provider has a REST API that sslbrain has no built-in provider 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 description is saved without keys; 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 the description and the keys against the provider without saving anything.
Click Save.

Your own REST provider is always called directly from the appliance, never through the sslbrain Cloud proxy. Changes to the description apply 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 script must be an executable file on the appliance, for example /data/dns-scripts/<name>.sh. The appliance’s web interface cannot put a file there, so the file is placed from the machine:

Virtual appliance: choose 9 Danger zone and then 1 Open a root shell in the console menu (the console menu), and put the file in /opt/sslbrain/data/dns-scripts/. The directory is /data 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.

The script is chosen as for RFC 2136 above, but with script under Executor adapter. The fields are Sti til operator-script and Script timeout (sekunder) (5 to 300, default 60). They 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. The test measures CNAME redirects only.
Your own REST provider: open the credential under Credentials and click Test access.
RFC 2136 and script: the page has no Test access for these two. Create the rule as in step 8, and check the Domain validation panel in the wizard.
All four methods: the Domain validation panel in the rule wizard shows for each name which method covers it. For a DNS API credential it says “Validated with the DNS API credential” and the credential’s name.

If issuance still fails, see Validation fails.