Configuration reference

DNSroboCert configuration is defined in a central file, usually located at/etc/dnsrobocert/config.yml.Its location is defined by the-c flag when running DNSroboCert locally with the CLI, or with theCONFIG_PATH environment variable with Docker.

File format

The configuration file must be a valid YAML and must conform to the JSON schema defined for DNSroboCert.One can find the raw content of this schema onGitHub. DNSroboCert will validate the file each time it is changed,and output the errors (missing properties, wrong value type) if any.

The basic structure is the following:

draft:falseacme:{}profiles:[]certificates:[]

draft Section

If the draft mode is enabled, DNSroboCert will validate dynamically the configuration file, but will notreconfigure itself with it and will not proceed to any further action. This is useful to make wide modificationsin the file without DNSroboCert taking them into account immediately, then apply all modifications altogetherby disabling the draft mode.

draft:true

acme Section

This section contains all general configuration parameters for Certbot (the underlying ACME client thatgenerates the certificates) and how these certificates are stored locally.

acme:email_account:my.email@example.netstaging:falseapi_version:2# If directory_url is set, values of staging and api_version are ignoreddirectory_url:https://example.net/dircerts_permissions:files_mode:0644dirs_mode:0755user:nobodygroup:nogroupcrontab_renew:12 01,13 * * *

email_account

  • The email account used to create an account against Let’s Encrypt

  • type:string

  • default:null (no registration is done, and so no certificate is issued if an account does not exist yet)

staging

  • Iftrue, Let’s Encrypt staging servers will be used (useful for testing purpose)

  • type:boolean

  • default:false

api_version

  • The ACME protocol version to use (deprecated1 or current2)

  • type:integer

  • default:2

directory_url

  • The ACME CA server to use

  • type:string representing a valid URL

  • default:null (ACME CA server URL is determined usingstaging andapi_version values)

certs_permissions

  • An object describing the files and directories permissions to apply on generated certificates

  • type:object

  • default:null (default permissions are applied: certificates are owned by the user/group running DNSroboCert,and are only accessible by this user/group)

files_mode

  • The permissions to apply to files, defined in POSIX octal notation

  • type:integer orstring defined in octal notation (eg.0644 or"0755")

  • default:0640

dirs_mode

  • The permissions to apply to directories, defined in POSIX octal notation

  • type:integer orstring defined in octal notation (eg.0755 or"0755")

  • default:0750

user

  • The user name or uid that should be owner of the certificates

  • type:integer (for a uid, eg.1000) orstring (for a user name, eg."myuser")

  • default:null (user running DNSroboCert will be owner of the certificates)

group

  • The group name or gid that should group owner of the certificates

  • type:integer (for a gid, eg.1000) orstring (for a user name, eg."mygroup")

  • default:null (group running DNSroboCert will group owner of the certificates)

crontab_renew

  • A cron pattern defining the frequency for certificates renewal check

  • type:string representing a valid cron pattern

  • default:1201,13*** (twice a day)

profiles Section

This section holdsa list of profiles. Each profile is anobject that describes thecredentials and specific configuration to apply to a DNS provider supported by Lexicon in orderto fulfill a DNS-01 challenge.

Each profile is referenced by itsname, which can be used in one or more certificates in thecertificates section. Multiple profiles can be defined for the same DNS provider. However, each profilename must be unique.

profiles:-name:my_profile1provider:digitaloceanprovider_options:auth_token:TOKENsleep_time:45max_checks:5-name:my_profile2provider:henetprovider_options:auth_username:USERauth_password:PASSWORD

name

  • The name of the profile, used to reference this profile in thecertificates section.

  • type:string

  • mandatory property

provider

  • Name of the DNS provider supported by Lexicon

  • type:string

  • mandatory property

provider_options

  • Anobject defining all properties to use for the DNS provider defined for this profile

  • type:object

  • default:null

Each property that should be added inprovider_option depends on the actual provider used.You can check all properties available for each provider in theLexicon Providers configuration reference page.As an example for Aliyun it will be:

provider_options:auth_key_id:MY_KEY_IDauth_secret:MY_SECRET

sleep_time

  • Time in seconds to wait after the TXT entries are inserted into the DNS zone to perform the DNS-01 challengeof a certificate

  • type:integer

  • default:30

max_checks

  • Maximum number of checks to verify that the TXT entries have been properly inserted into the DNS zone beforeperforming the DNS-01 challenge of a certificate. DNSroboCert will wait for the amount of time defined insleep_time between each check. Set to0 to disable these checks.

  • type: integer

  • default:0 (no check is done)

ttl

  • Time to live in seconds for the TXT entries inserted in the DNS zone during a DNS-01 challenge.

  • type:integer

  • default:null (use any default TTL value specific to the DNS provider associated to this profile)

dynamic_zone_resolution

  • Switch on/off the dynamic resolution of the actual zone for a given domain using live DNS requests. This isparticularly useful for zones that concerns non second-level domains (eg.sub.domain.net).If set toFalse, DNSRoboCert will rely on a static list of top level domains to guess second level domains:you would need the optiondelegated_subdomain to work with a third (or more) level domain. Disabling thedynamic zone resolution can be useful on environments where DNS responses are unreliable (eg. slow requestsor timeouts).

  • type:boolean

  • default:True (dynamic zone resolution is enabled by default)

delegated_subdomain

  • Ifdynamic_zone_resolution is set toFalse and you are working on a subdomain which has beendelegated to a specific zone (eg.sub.domain.net delegated fromdomain.net), this option allowsto explicitly set the actual domain of that zone (otherwise DNSRoboCert may assume the zone isdomain.netinstead ofsub.domain.net when dynamic zone resolution is not set).

  • type:boolean

  • default:null

certificates Section

This sections handles the actual certificates that DNSroboCert needs to generate and renew regularly.It takes the form ofa list of certificates. Each certificate is an object that describe the domainsthat needs to be included in the certificate, and the profile to use to handle the DNS-01 challenges: theprofile is referred by its name, andmust exist in theprofiles Section.

In parallel several actions can be defined when a certificate is created or renewed. These actions have tobe defined in each relevant certificate configuration.

certificates:-name:my-wildcard-certdomains:-"*.example.net"-example.netprofile:my_profile1pfx:export:truepassphrase:PASSPHRASEautorestart:-containers:-container1-swarm_services:-service1podman_containers:-podman1autocmd:-cmd:/usr/bin/remote_deploy.shcontainers:-container2-domains:-www.sub.example.netprofile:my_profile2deploy_hook:python /home/user/local_deploy.pyforce_renew:falsefollow_cnames:falsereuse_key:falsekey_type:ecdsa

profile

  • The profile name to use to validated DNS-01 challenges. This profile must exist in theprofilessection.

  • type:string

  • mandatory property

domains

  • List of the domains to include in the certificate.

  • type:list[string]

  • mandatory property

name

  • Name of the certificate, used in particular to define where the certificate assets (key, cert, chain…)will be stored on the filesystem. For a certificate namedmy-cert, files will be available in thedirectory whose path is[CERTS_PATH]/live/my-cert. If the name is not specified, the effectivecertificate name will be the first domain listed in thedomains property.

  • type:string

  • default:null (in this case name is extracted from the first domain listed indomains, forinstanceexample.net forexample.net or*.example.net)

pfx

  • Configure an export of the certificate into the PFX (also known as PKCS#12) format upon creation/renewal.

  • type:object

  • default:null (certificate is not exported in PFX format)

export

  • Iftrue, the certificate is exported in PFX format.

  • type:boolean

  • default:false (the certificate is not exported in PFX format)

passphrase

  • If set, the PFX file will be protected with the given passphrase.

  • type:string

  • default:null (the PFX file is not protected by a passphrase)

deploy_hook

  • A command hook to execute locally when the certificate is created/renewed.

  • type:string

  • default:null (no deploy hook is configured)

Note

Several additional environment variables are injected by DNSrobocCert in the commandruns bydeploy_hook:

  • DNSROBOCERT_CERTIFICATE_NAME: name of the current certificate in the configuration file,

  • DNSROBOCERT_CERTIFICATE_DOMAINS: comma-separated list of the domains for the current certificate,

  • DNSROBOCERT_CERTIFICATE_PROFILE: DNSroboCert profile associated with the current certificate.

force_renew

  • Iftrue, the certificate will be force renewed when DNSroboCert configuration changes. Usefulfor debugging purposes.

  • type:boolean

  • default:false (the certificate is not force renewed)

follow_cnames

  • Iftrue, DNSroboCert will follow the chain of CNAME that may be defined for the challengeDNS names_acme-challenge.DOMAIN (whereDOMAIN is the domain to validate and integratein the certificate). This allows to delegate the validation to another DNS zone for securitypurpose. See thislink for more details.

  • type:boolean

  • default:false (CNAME chain is not followed)

reuse_key

  • Iftrue, the existing private key will be reused during certificate renewal instead ofcreating a new one each time the certificate is renewed.

  • type:boolean

  • default:false (the private key is never reused for certificate renewal)

key_type

  • Type of key to use when the certificate is generated. Must bersa orecdsa.

  • type:string

  • default:rsa (a RSA-type key will be used)

Warning

The following paragraphs describe theautorestart andautocmd features. To allow them to work properly,DNSroboCert must have access to the Docker client socket file or the Podman socket. Usually at path:

  • /var/run/docker.sock for Docker,

  • /run/podman/podman.sock for rootful Podman,

  • /run/user/$UID/podman/podman.sock where $UID is your user id for rootless podman.

If DNSroboCert is run directly on the host, this usually requires to use a user with administrative privileges,or member of thedocker group.

If DNSroboCert is run as a Docker, you will need to mount the Docker client socket file into the container.As an example the following command does that:

$dockerrun--rm--namednsrobocert    --mount /var/run/docker.sock:/var/run/docker.sock    adferrand/dnsrobocert

If DNSroboCert is run as a Podman, you will need to mount the podman socket into the container.As an example the following command does that:

For rootless Podman:

$podmanrun--rm--namednsrobocert    --volume /run/user/$UID/podman/:/run/podman    docker.io/adferrand/dnsrobocert

For rootful Podman:

$sudopodmanrun--rm--namednsrobocert    --volume /run/podman/:/run/podman    docker.io/adferrand/dnsrobocert

autorestart

  • Configure an automated restart of target containers when the certificate is created/renewed. Thisproperty takes a list of autorestart configurations. Each autorestart is triggered in the orderthey have been inserted here.

  • type:list[object]

  • default:null (no automated restart is triggered)

containers

  • A list of Docker containers to restart.

  • type:list[string]

  • default:null (no containers to restart)

swarm_services

  • A list of swarm services to force restart

  • type:list[string]

  • default:null (no swarm services to restart)

podman_containers

  • A list of Podman containers to restart.

  • type:list[string]

  • default:null (no containers to restart)

Property configuration example

autorestart:-containers:-container1-container2swarm_services:-service1

autocmd

  • Configure an automated execution of an arbitrary command on target containers when the certificate isis created/renewed. This property takes a list of autocmd configurations. Each autocmd is triggeredin the order they have been inserted here.

  • type:list[object]

  • default:null (no automated command is triggered)

cmd

  • The command to execute in each target container. Only commands of string type will be executed in a shell.

  • type:string orlist[string]

  • Mandatory property

containers

  • A list of Docker containers on which the command will be executed.

  • type:list[string]

  • default:null (no containers to restart)

Property configuration example

autocmd:-containers:-container1-container2cmd:[echo,"HelloWorld!"]-containers:-container3cmd:env

Warning

The featureautocmd is intended to call a simple executable file with few potential arguments.It is not made to call some advanced bash script, and would likely fail if you do so. In fact, the commandis not executed in a shell on the target, and variables would be resolved against the DNSroboCert containerenvironment. If you want to operate advanced scripting, put an executable script in the target container,and use its path in the relevantautocmd[].cmd property.

Environment variables

You can inject environment variables in the configuration file using the${MY_VARIABLE} format.

For instance, given that an environment variable namedAUTH_TOKEN with the valuemy-secret-token exists,you can write the following file configuration content:

profiles:-name:my_profileprovider:digitaloceanprovider_options:auth_token:${AUTH_TOKEN}certificates:[]

Then it will be resolved as:

profiles:-name:my_profileprovider:digitaloceanprovider_options:auth_token:my-secret-tokencertificates:[]

Non-existent variables declared in the configuration file will raise an error.

Note

If you want to write a literal${NOT_A_VARIABLE} that should not be resolved, you can escape the${}syntax by prepending a second dollar sign like so:$${NOT_A_VARIABLE}.