Sovrain
  1. Documentation
  2. Self-hosting

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 A records pointing to the node, and AAAA records 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 is sso.example.com.

Give Sovrain access to the zone

  1. 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
      
  2. 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; set IDP_TLS_OVH_ENDPOINT if your account uses another one. If the landing host is itself the zone, leave IDP_TLS_DNS_ZONE out.

  3. 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. Then watch it:

    docker logs -f sovrain
    docker exec sovrain curl -s http://localhost:8080/ready
    

    After a minute or two, /ready shows "nodeCertificate":true.

  4. 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 -enddate
    

    On the landing node the certificate names sso.example.com and *.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 seeCause
The node does not start: clouDnsAuthId must not be blank, ovhAppKey must not be blank or similarA 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 OVHThe 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 120sThe 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 recordIts 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.