======
|logo|
======
|version| |python_support| |docker| |ci| |coverage|
.. |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/
.. |python_support| image:: https://img.shields.io/pypi/pyversions/dnsrobocert
:target: https://pypi.org/project/dnsrobocert/
.. |docker| image:: https://img.shields.io/docker/pulls/adferrand/dnsrobocert
:target: https://hub.docker.com/r/adferrand/dnsrobocert
.. |ci| image:: https://img.shields.io/github/actions/workflow/status/adferrand/dnsrobocert/main.yml?branch=master
:target: https://github.com/adferrand/dnsrobocert/actions/workflows/main.yml
.. |coverage| image:: https://img.shields.io/codecov/c/github/adferrand/dnsrobocert/master
:target: https://app.codecov.io/gh/adferrand/dnsrobocert/branch/master
.. tag:intro-begin
.. contents:: Table of Contents
:local:
Features
========
DNSroboCert is designed to manage `Let's Encrypt`_ SSL certificates based on `DNS challenges`_.
* Let's Encrypt wildcard and regular certificates generation by Certbot_ using DNS challenges,
* Integrated automated renewal of almost expired certificates,
* Standardized API through Lexicon_ library to insert the DNS challenge with various DNS providers,
* Centralized YAML configuration file to maintain several certificates and several DNS providers
with configuration validity control,
* Modification of container configuration without restart,
* Flexible hooks upon certificate creation/renewal including containers restart, commands in containers
or custom hooks,
* Support for `DNS alias mode`_ (see the ``follow_cnames`` option in the `certificate section`_),
* Linux, Mac OS X and Windows support, with a particular care for Docker services,
* Delivered as a standalone application and a Docker image.
.. _DNS alias mode: https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode
.. _certificate section: https://dnsrobocert.readthedocs.io/en/latest/configuration_reference.html#certificate-properties
Why use DNSroboCert
===================
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:
1. You are in a firewalled network, and your HTTP/80 and HTTPS/443 ports are not opened to the outside world.
2. You want to secure non-Web services (like LDAP, IMAP, POP, etc.) were the HTTPS protocol is of no use.
3. You want to generate a wildcard certificate, valid for any sub-domain of a given domain.
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/
.. tag:intro-end
Documentation
=============
Online documentation (user guide, configuration reference) is available in the `DNSroboCert documentation`_.
For a quick start, please have a look in particular at the `User guide`_ and the `Lexicon provider configuration`_.
Support
=======
Do not hesitate to join the `DNSroboCert community on Github Discussions`_ if you need help to use or develop DNSroboCert!
Contributing
============
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/user_guide.html
.. _Lexicon provider configuration: https://dnsrobocert.readthedocs.io/en/latest/providers_options.html
.. _Developer guide: https://dnsrobocert.readthedocs.io/en/latest/developer_guide.html
.. _DNSroboCert community on Github Discussions: https://github.com/adferrand/dnsrobocert/discussions
Raw data
{
"_id": null,
"home_page": "https://dnsrobocert.readthedocs.io",
"name": "dnsrobocert",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "dnsrobocert",
"author": "Adrien Ferrand",
"author_email": "ferrand.ad@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/85/2a/bf24b7888b5be61a7ffcfb75d426f05f9a11f3a3262a12887d546943b70f/dnsrobocert-3.25.0.tar.gz",
"platform": null,
"description": "======\n|logo|\n======\n\n|version| |python_support| |docker| |ci| |coverage|\n\n.. |logo| image:: https://adferrand.github.io/dnsrobocert/images/dnsrobocert.svg\n :alt: DNSroboCert\n.. |version| image:: https://img.shields.io/pypi/v/dnsrobocert\n :target: https://pypi.org/project/dnsrobocert/\n.. |python_support| image:: https://img.shields.io/pypi/pyversions/dnsrobocert\n :target: https://pypi.org/project/dnsrobocert/\n.. |docker| image:: https://img.shields.io/docker/pulls/adferrand/dnsrobocert\n :target: https://hub.docker.com/r/adferrand/dnsrobocert\n.. |ci| image:: https://img.shields.io/github/actions/workflow/status/adferrand/dnsrobocert/main.yml?branch=master\n :target: https://github.com/adferrand/dnsrobocert/actions/workflows/main.yml\n.. |coverage| image:: https://img.shields.io/codecov/c/github/adferrand/dnsrobocert/master\n :target: https://app.codecov.io/gh/adferrand/dnsrobocert/branch/master\n\n.. tag:intro-begin\n\n.. contents:: Table of Contents\n :local:\n\nFeatures\n========\n\nDNSroboCert is designed to manage `Let's Encrypt`_ SSL certificates based on `DNS challenges`_.\n\n* Let's Encrypt wildcard and regular certificates generation by Certbot_ using DNS challenges,\n* Integrated automated renewal of almost expired certificates,\n* Standardized API through Lexicon_ library to insert the DNS challenge with various DNS providers,\n* Centralized YAML configuration file to maintain several certificates and several DNS providers\n with configuration validity control,\n* Modification of container configuration without restart,\n* Flexible hooks upon certificate creation/renewal including containers restart, commands in containers\n or custom hooks,\n* Support for `DNS alias mode`_ (see the ``follow_cnames`` option in the `certificate section`_),\n* Linux, Mac OS X and Windows support, with a particular care for Docker services,\n* Delivered as a standalone application and a Docker image.\n\n.. _DNS alias mode: https://github.com/acmesh-official/acme.sh/wiki/DNS-alias-mode\n.. _certificate section: https://dnsrobocert.readthedocs.io/en/latest/configuration_reference.html#certificate-properties\n\nWhy use DNSroboCert\n===================\n\nIf you are reading these lines, you certainly want to secure all your services using Let's Encrypt SSL\ncertificates, which are free and accepted everywhere.\n\nIf you want to secure Web services through HTTPS, there is already plenty of great tools. In the Docker\nworld, one can check Traefik_, or nginx-proxy_ + letsencrypt-nginx-proxy-companion_. Basically, theses tools\nwill allow automated and dynamic generation/renewal of SSL certificates, based on TLS or HTTP challenges,\non top of a reverse proxy to encrypt everything through HTTPS.\n\nSo far so good, but you may fall in one of the following categories:\n\n1. You are in a firewalled network, and your HTTP/80 and HTTPS/443 ports are not opened to the outside world.\n2. You want to secure non-Web services (like LDAP, IMAP, POP, etc.) were the HTTPS protocol is of no use.\n3. You want to generate a wildcard certificate, valid for any sub-domain of a given domain.\n\nFor the first case, ACME servers need to be able to access your website through HTTP (for HTTP challenges)\nor HTTPS (for TLS challenges) in order to validate the certificate. With a firewall these two challenges -\nwhich are widely used in HTTP proxy approaches - will not be usable: you need to ask a DNS challenge.\nPlease note that traefik embed DNS challenges, but only for few DNS providers.\n\nFor the second case, there is no website to use TLS or HTTP challenges, and you should ask a DNS challenge.\nOf course you could create a \"fake\" website to validate the domain using a HTTP challenge, and reuse the\ncertificate on the \"real\" service. But it is a workaround, and you have to implement a logic to propagate\nthe certificate, including during its renewal. Indeed, most of the non-Web services will need to be\nrestarted each time the certificate is renewed.\n\nFor the last case, the use of a DNS challenge is mandatory. Then the problems concerning certificates\npropagation that have been discussed in the second case will also occur.\n\nThe solution is a dedicated and specialized tool which handles the creation/renewal of Let's Encrypt\ncertificates, and ensure their propagation in the relevant services. It is the purpose of\nthis project.\n\n.. _Let's Encrypt: https://letsencrypt.org/\n.. _DNS challenges: https://tools.ietf.org/html/draft-ietf-acme-acme-01#page-44\n.. _Certbot: https://github.com/certbot/certbot\n.. _Lexicon: https://github.com/AnalogJ/lexicon\n.. _Traefik: https://hub.docker.com/_/traefik/\n.. _nginx-proxy: https://hub.docker.com/r/jwilder/nginx-proxy/\n.. _letsencrypt-nginx-proxy-companion: https://hub.docker.com/r/jrcs/letsencrypt-nginx-proxy-companion/\n\n.. tag:intro-end\n\nDocumentation\n=============\n\nOnline documentation (user guide, configuration reference) is available in the `DNSroboCert documentation`_.\n\nFor a quick start, please have a look in particular at the `User guide`_ and the `Lexicon provider configuration`_.\n\nSupport\n=======\n\nDo not hesitate to join the `DNSroboCert community on Github Discussions`_ if you need help to use or develop DNSroboCert!\n\nContributing\n============\n\nIf you want to help in the DNSroboCert development, you are welcome!\nPlease have a look at the `Developer guide`_ page to know how to start.\n\n.. _DNSroboCert documentation: https://dnsrobocert.readthedocs.io\n.. _User guide: https://dnsrobocert.readthedocs.io/en/latest/user_guide.html\n.. _Lexicon provider configuration: https://dnsrobocert.readthedocs.io/en/latest/providers_options.html\n.. _Developer guide: https://dnsrobocert.readthedocs.io/en/latest/developer_guide.html\n.. _DNSroboCert community on Github Discussions: https://github.com/adferrand/dnsrobocert/discussions\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to manage your DNS-challenged TLS certificates",
"version": "3.25.0",
"project_urls": {
"Homepage": "https://dnsrobocert.readthedocs.io",
"Repository": "https://github.com/adferrand/dnsrobocert"
},
"split_keywords": [
"dnsrobocert"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6749c88d55383a13964a273b4ee02adf0c455aadb97fd85c3776e54d0d5e17c2",
"md5": "2b2e9ff3e12051eda7fcfd91625c677f",
"sha256": "cbf11e205d9b2c78a1310d101c0a65252b0bea0382c62b15165159d5920d0de2"
},
"downloads": -1,
"filename": "dnsrobocert-3.25.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b2e9ff3e12051eda7fcfd91625c677f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 21217,
"upload_time": "2023-11-16T22:59:10",
"upload_time_iso_8601": "2023-11-16T22:59:10.584069Z",
"url": "https://files.pythonhosted.org/packages/67/49/c88d55383a13964a273b4ee02adf0c455aadb97fd85c3776e54d0d5e17c2/dnsrobocert-3.25.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "852abf24b7888b5be61a7ffcfb75d426f05f9a11f3a3262a12887d546943b70f",
"md5": "fb4bc3bd945d5e978def8531a73f23cc",
"sha256": "9dae5dda73f9ead688fbd005bfd820604234206d99372f2d778246de3b86a8ae"
},
"downloads": -1,
"filename": "dnsrobocert-3.25.0.tar.gz",
"has_sig": false,
"md5_digest": "fb4bc3bd945d5e978def8531a73f23cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 19384,
"upload_time": "2023-11-16T22:59:12",
"upload_time_iso_8601": "2023-11-16T22:59:12.344139Z",
"url": "https://files.pythonhosted.org/packages/85/2a/bf24b7888b5be61a7ffcfb75d426f05f9a11f3a3262a12887d546943b70f/dnsrobocert-3.25.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-16 22:59:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adferrand",
"github_project": "dnsrobocert",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "dnsrobocert"
}
JSON
