Domains without a DNS API
Copy link to the page “Domains without a DNS API”Prepare your domain without an API key for your DNS.
Your domain is with a provider without a DNS API
Copy link to the section “Your domain is with a provider without a DNS API”AutoDNS (CNAME) works with every DNS provider. You create a permanent CNAME record, and validation runs through sslbrain Cloud (EU).
What you need
Copy link to the section “What you need”- The names the certificate should cover.
- Access to create DNS records at the provider.
Create the permanent DNS record
Copy link to the section “Create the permanent DNS record”-
Open Issuance › Domains and click Make ready beside the domain.
-
Copy the displayed CNAME record to your DNS. Use one record per name; the domain and its wildcard use the same record. See the name and value in step 6.
-
Enter the names in the domain test and click Check domain. Leave the CNAME record in place for renewals.
Check that it works
Copy link to the section “Check that it works”The domain test shows Ready for a certificate. You can now choose a certificate source and create the installation plan.
If it fails
Copy link to the section “If it fails”- The test shows a wrong or missing CNAME → correct the record using the value under Make ready. See troubleshooting in step 6.
- The appliance cannot reach sslbrain Cloud → check the connection under first-time setup.
- You need to change records on your own DNS server → use the details for your own DNS server below.
- A DNS-API credential fails → open it under Servers › Credentials. Use Test access for a REST provider. RFC 2136 and scripts are tested during issuance; read the result in the run under Installation plans › Runs.
When you want to update your own DNS server
Copy link to the section “When you want to update your own DNS server”A DNS server such as BIND can be updated with nsupdate using RFC 2136. The appliance must be able to reach the server. The TSIG key needs permission to create and delete validation records, and a public CA must be able to read them in public DNS.
The creation form only shows built-in providers. An owner opens Issuance › Domains › DNS providers › Add DNS provider, gives the credential a Name, selects Hetzner DNS and enters a temporary value in Hetzner DNS API Token. Click Test and save, then Save anyway when the test fails.
Open the credential under Servers › Credentials. Select native (RFC 2136 nsupdate) under Executor adapter, fill in the fields below and Zone bindings (one per line), then click Save. This adapter does not use the temporary token.
| Field | Content |
|---|---|
| Name server (server) | The DNS server’s name or address |
| Zone | The zone, such as example.com |
| TSIG algorithm | For example hmac-sha256, the default |
| TTL (seconds) | 5 to 86400, default 60 |
| Username | The TSIG key name |
| Password / Key | The TSIG key’s base64 secret |
When your provider has an API that is missing from the list
Copy link to the section “When your provider has an API that is missing from the list”An owner gives the credential a Name and selects New custom REST DNS provider… under DNS provider in the creation form. Use the provider’s API documentation to fill in the fields:
| Section | What to describe |
|---|---|
| Provider | Name, description and an HTTPS base URL at a public address |
| Authentication | Auth type and its headers or query parameters |
| Zones | Zone list path and JSON paths for the list, zone ID and zone name |
| Create record | Method, path, JSON body and TTL |
| Delete record | One DELETE call with the record ID, or an ID lookup before deletion |
Paths and bodies can use {zone_id}, {zone}, {name}, {fqdn}, {type}, {value} and {ttl}. Deletion can also use {record_id}. Write JSON paths with dots, such as data.records. Fill in the credentials, use Test access and click Save.
The appliance calls the provider API directly. Changes to the description apply to every credential using it.
When validation needs a script
Copy link to the section “When validation needs a script”Place an executable script in /data/dns-scripts/ on the appliance. On a virtual appliance, the host directory is /opt/sslbrain/data/dns-scripts/; files can be placed there through the console’s root shell. With Docker, use the directory on the volume mounted as /data. Run chmod 755 on the file.
Create the credential as described for RFC 2136. Then select script under Executor adapter and fill in Path to operator script. The timeout defaults to 60 seconds and can be set from 5 to 300 seconds.
| Environment variable | Content |
|---|---|
SSLBRAIN_DNS_ACTION | create or remove |
SSLBRAIN_DNS_RECORD_NAME | Record name |
SSLBRAIN_DNS_RECORD_TYPE | Record type |
SSLBRAIN_DNS_RECORD_VALUE | Record value |
SSLBRAIN_DNS_FQDN | Name being validated |
SSLBRAIN_DNS_AUTODNS_TARGET | Appliance CNAME target |
SSLBRAIN_DNS_REQUIREMENT_ID | Validation ID when present |
SSLBRAIN_DNS_USERNAME | Username from the credential |
SSLBRAIN_DNS_SECRET_FILE | File containing the secret, with permissions 0600 |
Exit code 0 means completed, 2 means completed with a warning, and all other codes mean failure. The secret is supplied through the file and does not appear on the command line.