diff --git a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py index f4820e1ca..7e53f83ce 100644 --- a/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py +++ b/certbot-dns-cloudflare/certbot_dns_cloudflare/__init__.py @@ -1 +1,86 @@ -"""Cloudflare DNS Authenticator""" +""" +The `~certbot_dns_cloudflare.dns_cloudflare` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the Cloudflare API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-cloudflare-credentials`` Cloudflare credentials_ INI file. + (Required) +``--dns-cloudflare-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 10) +======================================== ===================================== + + +Credentials +----------- + +Use of this plugin requires a configuration file containing Cloudflare API +credentials, obtained from your Cloudflare +`account page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # Cloudflare API credentials used by Certbot + dns_cloudflare_email = cloudflare@example.com + dns_cloudflare_api_key = 0123456789abcdef0123456789abcdef01234567 + +The path to this file can be provided interactively or using the +``--dns-cloudflare-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + Cloudflare account. Users who can read this file can use these credentials + to issue arbitrary API calls on your behalf. Users who can cause Certbot to + run using these credentials can complete a ``dns-01`` challenge to acquire + new certificates or revoke existing certificates for associated domains, + even if those domains aren't being managed by this server. + +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-cloudflare \\ + --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-cloudflare \\ + --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-cloudflare \\ + --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini \\ + --dns-cloudflare-propagation-seconds 60 \\ + -d example.com + +""" diff --git a/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst b/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst index 939d4c0b4..35f525201 100644 --- a/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst +++ b/certbot-dns-cloudflare/docs/api/dns_cloudflare.rst @@ -1,5 +1,5 @@ :mod:`certbot_dns_cloudflare.dns_cloudflare` --------------------------------------- +-------------------------------------------- .. automodule:: certbot_dns_cloudflare.dns_cloudflare :members: diff --git a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py index 8df02d0fa..6ddbdfe5a 100644 --- a/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py +++ b/certbot-dns-cloudxns/certbot_dns_cloudxns/__init__.py @@ -1 +1,86 @@ -"""CloudXNS DNS Authenticator""" +""" +The `~certbot_dns_cloudxns.dns_cloudxns` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the CloudXNS API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-cloudxns-credentials`` CloudXNS credentials_ INI file. + (Required) +``--dns-cloudxns-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 30) +======================================== ===================================== + + +Credentials +----------- + +Use of this plugin requires a configuration file containing CloudXNS API +credentials, obtained from your CloudXNS +`API page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # CloudXNS API credentials used by Certbot + dns_cloudxns_api_key = 1234567890abcdef1234567890abcdef + dns_cloudxns_secret_key = 1122334455667788 + +The path to this file can be provided interactively or using the +``--dns-cloudxns-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + CloudXNS account. Users who can read this file can use these credentials to + issue arbitrary API calls on your behalf. Users who can cause Certbot to run + using these credentials can complete a ``dns-01`` challenge to acquire new + certificates or revoke existing certificates for associated domains, even if + those domains aren't being managed by this server. + +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-cloudxns \\ + --dns-cloudxns-credentials ~/.secrets/certbot/cloudxns.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-cloudxns \\ + --dns-cloudxns-credentials ~/.secrets/certbot/cloudxns.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-cloudxns \\ + --dns-cloudxns-credentials ~/.secrets/certbot/cloudxns.ini \\ + --dns-cloudxns-propagation-seconds 60 \\ + -d example.com + +""" diff --git a/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py b/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py index 40b2527f8..3ab8df041 100644 --- a/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py +++ b/certbot-dns-digitalocean/certbot_dns_digitalocean/__init__.py @@ -1 +1,86 @@ -"""DigitalOcean DNS Authenticator""" +""" +The `~certbot_dns_digitalocean.dns_digitalocean` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the DigitalOcean API. + + +Named Arguments +--------------- + +========================================== =================================== +``--dns-digitalocean-credentials`` DigitalOcean credentials_ INI file. + (Required) +``--dns-digitalocean-propagation-seconds`` The number of seconds to wait for + DNS to propagate before asking the + ACME server to verify the DNS + record. + (Default: 10) +========================================== =================================== + + +Credentials +----------- + +Use of this plugin requires a configuration file containing DigitalOcean API +credentials, obtained from your DigitalOcean account's `Applications & API +Tokens page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # DigitalOcean API credentials used by Certbot + dns_digitalocean_token = 0000111122223333444455556666777788889999aaaabbbbccccddddeeeeffff + +The path to this file can be provided interactively or using the +``--dns-digitalocean-credentials`` command-line argument. Certbot records the +path to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + DigitalOcean account. Users who can read this file can use these credentials + to issue arbitrary API calls on your behalf. Users who can cause Certbot to + run using these credentials can complete a ``dns-01`` challenge to acquire + new certificates or revoke existing certificates for associated domains, + even if those domains aren't being managed by this server. + +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-digitalocean \\ + --dns-digitalocean-credentials ~/.secrets/certbot/digitalocean.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-digitalocean \\ + --dns-digitalocean-credentials ~/.secrets/certbot/digitalocean.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-digitalocean \\ + --dns-digitalocean-credentials ~/.secrets/certbot/digitalocean.ini \\ + --dns-digitalocean-propagation-seconds 60 \\ + -d example.com + +""" diff --git a/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py b/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py index 1d6747249..f8a2e83aa 100644 --- a/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py +++ b/certbot-dns-dnsimple/certbot_dns_dnsimple/__init__.py @@ -1 +1,85 @@ -"""DNSimple DNS Authenticator""" +""" +The `~certbot_dns_dnsimple.dns_dnsimple` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the DNSimple API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-dnsimple-credentials`` DNSimple credentials_ INI file. + (Required) +``--dns-dnsimple-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 30) +======================================== ===================================== + + +Credentials +----------- + +Use of this plugin requires a configuration file containing DNSimple API +credentials, obtained from your DNSimple +`account page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # DNSimple API credentials used by Certbot + dns_dnsimple_token = MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAw + +The path to this file can be provided interactively or using the +``--dns-dnsimple-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + DNSimple account. Users who can read this file can use these credentials + to issue arbitrary API calls on your behalf. Users who can cause Certbot to + run using these credentials can complete a ``dns-01`` challenge to acquire + new certificates or revoke existing certificates for associated domains, + even if those domains aren't being managed by this server. + +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-dnsimple \\ + --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-dnsimple \\ + --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-dnsimple \\ + --dns-dnsimple-credentials ~/.secrets/certbot/dnsimple.ini \\ + --dns-dnsimple-propagation-seconds 60 \\ + -d example.com + +""" diff --git a/certbot-dns-google/certbot_dns_google/__init__.py b/certbot-dns-google/certbot_dns_google/__init__.py index 9e9096d83..26685206c 100644 --- a/certbot-dns-google/certbot_dns_google/__init__.py +++ b/certbot-dns-google/certbot_dns_google/__init__.py @@ -1 +1,98 @@ -"""Google Cloud DNS Authenticator""" +""" +The `~certbot_dns_google.dns_google` plugin automates the process of +completing a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and +subsequently removing, TXT records using the Google Cloud DNS API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-google-credentials`` Google Cloud Platform credentials_ + JSON file. + (Required) +``--dns-google-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 60) +======================================== ===================================== + + +Credentials +----------- + +Use of this plugin requires a configuration file containing Google Cloud +Platform API credentials for an account with the following permissions: + +* ``dns.changes.create`` +* ``dns.changes.get`` +* ``dns.managedZones.list`` +* ``dns.resourceRecordSets.create`` +* ``dns.resourceRecordSets.delete`` + +Google provides instructions for `creating a service account `_ and +`information about the required permissions `_. + +.. code-block:: json + :name: credentials.json + :caption: Example credentials file: + + { + "type": "service_account", + ... + } + +The path to this file can be provided interactively or using the +``--dns-google-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would a password. Users who + can read this file can use these credentials to issue some types of API calls + on your behalf, limited by the permissions assigned to the account. Users who + can cause Certbot to run using these credentials can complete a ``dns-01`` + challenge to acquire new certificates or revoke existing certificates for + domains these credentials are authorized to manage. + +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-google \\ + --dns-google-credentials ~/.secrets/certbot/google.json \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-google \\ + --dns-google-credentials ~/.secrets/certbot/google.json \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 120 seconds + for DNS propagation + + certbot certonly \\ + --dns-google \\ + --dns-google-credentials ~/.secrets/certbot/google.ini \\ + --dns-google-propagation-seconds 120 \\ + -d example.com + +""" diff --git a/certbot-dns-google/docs/_ext/jsonlexer.py b/certbot-dns-google/docs/_ext/jsonlexer.py new file mode 100644 index 000000000..1ad004d2b --- /dev/null +++ b/certbot-dns-google/docs/_ext/jsonlexer.py @@ -0,0 +1,16 @@ +"""Copied from https://stackoverflow.com/a/16863232""" + +def setup(app): + # enable Pygments json lexer + try: + import pygments + if pygments.__version__ >= '1.5': + # use JSON lexer included in recent versions of Pygments + from pygments.lexers import JsonLexer + else: + # use JSON lexer from pygments-json if installed + from pygson.json_lexer import JSONLexer as JsonLexer + except ImportError: + pass # not fatal if we have old (or no) Pygments and no pygments-json + else: + app.add_lexer('json', JsonLexer()) diff --git a/certbot-dns-google/docs/conf.py b/certbot-dns-google/docs/conf.py index 4ff1af1d1..bbb343ee8 100644 --- a/certbot-dns-google/docs/conf.py +++ b/certbot-dns-google/docs/conf.py @@ -17,8 +17,8 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import sys +sys.path.insert(0, os.path.abspath('_ext')) # -- General configuration ------------------------------------------------ @@ -34,7 +34,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.viewcode'] + 'sphinx.ext.viewcode', + 'jsonlexer'] autodoc_member_order = 'bysource' autodoc_default_flags = ['show-inheritance', 'private-members'] diff --git a/certbot-dns-nsone/certbot_dns_nsone/__init__.py b/certbot-dns-nsone/certbot_dns_nsone/__init__.py index 8c061edf7..e59be74a7 100644 --- a/certbot-dns-nsone/certbot_dns_nsone/__init__.py +++ b/certbot-dns-nsone/certbot_dns_nsone/__init__.py @@ -1 +1,85 @@ -"""NS1 DNS Authenticator""" +""" +The `~certbot_dns_nsone.dns_nsone` plugin automates the process of completing +a ``dns-01`` challenge (`~acme.challenges.DNS01`) by creating, and subsequently +removing, TXT records using the NS1 API. + + +Named Arguments +--------------- + +======================================== ===================================== +``--dns-nsone-credentials`` NS1 credentials_ INI file. + (Required) +``--dns-nsone-propagation-seconds`` The number of seconds to wait for DNS + to propagate before asking the ACME + server to verify the DNS record. + (Default: 30) +======================================== ===================================== + + +Credentials +----------- + +Use of this plugin requires a configuration file containing NS1 API credentials, +obtained from your NS1 +`account page `_. + +.. code-block:: ini + :name: credentials.ini + :caption: Example credentials file: + + # NS1 API credentials used by Certbot + dns_nsone_api_key = MDAwMDAwMDAwMDAwMDAw + +The path to this file can be provided interactively or using the +``--dns-nsone-credentials`` command-line argument. Certbot records the path +to this file for use during renewal, but does not store the file's contents. + +.. caution:: + You should protect these API credentials as you would the password to your + NS1 account. Users who can read this file can use these credentials to issue + arbitrary API calls on your behalf. Users who can cause Certbot to run using + these credentials can complete a ``dns-01`` challenge to acquire new + certificates or revoke existing certificates for associated domains, even if + those domains aren't being managed by this server. + +Certbot will emit a warning if it detects that the credentials file can be +accessed by other users on your system. The warning reads "Unsafe permissions +on credentials configuration file", followed by the path to the credentials +file. This warning will be emitted each time Certbot uses the credentials file, +including for renewal, and cannot be silenced except by addressing the issue +(e.g., by using a command like ``chmod 600`` to restrict access to the file). + + +Examples +-------- + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com`` + + certbot certonly \\ + --dns-nsone \\ + --dns-nsone-credentials ~/.secrets/certbot/nsone.ini \\ + -d example.com + +.. code-block:: bash + :caption: To acquire a single certificate for both ``example.com`` and + ``www.example.com`` + + certbot certonly \\ + --dns-nsone \\ + --dns-nsone-credentials ~/.secrets/certbot/nsone.ini \\ + -d example.com \\ + -d www.example.com + +.. code-block:: bash + :caption: To acquire a certificate for ``example.com``, waiting 60 seconds + for DNS propagation + + certbot certonly \\ + --dns-nsone \\ + --dns-nsone-credentials ~/.secrets/certbot/nsone.ini \\ + --dns-nsone-propagation-seconds 60 \\ + -d example.com + +"""