How-to guide
Set up TLS with DNS
Give Sovrain API access to your DNS zone at ClouDNS or OVH so that it issues and renews its own certificates.
This guide gives a Sovrain node what it needs to get and renew its TLS certificates by itself: API access to your DNS zone at ClouDNS or OVH. Sovrain uses the ACME DNS-01 challenge with Let’s Encrypt by default, and it uses the same access to publish the address of every new organization.
Sovrain has no other way to get a certificate. It does not use the HTTP-01 or TLS-ALPN-01 challenges, it cannot load
a certificate you bring, and it supports no DNS provider other than ClouDNS and OVH. A node with the prod profile
does not start while a credential of the chosen provider is empty; with wrong credentials it starts but /ready
answers 503.
Before you start
- The landing host and the region host have
Arecords pointing to the node, andAAAArecords only if the container network has IPv6 enabled, as in Run Sovrain with Docker. - You know which zone holds the landing host. In the examples it is
example.com, and the landing host issso.example.com.
Give Sovrain access to the zone
Create API credentials at your provider.
ClouDNS: create an API sub-user and give it the zone. If you use the main API user instead, also set
IDP_TLS_CLOUDNS_AUTH_KIND=AUTH_ID.OVH: create an application key and secret, and a consumer key with these rights on your zone:
GET /domain/zone/example.com/record GET /domain/zone/example.com/record/* POST /domain/zone/example.com/record DELETE /domain/zone/example.com/record/* POST /domain/zone/example.com/refresh
Add the settings to the node’s environment file.
For ClouDNS:
IDP_TLS_DNS_PROVIDER=cloudns IDP_TLS_DNS_ZONE=example.com IDP_TLS_CLOUDNS_AUTH_ID=<sub-user id> IDP_TLS_CLOUDNS_PASSWORD=<sub-user password>For OVH:
IDP_TLS_DNS_PROVIDER=ovh IDP_TLS_DNS_ZONE=example.com IDP_TLS_OVH_APP_KEY=<application key> IDP_TLS_OVH_APP_SECRET=<application secret> IDP_TLS_OVH_CONSUMER_KEY=<consumer key>The OVH endpoint defaults to
https://eu.api.ovh.com/1.0; setIDP_TLS_OVH_ENDPOINTif your account uses another one. If the landing host is itself the zone, leaveIDP_TLS_DNS_ZONEout.Recreate the container so it reads the new environment file:
docker stop --time 60 sovrain && docker rm sovrain, then run the samedocker runcommand as in Run Sovrain with Docker.docker restartkeeps the old values. Then watch it:docker logs -f sovrain docker exec sovrain curl -s http://localhost:8080/readyAfter a minute or two,
/readyshows"nodeCertificate":true.Check the certificate from outside:
openssl s_client -connect sso.example.com:443 -servername acme.sso.example.com </dev/null 2>/dev/null \ | openssl x509 -noout -subject -ext subjectAltName -enddateOn the landing node the certificate names
sso.example.comand*.sso.example.com. A node in another region names only*.sso.example.com.
From then on Sovrain renews its certificates by itself; you do nothing more. When and how it renews, and how it gets certificates for organizations’ own domains: Certificates.
If you want to try the setup first
Let’s Encrypt limits how many certificates a domain can get in a week. To test without using that up, point the node at the Let’s Encrypt staging directory. Browsers do not trust staging certificates, so remove the setting again before real people use the node.
IDP_TLS_ACME_DIRECTORY=https://acme-staging-v02.api.letsencrypt.org/directory
After you add or remove the setting, recreate the container so it reads the new environment file:
docker stop --time 60 sovrain && docker rm sovrain, then run the same docker run command as in
Run Sovrain with Docker. docker restart keeps the old values.
If it does not work
| You see | Cause |
|---|---|
The node does not start: clouDnsAuthId must not be blank, ovhAppKey must not be blank or similar | A credential of the chosen provider is missing |
The node does not start: landingHost sso.example.com is not inside dnsZone … | IDP_TLS_DNS_ZONE is not the zone of the landing host or a zone above it |
/ready answers 503 with an error from ClouDNS or OVH | The credentials lack a right on the zone, or the zone name is wrong |
The log says TXT _acme-challenge.sso.example.com did not show values … within 120s | The container cannot query the zone’s nameservers (it needs outgoing DNS on port 53), or they did not serve the new record within 2 minutes |
Let’s Encrypt reports that it found no matching TXT record | Its resolvers still saw an old answer; raise IDP_TLS_DNS_SETTLE_DELAY, for example to 120s |
All TLS settings: Server configuration. Why Sovrain gets its certificates only this way: About running Sovrain yourself.