Orchestrate Certbot and Lexicon together to provide Let's Encrypt TLS certificates validated by DNS challenges
|version| |python_support| |docker| |ci| |coverage| |spectrum|
.. |logo| image:: https://adferrand.github.io/dnsrobocert/images/dnsrobocert.svg :alt: DNSroboCert .. |version| image:: https://img.shields.io/pypi/v/dnsrobocert :target: https://pypi.org/project/dnsrobocert/ .. |pythonsupport| image:: https://img.shields.io/pypi/pyversions/dnsrobocert :target: https://pypi.org/project/dnsrobocert/ .. |docker| image:: https://img.shields.io/docker/image-size/adferrand/dnsrobocert :target: https://microbadger.com/images/adferrand/dnsrobocert .. |ci| image:: https://img.shields.io/azure-devops/build/adferrand/338d4cba-ab35-4cf9-a9c6-1d2601554b32/21/master :target: https://dev.azure.com/adferrand/dnsrobocert/build/latest?definitionId=21&branchName=master .. |coverage| image:: https://img.shields.io/azure-devops/coverage/adferrand/338d4cba-ab35-4cf9-a9c6-1d2601554b32/21 :target: https://dev.azure.com/adferrand/dnsrobocert/_build?definitionId=21&view=ms.vss-pipelineanalytics-web.new-build-definition-pipeline-analytics-view-cardmetrics .. |spectrum| image:: https://withspectrum.github.io/badge/badge.svg :target: https://spectrum.chat/dnsrobocert
.. contents:: Table of Contents :local:
DNSroboCert is designed to manage
Let's Encrypt_ SSL certificates based on
DNS alias mode_ (see the
follow_cnamesoption in the
.. DNS alias mode: https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode .. _certificate section: https://dnsrobocert.readthedocs.io/en/latest/configurationreference.html#certificate-properties
If you are reading these lines, you certainly want to secure all your services using Let's Encrypt SSL certificates, which are free and accepted everywhere.
If you want to secure Web services through HTTPS, there is already plenty of great tools. In the Docker world, one can check Traefik, or nginx-proxy + letsencrypt-nginx-proxy-companion_. Basically, theses tools will allow automated and dynamic generation/renewal of SSL certificates, based on TLS or HTTP challenges, on top of a reverse proxy to encrypt everything through HTTPS.
So far so good, but you may fall in one of the following categories:
For the first case, ACME servers need to be able to access your website through HTTP (for HTTP challenges) or HTTPS (for TLS challenges) in order to validate the certificate. With a firewall these two challenges - which are widely used in HTTP proxy approaches - will not be usable: you need to ask a DNS challenge. Please note that traefik embed DNS challenges, but only for few DNS providers.
For the second case, there is no website to use TLS or HTTP challenges, and you should ask a DNS challenge. Of course you could create a "fake" website to validate the domain using a HTTP challenge, and reuse the certificate on the "real" service. But it is a workaround, and you have to implement a logic to propagate the certificate, including during its renewal. Indeed, most of the non-Web services will need to be restarted each time the certificate is renewed.
For the last case, the use of a DNS challenge is mandatory. Then the problems concerning certificates propagation that have been discussed in the second case will also occur.
The solution is a dedicated and specialized tool which handles the creation/renewal of Let's Encrypt certificates, and ensure their propagation in the relevant services. It is the purpose of this project.
.. Let's Encrypt: https://letsencrypt.org/ .. _DNS challenges: https://tools.ietf.org/html/draft-ietf-acme-acme-01#page-44 .. _Certbot: https://github.com/certbot/certbot .. _Lexicon: https://github.com/AnalogJ/lexicon .. _Traefik: https://hub.docker.com//traefik/ .. _nginx-proxy: https://hub.docker.com/r/jwilder/nginx-proxy/ .. _letsencrypt-nginx-proxy-companion: https://hub.docker.com/r/jrcs/letsencrypt-nginx-proxy-companion/
Online documentation (user guide, configuration reference) is available in the
For a quick start, please have a look in particular at the
User guide_ and the
Lexicon provider configuration_.
Do not hesitate to join the
DNSroboCert community on Spectrum_ if you need help to use or develop DNSroboCert!
If you want to help in the DNSroboCert development, you are welcome! Please have a look at the
Developer guide_ page to know how to start.
.. DNSroboCert documentation: https://dnsrobocert.readthedocs.io .. _User guide: https://dnsrobocert.readthedocs.io/en/latest/userguide.html .. Lexicon provider configuration: https://dnsrobocert.readthedocs.io/en/latest/providersoptions.html .. Developer guide: https://dnsrobocert.readthedocs.io/en/latest/developerguide.html .. _DNSroboCert community on Spectrum: https://spectrum.chat/dnsrobocert