In order to work properly, DNSroboCert requires a configuration file, which is written in YAML. To avoid any problem, you should create it before starting DNSroboCert (the file can be empty at this point).
The path of this file is configurable. We will assume in this user guide that it is
On Linux for instance, run:
mkdir /etc/dnsrobocert touch /etc/dnsrobocert/config.yml
DNSroboCert will store the certificates in a specific folder. Here also a good idea is to create it before starting DNSroboCert.
The path of this folder is configurable. We will assume in this user guide that it is
On Linux for instance, run:
mkdir -p /etc/letsencrypt
DNSroboCert can be installed in two ways:
- On the host using a python package manager
- As a Docker container
Installation on the host¶
- DNSroboCert requires Python 3.6+.
- It can be installed on Linux, Mac OS or Windows.
- For Linux and Mac OS, running as a privileged user (eg. root) is recommended.
- For Windows, running as a privileged user (eg. Administrator) is required.
The recommended way is to use Pipx, a tool that extends Pip and is specifically designed to install a Python program in a isolated and dedicated environment.
You need Python 3.6+ installed on your machine.
Install pipx using pip:
python3 -m pip install pipx python3 -m pipx ensurepath
Then install DNSroboCert on the desired version (eg.
python3 -m pipx install dnsrobocert==3.0.0
At this point DNSroboCert is installed and available in the
PATH. You can display the inline help using:
And run DNSroboCert with:
dnsrobocert -c /etc/dnsrobocert/config.yml -d /etc/letsencrypt
DNSroboCert will continue to run in the foreground. To stop it, press CTRL+C.
Running as a Docker container¶
An up-to-date Docker image is available in DockerHub. In order to persist DNSroboCert configuration and the generated certificates, you should mount its configuration and the dedicated folder for certificates from the host into the container.
- For the configuration file, expected path is
- For the certificates folder, expected path is
Both paths are configurable in the container through the environment variables
Finally you can run this typical command for the desired version (eg. 3.0.0):
docker run --rm --name dnsrobocert --volume /etc/dnsrobocert/config.yml:/etc/dnsrobocert/config.yml --volume /etc/letsencrypt:/etc/letsencrypt adferrand/dnsrobocert:3.0.0
The Docker container will continue to run in the foreground. To stop it, press CTRL+C.
DNSroboCert also work on Podman
This guide focuses only on the bare minimum to make use of DNSroboCert: create one or more certificates. For an advanced configuration, in order to use more of DNSroboCert capabilities, please have a look to the Configuration reference.
Configuring DNSroboCert consists in writing its unique configuration file (we assume its location at
/etc/dnsrobocert/config.yml). In particular 3 things need to be set up, and correspond to the 3
main sections of the configuration file:
acme, we define the Let’s Encrypt account that will be used to issue certificates
profiles, we describe the DNS credentials and the DNS provider associated to the DNS zone to fulfill DNS-01 challenges
- and finally in
certificates, we list the certificates that DNSroboCert will issue and regularly renew.
We can write the configuration file in draft mode: in this case, DNSroboCert will validate the configuration file, but will not do anything with it. This is quite suitable during the initial configuration phase.
So let’s start with a
config.yml whose content is:
Basically we need to decide which email will be associated to the Let’s Encrypt account. This email is used by Let’s Encrypt administrators to broadcast important messages, and particularly when your certificates are about to expire. This email is put in the acme.email_account property.
During DNSroboCert configuration, you will certainly want to test things without targeting the Let’s Encrypt
production servers, since these servers have certificate rate creation limits. This can be done by setting
true: in this case Let’s Encrypt staging servers will be used.
At this point, our
config.yml looks like this:
draft: true acme: email_account: email@example.com staging: true
It is time to set the credentials and other specific configuration entries for the DNS provider that is holding the DNS zone for the domains you want to include in your certificate. This constitute a so-called “profile” in DNSroboCert.
Please have a look to the Lexicon Providers configuration reference page to see what are the DNS providers supported by DNSroboCert (through the Lexicon tool), and what are the relevant configuration parameters for your provider.
We need to create a profile, and add it in the list holded by the
profiles property. This profile needs:
- a name, on the property
- the Lexicon provider, as defined in the Lexicon Providers configuration reference page,
on the property
- the provider options described in the aforementioned page for your provider, exposed as an object in the
profiles.provider_optionswhere each key is an option, and the value is the value option.
Typically a profile looks like the following:
profiles: - name: my_profile provider: a_provider provider_options: one_option: one_value another_option: another_value
We assume here that the
henet provider will be used. It requires two options:
Given the format for
profiles, our existing
config.yml and the use of
henet provider, our
configuration file will look like this now:
draft: true acme: email_account: firstname.lastname@example.org staging: true profiles: - name: henet_profile provider: henet provider_options: auth_username: USER auth_password: PASSWD
You can declare multiple profiles to use different providers and/or the same provider with different credentials.
Everything is ready to get the certificates. What you want as certificates is defined in the
section. It contains a list of each certificate you want. The bare minimum content for a certificate is:
- the profile name to use for DNS-01 challenges, set in the
- the list of domains to add in the certificate, to give as a list in the
Typically a certificate entry will looks like:
certificates: - domains: - one.example.net - two.example.net profile: my_profile
We assume here that the DNS zone is
example.net, and two certificates need to be created:
- a regular certificate for
- a wildcard certificate for
We will use the
henet_profile configured previously.
Given this situation, we add the certificate configurations to our
The configuration file looks like this now:
draft: true acme: email_account: email@example.com staging: true profiles: - name: henet_profile provider: henet provider_options: auth_username: USER auth_password: PASSWD certificates: - domains: - mail.example.net - ldap.example.net profile: henet_profile - domains: - "*.example.net" - example.net profile: henet_profile
Our configuration is now ready: we can disable the draft mode, by setting
draft parameter to
We continue to assume that the certificates will be generated in the
If DNSroboCert is already started, it will immediately proceed to issue and retrieve the certificates. If not, see the Installation section to start DNSroboCert.
After a minute, your certificates will be issued (have a look to the log output to check that). Your certificates
are available in the
/etc/letsencrypt folder and can be used. The layout of
the Certbot layout convention. So given our example here, you will find:
- the regular certificate for
- the wildcard certificate for
If you used the Let’s Encrypt staging servers to configure DNSroboCert, you can now go back to th
production servers to get real certificates: in
acme.staging value to
false. DNSroboCert will proceed immediately to replace the testing certificates by real certificates.
DNSroboCert check constantly for modifications in its configuration file. You can live edit it: DNSroboCert will proceed to issue new certificates as soon as you configuration file is written to the disk.
Let’s Encrypt certificates last only 3 months, and need to be renewed regularly. DNSroboCert includes this functionality: while it is running it will regularly (twice a day) check for certificate renewal, and proceed to all renewals if needed (this happens typically one month before the expiration of the current certificate).
Because of this regular renewal requirement, DNSroboCert should run constantly on your machine as a daemon.
The tool does not provide a specific daemon technology: the CLI will just constantly run on the foreground,
and reacts properly to the relevant exit signal codes like
SIGTERM. From that it is your reponsability
to daemonize DNSroboCert.
Here are some relevant ways depending on the context.
If you run DNSroboCert directly on the host (eg. you followed the Installation on the host section), one simple way is to define a systemd unit, and configure your Systemd to run DNSroboCert as a daemon at startup.
If you run DNSroboCert in a Docker container (eg. you followed the Running as a Docker container section), then Docker-Compose is a standard way to configure a Docker and ensure that is runs all the time as a daemon.
Create the following
version: '2' services: dnsrobocert: image: adferrand/dnsrobocert container_name: dnsrobocert volumes: - /etc/letsencrypt:/etc/letsencrypt - /etc/dnsrobocert:/etc/dnsrobocert restart: always
Then run it:
docker-compose up -d
At this point, your Docker container of DNSroboCert will be started and the Docker daemon will ensure it continues to run upon your machine restart.
Run DNSroboCert in “one-shot” mode¶
If the approach of DNSroboCert process running constantly does not fit your needs, you can also use the “one-shot” mode.
In this mode, DNSroboCert will process only once the provided configuration upon execution, then:
- create or update certificates if needed
- renew expired certificates
- delete certificates that do not match the current configuration
At the end it will exit immediately without setting up any config watch or automated renewal process: it will be up to you to execute DNSroboCert on a regular basis (preferably twice a day as recommended by Let’s Encrypt).
To use the “one-shot” mode, simply set the –one-shot flag to the command line. For instance:
dnsrobocert --config /path/to/config.yml --directory /path/to/letsencrypt --one-shot