diff options
Diffstat (limited to 'docs')
54 files changed, 0 insertions, 4144 deletions
diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index ba65b13af..000000000 --- a/docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -/_build/ diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 415eebca1..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,183 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LetsEncrypt.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LetsEncrypt.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/LetsEncrypt" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LetsEncrypt" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore deleted file mode 100644 index e69de29bb..000000000 --- a/docs/_static/.gitignore +++ /dev/null diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html deleted file mode 100644 index 8fd0f127d..000000000 --- a/docs/_templates/footer.html +++ /dev/null @@ -1,52 +0,0 @@ -<footer> - {% if (theme_prev_next_buttons_location == 'bottom' or theme_prev_next_buttons_location == 'both') and (next or prev) %} - <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> - {% if next %} - <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n" rel="next">{{ _('Next') }} <span class="fa fa-arrow-circle-right"></span></a> - {% endif %} - {% if prev %} - <a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> {{ _('Previous') }}</a> - {% endif %} - </div> - {% endif %} - - <hr/> - - <div role="contentinfo"> - <p> - <span class="copyright"> - © Copyright 2014-2018 - The Certbot software and documentation are licensed under the Apache 2.0 license as described at <a href="https://eff.org/cb-license">https://eff.org/cb-license</a>. - </span> - <br> - <br> - <span class="status"> - <a href="https://letsencrypt.status.io/">Let's Encrypt Status</a> - </span> - - {%- if build_id and build_url %} - {% trans build_url=build_url, build_id=build_id %} - <span class="build"> - Build - <a href="{{ build_url }}">{{ build_id }}</a>. - </span> - {% endtrans %} - {%- elif commit %} - {% trans commit=commit %} - <span class="commit"> - Revision <code>{{ commit }}</code>. - </span> - {% endtrans %} - {%- elif last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} - {%- endif %} - - </p> - </div> - - {%- if show_sphinx %} - {% trans %}Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}. - {%- endif %} - - {%- block extrafooter %} {% endblock %} - -</footer> diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 8668ec5d8..000000000 --- a/docs/api.rst +++ /dev/null @@ -1,8 +0,0 @@ -================= -API Documentation -================= - -.. toctree:: - :glob: - - api/** diff --git a/docs/api/account.rst b/docs/api/account.rst deleted file mode 100644 index fd90230ea..000000000 --- a/docs/api/account.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.account` --------------------------- - -.. automodule:: certbot.account - :members: diff --git a/docs/api/achallenges.rst b/docs/api/achallenges.rst deleted file mode 100644 index 90dda3f06..000000000 --- a/docs/api/achallenges.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.achallenges` ------------------------------- - -.. automodule:: certbot.achallenges - :members: diff --git a/docs/api/auth_handler.rst b/docs/api/auth_handler.rst deleted file mode 100644 index 8819bb1bd..000000000 --- a/docs/api/auth_handler.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.auth_handler` -------------------------------- - -.. automodule:: certbot.auth_handler - :members: diff --git a/docs/api/cert_manager.rst b/docs/api/cert_manager.rst deleted file mode 100644 index c8c86f8b9..000000000 --- a/docs/api/cert_manager.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.cert_manager` -------------------------------- - -.. automodule:: certbot.cert_manager - :members: diff --git a/docs/api/cli.rst b/docs/api/cli.rst deleted file mode 100644 index 91be86758..000000000 --- a/docs/api/cli.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.cli` ----------------------- - -.. automodule:: certbot.cli - :members: diff --git a/docs/api/client.rst b/docs/api/client.rst deleted file mode 100644 index 00a443cd9..000000000 --- a/docs/api/client.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.client` -------------------------- - -.. automodule:: certbot.client - :members: diff --git a/docs/api/configuration.rst b/docs/api/configuration.rst deleted file mode 100644 index 4e99c73d2..000000000 --- a/docs/api/configuration.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.configuration` --------------------------------- - -.. automodule:: certbot.configuration - :members: diff --git a/docs/api/constants.rst b/docs/api/constants.rst deleted file mode 100644 index 99ecc240a..000000000 --- a/docs/api/constants.rst +++ /dev/null @@ -1,9 +0,0 @@ -:mod:`certbot.constants` ------------------------------------ - -.. automodule:: certbot.constants - :members: - :exclude-members: SSL_DHPARAMS_SRC - -.. autodata:: SSL_DHPARAMS_SRC - :annotation: = '/path/to/certbot/ssl-dhparams.pem' diff --git a/docs/api/crypto_util.rst b/docs/api/crypto_util.rst deleted file mode 100644 index 2f473944c..000000000 --- a/docs/api/crypto_util.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.crypto_util` ------------------------------- - -.. automodule:: certbot.crypto_util - :members: diff --git a/docs/api/display.rst b/docs/api/display.rst deleted file mode 100644 index 1a18e6534..000000000 --- a/docs/api/display.rst +++ /dev/null @@ -1,23 +0,0 @@ -:mod:`certbot.display` --------------------------- - -.. automodule:: certbot.display - :members: - -:mod:`certbot.display.util` -=============================== - -.. automodule:: certbot.display.util - :members: - -:mod:`certbot.display.ops` -============================== - -.. automodule:: certbot.display.ops - :members: - -:mod:`certbot.display.enhancements` -======================================= - -.. automodule:: certbot.display.enhancements - :members: diff --git a/docs/api/eff.rst b/docs/api/eff.rst deleted file mode 100644 index 2924b256d..000000000 --- a/docs/api/eff.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.eff` ----------------------- - -.. automodule:: certbot.eff - :members: diff --git a/docs/api/error_handler.rst b/docs/api/error_handler.rst deleted file mode 100644 index f1306177d..000000000 --- a/docs/api/error_handler.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.error_handler` --------------------------------- - -.. automodule:: certbot.error_handler - :members: diff --git a/docs/api/errors.rst b/docs/api/errors.rst deleted file mode 100644 index a9324765b..000000000 --- a/docs/api/errors.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.errors` -------------------------- - -.. automodule:: certbot.errors - :members: diff --git a/docs/api/hooks.rst b/docs/api/hooks.rst deleted file mode 100644 index 140fbf284..000000000 --- a/docs/api/hooks.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.hooks` ------------------------- - -.. automodule:: certbot.hooks - :members: diff --git a/docs/api/index.rst b/docs/api/index.rst deleted file mode 100644 index be94214c9..000000000 --- a/docs/api/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot` ------------------- - -.. automodule:: certbot - :members: diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst deleted file mode 100644 index 2988b3b87..000000000 --- a/docs/api/interfaces.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.interfaces` ------------------------------ - -.. automodule:: certbot.interfaces - :members: diff --git a/docs/api/lock.rst b/docs/api/lock.rst deleted file mode 100644 index 6dcbf9589..000000000 --- a/docs/api/lock.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.lock` ------------------------ - -.. automodule:: certbot.lock - :members: diff --git a/docs/api/log.rst b/docs/api/log.rst deleted file mode 100644 index 41311de90..000000000 --- a/docs/api/log.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.log` ----------------------- - -.. automodule:: certbot.log - :members: diff --git a/docs/api/main.rst b/docs/api/main.rst deleted file mode 100644 index a555bab01..000000000 --- a/docs/api/main.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.main` ------------------------ - -.. automodule:: certbot.main - :members: diff --git a/docs/api/notify.rst b/docs/api/notify.rst deleted file mode 100644 index fa042b2d2..000000000 --- a/docs/api/notify.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.notify` -------------------------- - -.. automodule:: certbot.notify - :members: diff --git a/docs/api/ocsp.rst b/docs/api/ocsp.rst deleted file mode 100644 index 7044f4052..000000000 --- a/docs/api/ocsp.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.ocsp` ------------------------ - -.. automodule:: certbot.ocsp - :members: diff --git a/docs/api/plugins/common.rst b/docs/api/plugins/common.rst deleted file mode 100644 index 7cfaf8d70..000000000 --- a/docs/api/plugins/common.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.common` ---------------------------------- - -.. automodule:: certbot.plugins.common - :members: diff --git a/docs/api/plugins/disco.rst b/docs/api/plugins/disco.rst deleted file mode 100644 index 1a27f0f69..000000000 --- a/docs/api/plugins/disco.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.disco` --------------------------------- - -.. automodule:: certbot.plugins.disco - :members: diff --git a/docs/api/plugins/dns_common.rst b/docs/api/plugins/dns_common.rst deleted file mode 100644 index ee3945e74..000000000 --- a/docs/api/plugins/dns_common.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.dns_common` ---------------------------------- - -.. automodule:: certbot.plugins.dns_common - :members: diff --git a/docs/api/plugins/dns_common_lexicon.rst b/docs/api/plugins/dns_common_lexicon.rst deleted file mode 100644 index a48166828..000000000 --- a/docs/api/plugins/dns_common_lexicon.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.dns_common_lexicon` ------------------------------------------ - -.. automodule:: certbot.plugins.dns_common_lexicon - :members: diff --git a/docs/api/plugins/manual.rst b/docs/api/plugins/manual.rst deleted file mode 100644 index eea443499..000000000 --- a/docs/api/plugins/manual.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.manual` ---------------------------------- - -.. automodule:: certbot.plugins.manual - :members: diff --git a/docs/api/plugins/selection.rst b/docs/api/plugins/selection.rst deleted file mode 100644 index 6211bf9c0..000000000 --- a/docs/api/plugins/selection.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.selection` ------------------------------------- - -.. automodule:: certbot.plugins.selection - :members: diff --git a/docs/api/plugins/standalone.rst b/docs/api/plugins/standalone.rst deleted file mode 100644 index 60aa48b4f..000000000 --- a/docs/api/plugins/standalone.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.standalone` -------------------------------------- - -.. automodule:: certbot.plugins.standalone - :members: diff --git a/docs/api/plugins/util.rst b/docs/api/plugins/util.rst deleted file mode 100644 index 30ab3d49f..000000000 --- a/docs/api/plugins/util.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.util` -------------------------------- - -.. automodule:: certbot.plugins.util - :members: diff --git a/docs/api/plugins/webroot.rst b/docs/api/plugins/webroot.rst deleted file mode 100644 index e1f4523f7..000000000 --- a/docs/api/plugins/webroot.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.plugins.webroot` ----------------------------------- - -.. automodule:: certbot.plugins.webroot - :members: diff --git a/docs/api/renewal.rst b/docs/api/renewal.rst deleted file mode 100644 index 58557351f..000000000 --- a/docs/api/renewal.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.renewal` --------------------------- - -.. automodule:: certbot.renewal - :members: diff --git a/docs/api/reporter.rst b/docs/api/reporter.rst deleted file mode 100644 index ad71dbb69..000000000 --- a/docs/api/reporter.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.reporter` ---------------------------- - -.. automodule:: certbot.reporter - :members: diff --git a/docs/api/reverter.rst b/docs/api/reverter.rst deleted file mode 100644 index 3e0ac750b..000000000 --- a/docs/api/reverter.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.reverter` ---------------------------- - -.. automodule:: certbot.reverter - :members: diff --git a/docs/api/storage.rst b/docs/api/storage.rst deleted file mode 100644 index 34e3a45c0..000000000 --- a/docs/api/storage.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.storage` --------------------------- - -.. automodule:: certbot.storage - :members: diff --git a/docs/api/util.rst b/docs/api/util.rst deleted file mode 100644 index 7d0e33501..000000000 --- a/docs/api/util.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`certbot.util` --------------------------- - -.. automodule:: certbot.util - :members: diff --git a/docs/challenges.rst b/docs/challenges.rst deleted file mode 100644 index ee8bb8e61..000000000 --- a/docs/challenges.rst +++ /dev/null @@ -1,70 +0,0 @@ -Challenges -========== - -To receive a certificate from Let's Encrypt certificate authority (CA), you must pass a *challenge* to -prove you control each of the domain names that will be listed in the certificate. A challenge is one of -a list of specified tasks that only someone who controls the domain should be able to accomplish, such as: - -* Posting a specified file in a specified location on a web site (the HTTP-01 challenge) -* Posting a specified DNS record in the domain name system (the DNS-01 challenge) - -It’s possible to complete each type of challenge *automatically* (Certbot directly makes the necessary -changes itself, or runs another program that does so), or *manually* (Certbot tells you to make a -certain change, and you edit a configuration file of some kind in order to accomplish it). Certbot's -design favors performing challenges automatically, and this is the normal case for most users of Certbot. - -Some plugins offer an *authenticator*, meaning that they can satisfy challenges: - -* Apache plugin: (HTTP-01) Tries to edit your Apache configuration files to temporarily serve files to - satisfy challenges from the certificate authority. Use the Apache plugin when you're running Certbot on a - web server with Apache listening on port 80. -* Nginx plugin: (HTTP-01) Tries to edit your nginx configuration files to temporarily serve files to - satisfy challenges from the certificate authority. Use the nginx plugin when you're running Certbot on a - web server with nginx listening on port 80. -* Webroot plugin: (HTTP-01) Tries to place a file where it can be served over HTTP on port 80 by a - web server running on your system. Use the Webroot plugin when you're running Certbot on - a web server with any server application listening on port 80 serving files from a folder on disk in response. -* Standalone plugin: (HTTP-01) Tries to run a temporary web server listening on HTTP on port 80. Use the - Standalone plugin if no existing program is listening to this port. -* Manual plugin: (DNS-01 or HTTP-01) Either tells you what changes to make to your configuration or updates - your DNS records using an external script (for DNS-01) or your webroot (for HTTP-01). Use the Manual - plugin if you have the technical knowledge to make configuration changes yourself when asked to do so, - and are prepared to repeat these steps every time the certificate needs to be renewed. - -Tips for Challenges -------------------- -General tips: - -* Run Certbot on your web server, not on your laptop or another server. It’s usually the easiest way to get a certificate. -* Use a tool like the DNSchecker at dnsstuff.com to check your DNS records to make sure - there are no serious errors. A DNS error can prevent a certificate authority from - issuing a certificate, even if it does not prevent your site from loading in a browser. -* If you are using Apache or NGINX plugins, make sure the configuration of your Apache or NGINX server is correct. - -HTTP-01 Challenge -~~~~~~~~~~~~~~~~~ - -* Make sure the domain name exists and is already pointed to the public IP address of the server where - you’re requesting the certificate. -* Make sure port 80 is open, publicly reachable from the Internet, and not blocked by a router or firewall. -* When using the Webroot plugin or the manual plugin, make sure the the webroot directory exists and that you - specify it properly. If you set the webroot directory for example.com to `/var/www/example.com` - then a file placed in `/var/www/example.com/.well-known/acme-challenge/testfile` should appear on - your web site at `http://example.com/.well-known/acme-challenge/testfile` (A redirection to HTTPS - is OK here and should not stop the challenge from working.) -* In some web server configurations, all pages are dynamically generated by some kind of framework, - usually using a database backend. In this case, there might not be a particular directory - from which the web server can serve filesdirectly. Using the Webroot plugin in this case - requires making a change to your web server configuration first. -* Make sure your web server serves files properly from the directory where the challenge - file is placed (e. g. `/.well-known/acme-challenge`) to the expected location on the - website without adding a header or footer. -* When using the Standalone plugin, make sure another program is not already listening to port 80 on the server. -* When using the Webroot plugin, make sure there is a web server listening on port 80. - -DNS-01 Challenge -~~~~~~~~~~~~~~~~ - -* When using the manual plugin, make sure your DNS records are correctly updated; - you must be able to make appropriate changes to your DNS zone in order to pass the challenge. - diff --git a/docs/ciphers.rst b/docs/ciphers.rst deleted file mode 100644 index 1b320cdf9..000000000 --- a/docs/ciphers.rst +++ /dev/null @@ -1,339 +0,0 @@ -============ -Ciphersuites -============ - -.. contents:: Table of Contents - :local: - - -.. _ciphersuites: - -Introduction -============ - -Autoupdates ------------ - -Within certain limits, TLS server software can choose what kind of -cryptography to use when a client connects. These choices can affect -security, compatibility, and performance in complex ways. Most of -these options are independent of a particular certificate. Certbot -tries to provide defaults that we think are most useful to our users. - -As described below, Certbot will default to modifying -server software's cryptographic settings to keep these up-to-date with -what we think are appropriate defaults when new versions of the Certbot -are installed (for example, by an operating system package manager). - -When this feature is implemented, this document will be updated -to describe how to disable these automatic changes. - - -Cryptographic choices ---------------------- - -Software that uses cryptography must inevitably make choices about what -kind of cryptography to use and how. These choices entail assumptions -about how well particular cryptographic mechanisms resist attack, and what -trade-offs are available and appropriate. The choices are constrained -by compatibility issues (in order to interoperate with other software, -an implementation must agree to use cryptographic mechanisms that the -other side also supports) and protocol issues (cryptographic mechanisms -must be specified in protocols and there must be a way to agree to use -them in a particular context). - -The best choices for a particular application may change over time in -response to new research, new standardization events, changes in computer -hardware, and changes in the prevalence of legacy software. Much important -research on cryptanalysis and cryptographic vulnerabilities is unpublished -because many researchers have been working in the interest of improving -some entities' communications security while weakening, or failing to -improve, others' security. But important information that improves our -understanding of the state of the art is published regularly. - -When enabling TLS support in a compatible web server (which is a separate -step from obtaining a certificate), Certbot has the ability to -update that web server's TLS configuration. Again, this is *different -from the cryptographic particulars of the certificate itself*; the -certificate as of the initial release will be RSA-signed using one of -Let's Encrypt's 2048-bit RSA keys, and will describe the subscriber's -RSA public key ("subject public key") of at least 2048 bits, which is -used for key establishment. - -Note that the subscriber's RSA public key can be used in a wide variety -of key establishment methods, most of which do not use RSA directly -for key exchange, but only for authenticating the server! For example, -in DHE and ECDHE key exchanges, the subject public key is just used to -sign other parameters for authentication. You do not have to "use RSA" -for other purposes just because you're using an RSA key for authentication. - -The certificate doesn't specify other cryptographic or ciphersuite -particulars; for example, it doesn't say whether or not parties should -use a particular symmetric algorithm like 3DES, or what cipher modes -they should use. All of these details are negotiated between client -and server independent of the content of the ciphersuite. The -Let's Encrypt project hopes to provide useful defaults that reflect -good security choices with respect to the publicly-known state of the -art. However, the Let's Encrypt certificate authority does *not* -dictate end-users' security policy, and any site is welcome to change -its preferences in accordance with its own policy or its administrators' -preferences, and use different cryptographic mechanisms or parameters, -or a different priority order, than the defaults provided by Certbot. - -If you don't use Certbot to configure your server directly, because the -client doesn't integrate with your server software or because you chose -not to use this integration, then the cryptographic defaults haven't been -modified, and the cryptography chosen by the server will still be whatever -the default for your software was. For example, if you obtain a -certificate using *standalone* mode and then manually install it in an IMAP -or LDAP server, your cryptographic settings will not be modified by the -client in any way. - - -Sources of defaults -------------------- - -Initially, Certbot will configure users' servers to use the cryptographic -defaults recommended by the Mozilla project. These settings are well-reasoned -recommendations that carefully consider client software compatibility. They -are described at - -https://wiki.mozilla.org/Security/Server_Side_TLS - -and the version implemented by Certbot will be the -version that was most current as of the release date of each client -version. Mozilla offers three separate sets of cryptographic options, -which trade off security and compatibility differently. These are -referred to as the "Modern", "Intermediate", and "Old" configurations -(in order from most secure to least secure, and least-backwards compatible -to most-backwards compatible). The client will follow the Mozilla defaults -for the *Intermediate* configuration by default, at least with regards to -ciphersuites and TLS versions. Mozilla's web site describes which client -software will be compatible with each configuration. You can also use -the Qualys SSL Labs site, which Certbot will suggest -when installing a certificate, to test your server and see whether it -will be compatible with particular software versions. - -It will be possible to ask Certbot to instead apply (and track) Modern -or Old configurations. - -The Let's Encrypt project expects to follow the Mozilla recommendations -in the future as those recommendations are updated. (For example, some -users have proposed prioritizing a new ciphersuite known as ``0xcc13`` -which uses the ChaCha and Poly1305 algorithms, and which is already -implemented by the Chrome browser. Mozilla has delayed recommending -``0xcc13`` over compatibility and standardization concerns, but is likely -to recommend it in the future once these concerns have been addressed. At -that point, Certbot would likely follow the Mozilla recommendations and favor -the use of this ciphersuite as well.) - -The Let's Encrypt project may deviate from the Mozilla recommendations -in the future if good cause is shown and we believe our users' -priorities would be well-served by doing so. In general, please address -relevant proposals for changing priorities to the Mozilla security -team first, before asking the Certbot developers to change -Certbot's priorities. The Mozilla security team is likely to have more -resources and expertise to bring to bear on evaluating reasons why its -recommendations should be updated. - -The Let's Encrypt project will entertain proposals to create a *very* -small number of alternative configurations (apart from Modern, -Intermediate, and Old) that there's reason to believe would be widely -used by sysadmins; this would usually be a preferable course to modifying -an existing configuration. For example, if many sysadmins want their -servers configured to track a different expert recommendation, Certbot -could add an option to do so. - - -Resources for recommendations ------------------------------ - -In the course of considering how to handle this issue, we received -recommendations with sources of expert guidance on ciphersuites and other -cryptographic parameters. We're grateful to everyone who contributed -suggestions. The recommendations we received are available under Feedback_. - -Certbot users are welcome to review these authorities to -better inform their own cryptographic parameter choices. We also -welcome suggestions of other resources to add to this list. Please keep -in mind that different recommendations may reflect different priorities -or evaluations of trade-offs, especially related to compatibility! - - -Changing your settings ----------------------- - -This will probably look something like - -.. code-block:: shell - - certbot --cipher-recommendations mozilla-secure - certbot --cipher-recommendations mozilla-intermediate - certbot --cipher-recommendations mozilla-old - -to track Mozilla's *Secure*, *Intermediate*, or *Old* recommendations, -and - -.. code-block:: shell - - certbot --update-ciphers on - -to enable updating ciphers with each new Certbot release, or - -.. code-block:: shell - - certbot --update-ciphers off - -to disable automatic configuration updates. These features have not yet -been implemented and this syntax may change when they are implemented. - - -TODO ----- - -The status of this feature is tracked as part of issue #1123 in our -bug tracker. - -https://github.com/certbot/certbot/issues/1123 - -Prior to implementation of #1123, the client does not actually modify -ciphersuites (this is intended to be implemented as a "configuration -enhancement", but the only configuration enhancement implemented -so far is redirecting HTTP requests to HTTPS in web servers, the -"redirect" enhancement). The changes here would probably be either a new -"ciphersuite" enhancement in each plugin that provides an installer, -or a family of enhancements, one per selectable ciphersuite configuration. - -Feedback -======== -We receive lots of feedback on the type of ciphersuites that Let's Encrypt supports and list some collated feedback below. This section aims to track suggestions and references that people have offered or identified to improve the ciphersuites that Let's Encrypt enables when configuring TLS on servers. - -Because of the Chatham House Rule applicable to some of the discussions, people are *not* individually credited for their suggestions, but most suggestions here were made or found by other people, and I thank them for their contributions. - -Some people provided rationale information mostly having to do with compatibility of particular user-agents (especially UAs that don't support ECC, or that don't support DH groups > 1024 bits). Some ciphersuite configurations have been chosen to try to increase compatibility with older UAs while allowing newer UAs to negotiate stronger crypto. For example, some configurations forego forward secrecy entirely for connections from old UAs, like by offering ECDHE and RSA key exchange, but no DHE at all. (There are UAs that can fail the negotiation completely if a DHE ciphersuite with prime > 1024 bits is offered.) - -References ----------- - -RFC 7575 -~~~~~~~~ - -IETF has published a BCP document, RFC 7525, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" - -https://datatracker.ietf.org/doc/rfc7525/ - -BetterCrypto.org -~~~~~~~~~~~~~~~~ - -BetterCrypto.org, a collaboration of mostly European IT security experts, has published a draft paper, "Applied Crypto Hardening" - -https://bettercrypto.org/static/applied-crypto-hardening.pdf - -FF-DHE Internet-Draft -~~~~~~~~~~~~~~~~~~~~~ - -Gillmor's Internet-Draft "Negotiated Discrete Log Diffie-Hellman Ephemeral Parameters for TLS" is being developed at the IETF TLS WG. It advocates using *standardized* DH groups in all cases, not individually-chosen ones (mostly because of the Triple Handshake attack which can involve maliciously choosing invalid DH groups). The draft provides a list of recommended groups, with primes beginning at 2048 bits and going up from there. It also has a new protocol mechanism for agreeing to use these groups, with the possibility of backwards compatibility (and use of weaker DH groups) for older clients and servers that don't know about this mechanism. - -https://tools.ietf.org/html/draft-ietf-tls-negotiated-ff-dhe-10 - -Mozilla -~~~~~~~ - -Mozilla's general server configuration guidance is available at https://wiki.mozilla.org/Security/Server_Side_TLS - -Mozilla has also produced a configuration generator: https://mozilla.github.io/server-side-tls/ssl-config-generator/ - -Dutch National Cyber Security Centre -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Dutch National Cyber Security Centre has published guidance on "ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS)" ("IT Security Guidelines for Transport Layer Security (TLS)"). These are available only in Dutch at - -https://www.ncsc.nl/dienstverlening/expertise-advies/kennisdeling/whitepapers/ict-beveiligingsrichtlijnen-voor-transport-layer-security-tls.html - -I have access to an English-language summary of the recommendations. - -Keylength.com -~~~~~~~~~~~~~ - -Damien Giry collects recommendations by academic researchers and standards organizations about keylengths for particular cryptoperiods, years, or security levels. The keylength recommendations of the various sources are summarized in a chart. This site has been updated over time and includes expert guidance from eight sources published between 2000 and 2017. - -http://www.keylength.com/ - -NIST -~~~~ -NISA published its "NIST Special Publication 800-52 Revision 1: Guidelines for the Selection, Configuration, and Use of Transport Layer Security (TLS) Implementations" - -http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-52r1.pdf - -and its "NIST Special Publication 800-57: Recommendation for Key Management – Part 1: General (Revision 3)" - -http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57_part1_rev3_general.pdf - -ENISA -~~~~~ - -ENISA published its "Algorithms, Key Sizes and Parameters Report - 2013" - -https://www.enisa.europa.eu/activities/identity-and-trust/library/deliverables/algorithms-key-sizes-and-parameters-report - -WeakDH/Logjam -------------- - -The WeakDH/Logjam research has thrown into question the safety of some existing practice using DH ciphersuites, especially the use of standardized groups with a prime ≤ 1024 bits. The authors provided detailed guidance, including ciphersuite lists, at - -https://weakdh.org/sysadmin.html - -These lists may have been derived from Mozilla's recommendations. -One of the authors clarified his view of the priorities for various changes as a result of the research at - -https://www.ietf.org/mail-archive/web/tls/current/msg16496.html - -In particular, he supports ECDHE and also supports the use of the standardized groups in the FF-DHE Internet-Draft mentioned above (which isn't clear from the group's original recommendations). - -Particular sites' opinions or configurations --------------------------------------------- - -Amazon ELB -~~~~~~~~~~ - -Amazon ELB explains its current ciphersuite choices at - -https://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/elb-security-policy-table.html - -U.S. Government 18F -~~~~~~~~~~~~~~~~~~~ - -The 18F site (https://18f.gsa.gov/) is using - -:: - - ssl_ciphers 'kEECDH+ECDSA+AES128 kEECDH+ECDSA+AES256 kEECDH+AES128 kEECDH+AES256 kEDH+AES128 kEDH+AES256 DES-CBC3-SHA +SHA !aNULL !eNULL !LOW !MD5 !EXP !DSS !PSK !SRP !kECDH !CAMELLIA !RC4 !SEED'; - -Duraconf -~~~~~~~~ - -The Duraconf project collects particular configuration files, with an apparent focus on avoiding the use of obsolete symmetric ciphers and hash functions, and favoring forward secrecy while not requiring it. - -https://github.com/ioerror/duraconf - -Site scanning or rating tools ------------------------------ - -Qualys SSL Labs -~~~~~~~~~~~~~~~ - -Qualys offers the best-known TLS security scanner, maintained by Ivan Ristić. - -https://www.ssllabs.com/ - -Dutch NCSC -~~~~~~~~~~ - -The Dutch NCSC, mentioned above, has also made available its own site security scanner which indicates how well sites comply with the recommendations. - -https://en.internet.nl/ - -Java compatibility issue ------------------------- - -A lot of backward-compatibility concerns have to do with Java hard-coding DHE primes to a 1024-bit limit, accepting DHE ciphersuites in negotiation, and then aborting the connection entirely if a prime > 1024 bits is presented. The simple summary is that servers offering a Java-compatible DHE ciphersuite in preference to other Java-compatible ciphersuites, and then presenting a DH group with a prime > 1024 bits, will be completely incompatible with clients running some versions of Java. (This may also be the case with very old MSIE versions...?) There are various strategies for dealing with this, and maybe we can document the options here. diff --git a/docs/cli-help.txt b/docs/cli-help.txt deleted file mode 100644 index cd6d431b3..000000000 --- a/docs/cli-help.txt +++ /dev/null @@ -1,726 +0,0 @@ -usage: - certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ... - -Certbot can obtain and install HTTPS/TLS/SSL certificates. By default, -it will attempt to use a webserver both for obtaining and installing the -certificate. The most common SUBCOMMANDS and flags are: - -obtain, install, and renew certificates: - (default) run Obtain & install a certificate in your current webserver - certonly Obtain or renew a certificate, but do not install it - renew Renew all previously obtained certificates that are near expiry - enhance Add security enhancements to your existing configuration - -d DOMAINS Comma-separated list of domains to obtain a certificate for - - --apache Use the Apache plugin for authentication & installation - --standalone Run a standalone webserver for authentication - --nginx Use the Nginx plugin for authentication & installation - --webroot Place files in a server's webroot folder for authentication - --manual Obtain certificates interactively, or using shell script hooks - - -n Run non-interactively - --test-cert Obtain a test certificate from a staging server - --dry-run Test "renew" or "certonly" without saving any certificates to disk - -manage certificates: - certificates Display information about certificates you have from Certbot - revoke Revoke a certificate (supply --cert-path or --cert-name) - delete Delete a certificate - -manage your account with Let's Encrypt: - register Create a Let's Encrypt ACME account - update_account Update a Let's Encrypt ACME account - --agree-tos Agree to the ACME server's Subscriber Agreement - -m EMAIL Email address for important account notifications - -optional arguments: - -h, --help show this help message and exit - -c CONFIG_FILE, --config CONFIG_FILE - path to config file (default: /etc/letsencrypt/cli.ini - and ~/.config/letsencrypt/cli.ini) - -v, --verbose This flag can be used multiple times to incrementally - increase the verbosity of output, e.g. -vvv. (default: - -2) - --max-log-backups MAX_LOG_BACKUPS - Specifies the maximum number of backup logs that - should be kept by Certbot's built in log rotation. - Setting this flag to 0 disables log rotation entirely, - causing Certbot to always append to the same log file. - (default: 1000) - -n, --non-interactive, --noninteractive - Run without ever asking for user input. This may - require additional command line flags; the client will - try to explain which ones are required if it finds one - missing (default: False) - --force-interactive Force Certbot to be interactive even if it detects - it's not being run in a terminal. This flag cannot be - used with the renew subcommand. (default: False) - -d DOMAIN, --domains DOMAIN, --domain DOMAIN - Domain names to apply. For multiple domains you can - use multiple -d flags or enter a comma separated list - of domains as a parameter. The first domain provided - will be the subject CN of the certificate, and all - domains will be Subject Alternative Names on the - certificate. The first domain will also be used in - some software user interfaces and as the file paths - for the certificate and related material unless - otherwise specified or you already have a certificate - with the same name. In the case of a name collision it - will append a number like 0001 to the file path name. - (default: Ask) - --eab-kid EAB_KID Key Identifier for External Account Binding (default: - None) - --eab-hmac-key EAB_HMAC_KEY - HMAC key for External Account Binding (default: None) - --cert-name CERTNAME Certificate name to apply. This name is used by - Certbot for housekeeping and in file paths; it doesn't - affect the content of the certificate itself. To see - certificate names, run 'certbot certificates'. When - creating a new certificate, specifies the new - certificate's name. (default: the first provided - domain or the name of an existing certificate on your - system for the same domains) - --dry-run Perform a test run of the client, obtaining test - (invalid) certificates but not saving them to disk. - This can currently only be used with the 'certonly' - and 'renew' subcommands. Note: Although --dry-run - tries to avoid making any persistent changes on a - system, it is not completely side-effect free: if used - with webserver authenticator plugins like apache and - nginx, it makes and then reverts temporary config - changes in order to obtain test certificates, and - reloads webservers to deploy and then roll back those - changes. It also calls --pre-hook and --post-hook - commands if they are defined because they may be - necessary to accurately simulate renewal. --deploy- - hook commands are not called. (default: False) - --debug-challenges After setting up challenges, wait for user input - before submitting to CA (default: False) - --preferred-challenges PREF_CHALLS - A sorted, comma delimited list of the preferred - challenge to use during authorization with the most - preferred challenge listed first (Eg, "dns" or "tls- - sni-01,http,dns"). Not all plugins support all - challenges. See - https://certbot.eff.org/docs/using.html#plugins for - details. ACME Challenges are versioned, but if you - pick "http" rather than "http-01", Certbot will select - the latest version automatically. (default: []) - --user-agent USER_AGENT - Set a custom user agent string for the client. User - agent strings allow the CA to collect high level - statistics about success rates by OS, plugin and use - case, and to know when to deprecate support for past - Python versions and flags. If you wish to hide this - information from the Let's Encrypt server, set this to - "". (default: CertbotACMEClient/0.30.2 - (certbot(-auto); OS_NAME OS_VERSION) Authenticator/XXX - Installer/YYY (SUBCOMMAND; flags: FLAGS) - Py/major.minor.patchlevel). The flags encoded in the - user agent are: --duplicate, --force-renew, --allow- - subset-of-names, -n, and whether any hooks are set. - --user-agent-comment USER_AGENT_COMMENT - Add a comment to the default user agent string. May be - used when repackaging Certbot or calling it from - another tool to allow additional statistical data to - be collected. Ignored if --user-agent is set. - (Example: Foo-Wrapper/1.0) (default: None) - -automation: - Flags for automating execution & other tweaks - - --keep-until-expiring, --keep, --reinstall - If the requested certificate matches an existing - certificate, always keep the existing one until it is - due for renewal (for the 'run' subcommand this means - reinstall the existing certificate). (default: Ask) - --expand If an existing certificate is a strict subset of the - requested names, always expand and replace it with the - additional names. (default: Ask) - --version show program's version number and exit - --force-renewal, --renew-by-default - If a certificate already exists for the requested - domains, renew it now, regardless of whether it is - near expiry. (Often --keep-until-expiring is more - appropriate). Also implies --expand. (default: False) - --renew-with-new-domains - If a certificate already exists for the requested - certificate name but does not match the requested - domains, renew it now, regardless of whether it is - near expiry. (default: False) - --reuse-key When renewing, use the same private key as the - existing certificate. (default: False) - --allow-subset-of-names - When performing domain validation, do not consider it - a failure if authorizations can not be obtained for a - strict subset of the requested domains. This may be - useful for allowing renewals for multiple domains to - succeed even if some domains no longer point at this - system. This option cannot be used with --csr. - (default: False) - --agree-tos Agree to the ACME Subscriber Agreement (default: Ask) - --duplicate Allow making a certificate lineage that duplicates an - existing one (both can be renewed in parallel) - (default: False) - --os-packages-only (certbot-auto only) install OS package dependencies - and then stop (default: False) - --no-self-upgrade (certbot-auto only) prevent the certbot-auto script - from upgrading itself to newer released versions - (default: Upgrade automatically) - --no-bootstrap (certbot-auto only) prevent the certbot-auto script - from installing OS-level dependencies (default: Prompt - to install OS-wide dependencies, but exit if the user - says 'No') - -q, --quiet Silence all output except errors. Useful for - automation via cron. Implies --non-interactive. - (default: False) - -security: - Security parameters & server settings - - --rsa-key-size N Size of the RSA key. (default: 2048) - --must-staple Adds the OCSP Must Staple extension to the - certificate. Autoconfigures OCSP Stapling for - supported setups (Apache version >= 2.3.3 ). (default: - False) - --redirect Automatically redirect all HTTP traffic to HTTPS for - the newly authenticated vhost. (default: Ask) - --no-redirect Do not automatically redirect all HTTP traffic to - HTTPS for the newly authenticated vhost. (default: - Ask) - --hsts Add the Strict-Transport-Security header to every HTTP - response. Forcing browser to always use SSL for the - domain. Defends against SSL Stripping. (default: None) - --uir Add the "Content-Security-Policy: upgrade-insecure- - requests" header to every HTTP response. Forcing the - browser to use https:// for every http:// resource. - (default: None) - --staple-ocsp Enables OCSP Stapling. A valid OCSP response is - stapled to the certificate that the server offers - during TLS. (default: None) - --strict-permissions Require that all configuration files are owned by the - current user; only needed if your config is somewhere - unsafe like /tmp/ (default: False) - --auto-hsts Gradually increasing max-age value for HTTP Strict - Transport Security security header (default: False) - -testing: - The following flags are meant for testing and integration purposes only. - - --test-cert, --staging - Use the staging server to obtain or revoke test - (invalid) certificates; equivalent to --server https - ://acme-staging-v02.api.letsencrypt.org/directory - (default: False) - --debug Show tracebacks in case of errors, and allow certbot- - auto execution on experimental platforms (default: - False) - --no-verify-ssl Disable verification of the ACME server's certificate. - (default: False) - --tls-sni-01-port TLS_SNI_01_PORT - Port used during tls-sni-01 challenge. This only - affects the port Certbot listens on. A conforming ACME - server will still attempt to connect on port 443. - (default: 443) - --tls-sni-01-address TLS_SNI_01_ADDRESS - The address the server listens to during tls-sni-01 - challenge. (default: ) - --http-01-port HTTP01_PORT - Port used in the http-01 challenge. This only affects - the port Certbot listens on. A conforming ACME server - will still attempt to connect on port 80. (default: - 80) - --http-01-address HTTP01_ADDRESS - The address the server listens to during http-01 - challenge. (default: ) - --break-my-certs Be willing to replace or renew valid certificates with - invalid (testing/staging) certificates (default: - False) - -paths: - Flags for changing execution paths & servers - - --cert-path CERT_PATH - Path to where certificate is saved (with auth --csr), - installed from, or revoked. (default: None) - --key-path KEY_PATH Path to private key for certificate installation or - revocation (if account key is missing) (default: None) - --fullchain-path FULLCHAIN_PATH - Accompanying path to a full certificate chain - (certificate plus chain). (default: None) - --chain-path CHAIN_PATH - Accompanying path to a certificate chain. (default: - None) - --config-dir CONFIG_DIR - Configuration directory. (default: /etc/letsencrypt) - --work-dir WORK_DIR Working directory. (default: /var/lib/letsencrypt) - --logs-dir LOGS_DIR Logs directory. (default: /var/log/letsencrypt) - --server SERVER ACME Directory Resource URI. (default: - https://acme-v02.api.letsencrypt.org/directory) - -manage: - Various subcommands and flags are available for managing your - certificates: - - certificates List certificates managed by Certbot - delete Clean up all files related to a certificate - renew Renew all certificates (or one specified with --cert- - name) - revoke Revoke a certificate specified with --cert-path or - --cert-name - update_symlinks Recreate symlinks in your /etc/letsencrypt/live/ - directory - -run: - Options for obtaining & installing certificates - -certonly: - Options for modifying how a certificate is obtained - - --csr CSR Path to a Certificate Signing Request (CSR) in DER or - PEM format. Currently --csr only works with the - 'certonly' subcommand. (default: None) - -renew: - The 'renew' subcommand will attempt to renew all certificates (or more - precisely, certificate lineages) you have previously obtained if they are - close to expiry, and print a summary of the results. By default, 'renew' - will reuse the options used to create obtain or most recently successfully - renew each certificate lineage. You can try it with `--dry-run` first. For - more fine-grained control, you can renew individual lineages with the - `certonly` subcommand. Hooks are available to run commands before and - after renewal; see https://certbot.eff.org/docs/using.html#renewal for - more information on these. - - --pre-hook PRE_HOOK Command to be run in a shell before obtaining any - certificates. Intended primarily for renewal, where it - can be used to temporarily shut down a webserver that - might conflict with the standalone plugin. This will - only be called if a certificate is actually to be - obtained/renewed. When renewing several certificates - that have identical pre-hooks, only the first will be - executed. (default: None) - --post-hook POST_HOOK - Command to be run in a shell after attempting to - obtain/renew certificates. Can be used to deploy - renewed certificates, or to restart any servers that - were stopped by --pre-hook. This is only run if an - attempt was made to obtain/renew a certificate. If - multiple renewed certificates have identical post- - hooks, only one will be run. (default: None) - --deploy-hook DEPLOY_HOOK - Command to be run in a shell once for each - successfully issued certificate. For this command, the - shell variable $RENEWED_LINEAGE will point to the - config live subdirectory (for example, - "/etc/letsencrypt/live/example.com") containing the - new certificates and keys; the shell variable - $RENEWED_DOMAINS will contain a space-delimited list - of renewed certificate domains (for example, - "example.com www.example.com" (default: None) - --disable-hook-validation - Ordinarily the commands specified for --pre-hook - /--post-hook/--deploy-hook will be checked for - validity, to see if the programs being run are in the - $PATH, so that mistakes can be caught early, even when - the hooks aren't being run just yet. The validation is - rather simplistic and fails if you use more advanced - shell constructs, so you can use this switch to - disable it. (default: False) - --no-directory-hooks Disable running executables found in Certbot's hook - directories during renewal. (default: False) - --disable-renew-updates - Disable automatic updates to your server configuration - that would otherwise be done by the selected installer - plugin, and triggered when the user executes "certbot - renew", regardless of if the certificate is renewed. - This setting does not apply to important TLS - configuration updates. (default: False) - --no-autorenew Disable auto renewal of certificates. (default: True) - -certificates: - List certificates managed by Certbot - -delete: - Options for deleting a certificate - -revoke: - Options for revocation of certificates - - --reason {unspecified,keycompromise,affiliationchanged,superseded,cessationofoperation} - Specify reason for revoking certificate. (default: - unspecified) - --delete-after-revoke - Delete certificates after revoking them. (default: - None) - --no-delete-after-revoke - Do not delete certificates after revoking them. This - option should be used with caution because the 'renew' - subcommand will attempt to renew undeleted revoked - certificates. (default: None) - -register: - Options for account registration - - --register-unsafely-without-email - Specifying this flag enables registering an account - with no email address. This is strongly discouraged, - because in the event of key loss or account compromise - you will irrevocably lose access to your account. You - will also be unable to receive notice about impending - expiration or revocation of your certificates. Updates - to the Subscriber Agreement will still affect you, and - will be effective 14 days after posting an update to - the web site. (default: False) - -m EMAIL, --email EMAIL - Email used for registration and recovery contact. Use - comma to register multiple emails, ex: - u1@example.com,u2@example.com. (default: Ask). - --eff-email Share your e-mail address with EFF (default: None) - --no-eff-email Don't share your e-mail address with EFF (default: - None) - -update_account: - Options for account modification - -unregister: - Options for account deactivation. - - --account ACCOUNT_ID Account ID to use (default: None) - -install: - Options for modifying how a certificate is deployed - -config_changes: - Options for controlling which changes are displayed - - --num NUM How many past revisions you want to be displayed - (default: None) - -rollback: - Options for rolling back server configuration changes - - --checkpoints N Revert configuration N number of checkpoints. - (default: 1) - -plugins: - Options for for the "plugins" subcommand - - --init Initialize plugins. (default: False) - --prepare Initialize and prepare plugins. (default: False) - --authenticators Limit to authenticator plugins only. (default: None) - --installers Limit to installer plugins only. (default: None) - -update_symlinks: - Recreates certificate and key symlinks in /etc/letsencrypt/live, if you - changed them by hand or edited a renewal configuration file - -enhance: - Helps to harden the TLS configuration by adding security enhancements to - already existing configuration. - -plugins: - Plugin Selection: Certbot client supports an extensible plugins - architecture. See 'certbot plugins' for a list of all installed plugins - and their names. You can force a particular plugin by setting options - provided below. Running --help <plugin_name> will list flags specific to - that plugin. - - --configurator CONFIGURATOR - Name of the plugin that is both an authenticator and - an installer. Should not be used together with - --authenticator or --installer. (default: Ask) - -a AUTHENTICATOR, --authenticator AUTHENTICATOR - Authenticator plugin name. (default: None) - -i INSTALLER, --installer INSTALLER - Installer plugin name (also used to find domains). - (default: None) - --apache Obtain and install certificates using Apache (default: - False) - --nginx Obtain and install certificates using Nginx (default: - False) - --standalone Obtain certificates using a "standalone" webserver. - (default: False) - --manual Provide laborious manual instructions for obtaining a - certificate (default: False) - --webroot Obtain certificates by placing files in a webroot - directory. (default: False) - --dns-cloudflare Obtain certificates using a DNS TXT record (if you are - using Cloudflare for DNS). (default: False) - --dns-cloudxns Obtain certificates using a DNS TXT record (if you are - using CloudXNS for DNS). (default: False) - --dns-digitalocean Obtain certificates using a DNS TXT record (if you are - using DigitalOcean for DNS). (default: False) - --dns-dnsimple Obtain certificates using a DNS TXT record (if you are - using DNSimple for DNS). (default: False) - --dns-dnsmadeeasy Obtain certificates using a DNS TXT record (if you - areusing DNS Made Easy for DNS). (default: False) - --dns-gehirn Obtain certificates using a DNS TXT record (if you are - using Gehirn Infrastracture Service for DNS). - (default: False) - --dns-google Obtain certificates using a DNS TXT record (if you are - using Google Cloud DNS). (default: False) - --dns-linode Obtain certificates using a DNS TXT record (if you are - using Linode for DNS). (default: False) - --dns-luadns Obtain certificates using a DNS TXT record (if you are - using LuaDNS for DNS). (default: False) - --dns-nsone Obtain certificates using a DNS TXT record (if you are - using NS1 for DNS). (default: False) - --dns-ovh Obtain certificates using a DNS TXT record (if you are - using OVH for DNS). (default: False) - --dns-rfc2136 Obtain certificates using a DNS TXT record (if you are - using BIND for DNS). (default: False) - --dns-route53 Obtain certificates using a DNS TXT record (if you are - using Route53 for DNS). (default: False) - --dns-sakuracloud Obtain certificates using a DNS TXT record (if you are - using Sakura Cloud for DNS). (default: False) - -apache: - Apache Web Server plugin - - --apache-enmod APACHE_ENMOD - Path to the Apache 'a2enmod' binary (default: a2enmod) - --apache-dismod APACHE_DISMOD - Path to the Apache 'a2dismod' binary (default: - a2dismod) - --apache-le-vhost-ext APACHE_LE_VHOST_EXT - SSL vhost configuration extension (default: -le- - ssl.conf) - --apache-server-root APACHE_SERVER_ROOT - Apache server root directory (default: /etc/apache2) - --apache-vhost-root APACHE_VHOST_ROOT - Apache server VirtualHost configuration root (default: - None) - --apache-logs-root APACHE_LOGS_ROOT - Apache server logs directory (default: - /var/log/apache2) - --apache-challenge-location APACHE_CHALLENGE_LOCATION - Directory path for challenge configuration (default: - /etc/apache2) - --apache-handle-modules APACHE_HANDLE_MODULES - Let installer handle enabling required modules for you - (Only Ubuntu/Debian currently) (default: True) - --apache-handle-sites APACHE_HANDLE_SITES - Let installer handle enabling sites for you (Only - Ubuntu/Debian currently) (default: True) - --apache-ctl APACHE_CTL - Full path to Apache control script (default: - apache2ctl) - -dns-cloudflare: - Obtain certificates using a DNS TXT record (if you are using Cloudflare - for DNS). - - --dns-cloudflare-propagation-seconds 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) - --dns-cloudflare-credentials DNS_CLOUDFLARE_CREDENTIALS - Cloudflare credentials INI file. (default: None) - -dns-cloudxns: - Obtain certificates using a DNS TXT record (if you are using CloudXNS for - DNS). - - --dns-cloudxns-propagation-seconds 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) - --dns-cloudxns-credentials DNS_CLOUDXNS_CREDENTIALS - CloudXNS credentials INI file. (default: None) - -dns-digitalocean: - Obtain certs using a DNS TXT record (if you are using DigitalOcean for - DNS). - - --dns-digitalocean-propagation-seconds 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) - --dns-digitalocean-credentials DNS_DIGITALOCEAN_CREDENTIALS - DigitalOcean credentials INI file. (default: None) - -dns-dnsimple: - Obtain certificates using a DNS TXT record (if you are using DNSimple for - DNS). - - --dns-dnsimple-propagation-seconds 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) - --dns-dnsimple-credentials DNS_DNSIMPLE_CREDENTIALS - DNSimple credentials INI file. (default: None) - -dns-dnsmadeeasy: - Obtain certificates using a DNS TXT record (if you are using DNS Made Easy - for DNS). - - --dns-dnsmadeeasy-propagation-seconds DNS_DNSMADEEASY_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 60) - --dns-dnsmadeeasy-credentials DNS_DNSMADEEASY_CREDENTIALS - DNS Made Easy credentials INI file. (default: None) - -dns-gehirn: - Obtain certificates using a DNS TXT record (if you are using Gehirn - Infrastracture Service for DNS). - - --dns-gehirn-propagation-seconds DNS_GEHIRN_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 30) - --dns-gehirn-credentials DNS_GEHIRN_CREDENTIALS - Gehirn Infrastracture Service credentials file. - (default: None) - -dns-google: - Obtain certificates using a DNS TXT record (if you are using Google Cloud - DNS for DNS). - - --dns-google-propagation-seconds 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) - --dns-google-credentials DNS_GOOGLE_CREDENTIALS - Path to Google Cloud DNS service account JSON file. - (See https://developers.google.com/identity/protocols/ - OAuth2ServiceAccount#creatinganaccount forinformation - about creating a service account and - https://cloud.google.com/dns/access- - control#permissions_and_roles for information about - therequired permissions.) (default: None) - -dns-linode: - Obtain certs using a DNS TXT record (if you are using Linode for DNS). - - --dns-linode-propagation-seconds DNS_LINODE_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 1200) - --dns-linode-credentials DNS_LINODE_CREDENTIALS - Linode credentials INI file. (default: None) - -dns-luadns: - Obtain certificates using a DNS TXT record (if you are using LuaDNS for - DNS). - - --dns-luadns-propagation-seconds DNS_LUADNS_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 30) - --dns-luadns-credentials DNS_LUADNS_CREDENTIALS - LuaDNS credentials INI file. (default: None) - -dns-nsone: - Obtain certificates using a DNS TXT record (if you are using NS1 for DNS). - - --dns-nsone-propagation-seconds 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) - --dns-nsone-credentials DNS_NSONE_CREDENTIALS - NS1 credentials file. (default: None) - -dns-ovh: - Obtain certificates using a DNS TXT record (if you are using OVH for DNS). - - --dns-ovh-propagation-seconds DNS_OVH_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 30) - --dns-ovh-credentials DNS_OVH_CREDENTIALS - OVH credentials INI file. (default: None) - -dns-rfc2136: - Obtain certificates using a DNS TXT record (if you are using BIND for - DNS). - - --dns-rfc2136-propagation-seconds DNS_RFC2136_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 60) - --dns-rfc2136-credentials DNS_RFC2136_CREDENTIALS - RFC 2136 credentials INI file. (default: None) - -dns-route53: - Obtain certificates using a DNS TXT record (if you are using AWS Route53 - for DNS). - - --dns-route53-propagation-seconds DNS_ROUTE53_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 10) - -dns-sakuracloud: - Obtain certificates using a DNS TXT record (if you are using Sakura Cloud - for DNS). - - --dns-sakuracloud-propagation-seconds DNS_SAKURACLOUD_PROPAGATION_SECONDS - The number of seconds to wait for DNS to propagate - before asking the ACME server to verify the DNS - record. (default: 90) - --dns-sakuracloud-credentials DNS_SAKURACLOUD_CREDENTIALS - Sakura Cloud credentials file. (default: None) - -manual: - Authenticate through manual configuration or custom shell scripts. When - using shell scripts, an authenticator script must be provided. The - environment variables available to this script depend on the type of - challenge. $CERTBOT_DOMAIN will always contain the domain being - authenticated. For HTTP-01 and DNS-01, $CERTBOT_VALIDATION is the - validation string, and $CERTBOT_TOKEN is the filename of the resource - requested when performing an HTTP-01 challenge. When performing a TLS- - SNI-01 challenge, $CERTBOT_SNI_DOMAIN will contain the SNI name for which - the ACME server expects to be presented with the self-signed certificate - located at $CERTBOT_CERT_PATH. The secret key needed to complete the TLS - handshake is located at $CERTBOT_KEY_PATH. An additional cleanup script - can also be provided and can use the additional variable - $CERTBOT_AUTH_OUTPUT which contains the stdout output from the auth - script. - - --manual-auth-hook MANUAL_AUTH_HOOK - Path or command to execute for the authentication - script (default: None) - --manual-cleanup-hook MANUAL_CLEANUP_HOOK - Path or command to execute for the cleanup script - (default: None) - --manual-public-ip-logging-ok - Automatically allows public IP logging (default: Ask) - -nginx: - Nginx Web Server plugin - - --nginx-server-root NGINX_SERVER_ROOT - Nginx server root directory. (default: /etc/nginx or - /usr/local/etc/nginx) - --nginx-ctl NGINX_CTL - Path to the 'nginx' binary, used for 'configtest' and - retrieving nginx version number. (default: nginx) - -null: - Null Installer - -standalone: - Spin up a temporary webserver - -webroot: - Place files in webroot directory - - --webroot-path WEBROOT_PATH, -w WEBROOT_PATH - public_html / webroot path. This can be specified - multiple times to handle different domains; each - domain will have the webroot path that preceded it. - For instance: `-w /var/www/example -d example.com -d - www.example.com -w /var/www/thing -d thing.net -d - m.thing.net` (default: Ask) - --webroot-map WEBROOT_MAP - JSON dictionary mapping domains to webroot paths; this - implies -d for each entry. You may need to escape this - from your shell. E.g.: --webroot-map - '{"eg1.is,m.eg1.is":"/www/eg1/", "eg2.is":"/www/eg2"}' - This option is merged with, but takes precedence over, - -w / -d entries. At present, if you put webroot-map in - a config file, it needs to be on a single line, like: - webroot-map = {"example.com":"/var/www"}. (default: - {}) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index c72d1c1cf..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,323 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Certbot documentation build configuration file, created by -# sphinx-quickstart on Sun Nov 23 20:35:21 2014. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import codecs -import os -import re -import sys - -import sphinx - - -here = os.path.abspath(os.path.dirname(__file__)) - -# read version number (and other metadata) from package init -init_fn = os.path.join(here, '..', 'certbot', '__init__.py') -with codecs.open(init_fn, encoding='utf8') as fd: - meta = dict(re.findall(r"""__([a-z]+)__ = '([^']+)""", fd.read())) - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath(os.path.join(here, '..'))) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.2' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.viewcode', - 'repoze.sphinx.autointerface', -] - -if sphinx.version_info >= (1, 6): - extensions.append('sphinx.ext.imgconverter') - -autodoc_member_order = 'bysource' -autodoc_default_flags = ['show-inheritance', 'private-members'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Certbot' -# this is now overridden by the footer.html template -#copyright = u'2014-2018 - The Certbot software and documentation are licensed under the Apache 2.0 license as described at https://eff.org/cb-license.' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '.'.join(meta['version'].split('.')[:2]) -# The full version, including alpha/beta/rc tags. -release = meta['version'] - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -default_role = 'py:obj' - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - -suppress_warnings = ['image.nonlocal_uri'] - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. - -# http://docs.readthedocs.org/en/latest/theme.html#how-do-i-use-this-locally-and-on-read-the-docs -# on_rtd is whether we are on readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -# otherwise, readthedocs.org uses their theme by default, so no need to specify it - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# Now only 'ja' uses this config value -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Certbotdoc' - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - #'preamble': '', - - # Latex figure (float) alignment - #'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ('index', 'Certbot.tex', u'Certbot Documentation', - u'Certbot Project', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'certbot', u'Certbot Documentation', - [project], 7), - ('man/certbot', 'certbot', u'certbot script documentation', - [project], 1), -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'Certbot', u'Certbot Documentation', - u'Certbot Project', 'Certbot', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False - - -intersphinx_mapping = { - 'python': ('https://docs.python.org/', None), - 'acme': ('https://acme-python.readthedocs.org/en/latest/', None), -} diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index 264db630f..000000000 --- a/docs/contributing.rst +++ /dev/null @@ -1,494 +0,0 @@ -=============== -Developer Guide -=============== - -.. contents:: Table of Contents - :local: - - -.. _getting_started: - -Getting Started -=============== - -Certbot has the same :ref:`system requirements <system_requirements>` when set -up for development. While the section below will help you install Certbot and -its dependencies, Certbot needs to be run on a UNIX-like OS so if you're using -Windows, you'll need to set up a (virtual) machine running an OS such as Linux -and continue with these instructions on that UNIX-like OS. - -Running a local copy of the client ----------------------------------- - -Running the client in developer mode from your local tree is a little different -than running Certbot as a user. To get set up, clone our git repository by -running: - -.. code-block:: shell - - git clone https://github.com/certbot/certbot - -If you're on macOS, we recommend you skip the rest of this section and instead -run Certbot in Docker. You can find instructions for how to do this :ref:`here -<docker-dev>`. If you're running on Linux, you can run the following commands to -install dependencies and set up a virtual environment where you can run -Certbot. - -.. code-block:: shell - - cd certbot - ./certbot-auto --debug --os-packages-only - python tools/venv.py - -If you have Python3 available and want to use it, run the ``venv3.py`` script. - -.. code-block:: shell - - python tools/venv3.py - -.. note:: You may need to repeat this when - Certbot's dependencies change or when a new plugin is introduced. - -You can now run the copy of Certbot from git either by executing -``venv/bin/certbot``, or by activating the virtual environment. You can do the -latter by running: - -.. code-block:: shell - - source venv/bin/activate - # or - source venv3/bin/activate - -After running this command, ``certbot`` and development tools like ``ipdb``, -``ipython``, ``pytest``, and ``tox`` are available in the shell where you ran -the command. These tools are installed in the virtual environment and are kept -separate from your global Python installation. This works by setting -environment variables so the right executables are found and Python can pull in -the versions of various packages needed by Certbot. More information can be -found in the `virtualenv docs`_. - -.. _`virtualenv docs`: https://virtualenv.pypa.io - -Find issues to work on ----------------------- - -You can find the open issues in the `github issue tracker`_. Comparatively -easy ones are marked `good first issue`_. If you're starting work on -something, post a comment to let others know and seek feedback on your plan -where appropriate. - -Once you've got a working branch, you can open a pull request. All changes in -your pull request must have thorough unit test coverage, pass our -tests, and be compliant with the :ref:`coding style <coding-style>`. - -.. _github issue tracker: https://github.com/certbot/certbot/issues -.. _good first issue: https://github.com/certbot/certbot/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22 - -.. _testing: - -Testing -------- - -When you are working in a file ``foo.py``, there should also be a file ``foo_test.py`` -either in the same directory as ``foo.py`` or in the ``tests`` subdirectory -(if there isn't, make one). While you are working on your code and tests, run -``python foo_test.py`` to run the relevant tests. - -For debugging, we recommend putting -``import ipdb; ipdb.set_trace()`` statements inside the source code. - -Once you are done with your code changes, and the tests in ``foo_test.py`` pass, -run all of the unittests for Certbot with ``tox -e py27`` (this uses Python -2.7). - -Once all the unittests pass, check for sufficient test coverage using -``tox -e cover``, and then check for code style with ``tox -e lint`` (all files) -or ``pylint --rcfile=.pylintrc path/to/file.py`` (single file at a time). - -Once all of the above is successful, you may run the full test suite using -``tox --skip-missing-interpreters``. We recommend running the commands above -first, because running all tests like this is very slow, and the large amount -of output can make it hard to find specific failures when they happen. - -.. warning:: The full test suite may attempt to modify your system's Apache - config if your user has sudo permissions, so it should not be run on a - production Apache server. - -.. _integration: - -Integration testing with the Boulder CA -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Generally it is sufficient to open a pull request and let Github and Travis run -integration tests for you, however, if you want to run them locally you need -Docker and docker-compose installed and working. Fetch and start Boulder, Let's -Encrypt's ACME CA software, by using: - -.. code-block:: shell - - ./tests/boulder-fetch.sh - -If you have problems with Docker, you may want to try `removing all containers and -volumes`_ and making sure you have at least 1GB of memory. - -Set up a certbot_test alias that enables easily running against the local -Boulder: - -.. code-block:: shell - - export SERVER=http://localhost:4000/directory - source tests/integration/_common.sh - -Run the integration tests using: - -.. code-block:: shell - - ./tests/boulder-integration.sh - -.. _removing all containers and volumes: https://www.digitalocean.com/community/tutorials/how-to-remove-docker-images-containers-and-volumes - -Code components and layout -========================== - -acme - contains all protocol specific code -certbot - main client code -certbot-apache and certbot-nginx - client code to configure specific web servers -certbot.egg-info - configuration for packaging Certbot - - -Plugin-architecture -------------------- - -Certbot has a plugin architecture to facilitate support for -different webservers, other TLS servers, and operating systems. -The interfaces available for plugins to implement are defined in -`interfaces.py`_ and `plugins/common.py`_. - -The main two plugin interfaces are `~certbot.interfaces.IAuthenticator`, which -implements various ways of proving domain control to a certificate authority, -and `~certbot.interfaces.IInstaller`, which configures a server to use a -certificate once it is issued. Some plugins, like the built-in Apache and Nginx -plugins, implement both interfaces and perform both tasks. Others, like the -built-in Standalone authenticator, implement just one interface. - -There are also `~certbot.interfaces.IDisplay` plugins, -which can change how prompts are displayed to a user. - -.. _interfaces.py: https://github.com/certbot/certbot/blob/master/certbot/interfaces.py -.. _plugins/common.py: https://github.com/certbot/certbot/blob/master/certbot/plugins/common.py#L34 - - -Authenticators --------------- - -Authenticators are plugins that prove control of a domain name by solving a -challenge provided by the ACME server. ACME currently defines several types of -challenges: HTTP, TLS-SNI (deprecated), TLS-ALPR, and DNS, represented by classes in `acme.challenges`. -An authenticator plugin should implement support for at least one challenge type. - -An Authenticator indicates which challenges it supports by implementing -`get_chall_pref(domain)` to return a sorted list of challenge types in -preference order. - -An Authenticator must also implement `perform(achalls)`, which "performs" a list -of challenges by, for instance, provisioning a file on an HTTP server, or -setting a TXT record in DNS. Once all challenges have succeeded or failed, -Certbot will call the plugin's `cleanup(achalls)` method to remove any files or -DNS records that were needed only during authentication. - -Installer ---------- - -Installers plugins exist to actually setup the certificate in a server, -possibly tweak the security configuration to make it more correct and secure -(Fix some mixed content problems, turn on HSTS, redirect to HTTPS, etc). -Installer plugins tell the main client about their abilities to do the latter -via the :meth:`~.IInstaller.supported_enhancements` call. We currently -have two Installers in the tree, the `~.ApacheConfigurator`. and the -`~.NginxConfigurator`. External projects have made some progress toward -support for IIS, Icecast and Plesk. - -Installers and Authenticators will oftentimes be the same class/object -(because for instance both tasks can be performed by a webserver like nginx) -though this is not always the case (the standalone plugin is an authenticator -that listens on port 80, but it cannot install certs; a postfix plugin would -be an installer but not an authenticator). - -Installers and Authenticators are kept separate because -it should be possible to use the `~.StandaloneAuthenticator` (it sets -up its own Python server to perform challenges) with a program that -cannot solve challenges itself (Such as MTA installers). - - -Installer Development ---------------------- - -There are a few existing classes that may be beneficial while -developing a new `~certbot.interfaces.IInstaller`. -Installers aimed to reconfigure UNIX servers may use Augeas for -configuration parsing and can inherit from `~.AugeasConfigurator` class -to handle much of the interface. Installers that are unable to use -Augeas may still find the `~.Reverter` class helpful in handling -configuration checkpoints and rollback. - - -.. _dev-plugin: - -Writing your own plugin -~~~~~~~~~~~~~~~~~~~~~~~ - -Certbot client supports dynamic discovery of plugins through the -`setuptools entry points`_ using the `certbot.plugins` group. This -way you can, for example, create a custom implementation of -`~certbot.interfaces.IAuthenticator` or the -`~certbot.interfaces.IInstaller` without having to merge it -with the core upstream source code. An example is provided in -``examples/plugins/`` directory. - -While developing, you can install your plugin into a Certbot development -virtualenv like this: - -.. code-block:: shell - - . venv/bin/activate - . tests/integration/_common.sh - pip install -e examples/plugins/ - certbot_test plugins - -Your plugin should show up in the output of the last command. If not, -it was not installed properly. - -Once you've finished your plugin and published it, you can have your -users install it system-wide with `pip install`. Note that this will -only work for users who have Certbot installed from OS packages or via -pip. Users who run `certbot-auto` are currently unable to use third-party -plugins. It's technically possible to install third-party plugins into -the virtualenv used by `certbot-auto`, but they will be wiped away when -`certbot-auto` upgrades. - -.. warning:: Please be aware though that as this client is still in a - developer-preview stage, the API may undergo a few changes. If you - believe the plugin will be beneficial to the community, please - consider submitting a pull request to the repo and we will update - it with any necessary API changes. - -.. _`setuptools entry points`: - http://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points - -.. _coding-style: - -Coding style -============ - -Please: - -1. **Be consistent with the rest of the code**. - -2. Read `PEP 8 - Style Guide for Python Code`_. - -3. Follow the `Google Python Style Guide`_, with the exception that we - use `Sphinx-style`_ documentation:: - - def foo(arg): - """Short description. - - :param int arg: Some number. - - :returns: Argument - :rtype: int - - """ - return arg - -4. Remember to use ``pylint``. - -.. _Google Python Style Guide: - https://google.github.io/styleguide/pyguide.html -.. _Sphinx-style: http://sphinx-doc.org/ -.. _PEP 8 - Style Guide for Python Code: - https://www.python.org/dev/peps/pep-0008 - -Mypy type annotations -===================== - -Certbot uses the `mypy`_ static type checker. Python 3 natively supports official type annotations, -which can then be tested for consistency using mypy. Python 2 doesn’t, but type annotations can -be `added in comments`_. Mypy does some type checks even without type annotations; we can find -bugs in Certbot even without a fully annotated codebase. - -Certbot supports both Python 2 and 3, so we’re using Python 2-style annotations. - -Zulip wrote a `great guide`_ to using mypy. It’s useful, but you don’t have to read the whole thing -to start contributing to Certbot. - -To run mypy on Certbot, use ``tox -e mypy`` on a machine that has Python 3 installed. - -Note that instead of just importing ``typing``, due to packaging issues, in Certbot we import from -``acme.magic_typing`` and have to add some comments for pylint like this: - -.. code-block:: python - - from acme.magic_typing import Dict # pylint: disable=unused-import, no-name-in-module - -Also note that OpenSSL, which we rely on, has type definitions for crypto but not SSL. We use both. -Those imports should look like this: - -.. code-block:: python - - from OpenSSL import crypto - from OpenSSL import SSL # type: ignore # https://github.com/python/typeshed/issues/2052 - -.. _mypy: https://mypy.readthedocs.io -.. _added in comments: https://mypy.readthedocs.io/en/latest/cheat_sheet.html -.. _great guide: https://blog.zulip.org/2016/10/13/static-types-in-python-oh-mypy/ - -Submitting a pull request -========================= - -Steps: - -1. Write your code! -2. Make sure your environment is set up properly and that you're in your - virtualenv. You can do this by running ``pip tools/venv.py``. - (this is a **very important** step) -3. Run ``tox -e lint`` to check for pylint errors. Fix any errors. -4. Run ``tox --skip-missing-interpreters`` to run the entire test suite - including coverage. The ``--skip-missing-interpreters`` argument ignores - missing versions of Python needed for running the tests. Fix any errors. -5. Submit the PR. Once your PR is open, please do not force push to the branch - containing your pull request to squash or amend commits. We use `squash - merges <https://github.com/blog/2141-squash-your-commits>`_ on PRs and - rewriting commits makes changes harder to track between reviews. -6. Did your tests pass on Travis? If they didn't, fix any errors. - -Asking for help -=============== - -If you have any questions while working on a Certbot issue, don't hesitate to -ask for help! You can do this in the #letsencrypt-dev IRC channel on Freenode. -If you don't already have an IRC client set up, we recommend you join using -`Riot <https://riot.im/app/#/room/#freenode_#letsencrypt-dev:matrix.org>`_. - -Updating certbot-auto and letsencrypt-auto -========================================== - -Updating the scripts --------------------- -Developers should *not* modify the ``certbot-auto`` and ``letsencrypt-auto`` files -in the root directory of the repository. Rather, modify the -``letsencrypt-auto.template`` and associated platform-specific shell scripts in -the ``letsencrypt-auto-source`` and -``letsencrypt-auto-source/pieces/bootstrappers`` directory, respectively. - -Building letsencrypt-auto-source/letsencrypt-auto -------------------------------------------------- -Once changes to any of the aforementioned files have been made, the -``letsencrypt-auto-source/letsencrypt-auto`` script should be updated. In lieu of -manually updating this script, run the build script, which lives at -``letsencrypt-auto-source/build.py``: - -.. code-block:: shell - - python letsencrypt-auto-source/build.py - -Running ``build.py`` will update the ``letsencrypt-auto-source/letsencrypt-auto`` -script. Note that the ``certbot-auto`` and ``letsencrypt-auto`` scripts in the root -directory of the repository will remain **unchanged** after this script is run. -Your changes will be propagated to these files during the next release of -Certbot. - -Opening a PR ------------- -When opening a PR, ensure that the following files are committed: - -1. ``letsencrypt-auto-source/letsencrypt-auto.template`` and - ``letsencrypt-auto-source/pieces/bootstrappers/*`` -2. ``letsencrypt-auto-source/letsencrypt-auto`` (generated by ``build.py``) - -It might also be a good idea to double check that **no** changes were -inadvertently made to the ``certbot-auto`` or ``letsencrypt-auto`` scripts in the -root of the repository. These scripts will be updated by the core developers -during the next release. - - -Updating the documentation -========================== - -In order to generate the Sphinx documentation, run the following -commands: - -.. code-block:: shell - - make -C docs clean html man - -This should generate documentation in the ``docs/_build/html`` -directory. - -.. note:: If you skipped the "Getting Started" instructions above, - run ``pip install -e ".[docs]"`` to install Certbot's docs extras modules. - - -.. _docker-dev: - -Running the client with Docker -============================== - -You can use Docker Compose to quickly set up an environment for running and -testing Certbot. To install Docker Compose, follow the instructions at -https://docs.docker.com/compose/install/. - -.. note:: Linux users can simply run ``pip install docker-compose`` to get - Docker Compose after installing Docker Engine and activating your shell as - described in the :ref:`Getting Started <getting_started>` section. - -Now you can develop on your host machine, but run Certbot and test your changes -in Docker. When using ``docker-compose`` make sure you are inside your clone of -the Certbot repository. As an example, you can run the following command to -check for linting errors:: - - docker-compose run --rm --service-ports development bash -c 'tox -e lint' - -You can also leave a terminal open running a shell in the Docker container and -modify Certbot code in another window. The Certbot repo on your host machine is -mounted inside of the container so any changes you make immediately take -effect. To do this, run:: - - docker-compose run --rm --service-ports development bash - -Now running the check for linting errors described above is as easy as:: - - tox -e lint - -.. _prerequisites: - -Notes on OS dependencies -======================== - -OS-level dependencies can be installed like so: - -.. code-block:: shell - - ./certbot-auto --debug --os-packages-only - -In general... - -* ``sudo`` is required as a suggested way of running privileged process -* `Python`_ 2.7 or 3.4+ is required -* `Augeas`_ is required for the Python bindings -* ``virtualenv`` is used for managing other Python library dependencies - -.. _Python: https://wiki.python.org/moin/BeginnersGuide/Download -.. _Augeas: http://augeas.net/ -.. _Virtualenv: https://virtualenv.pypa.io - - -FreeBSD -------- - -FreeBSD by default uses ``tcsh``. In order to activate virtualenv (see -above), you will need a compatible shell, e.g. ``pkg install bash && -bash``. diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 17cde1adf..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -Welcome to the Certbot documentation! -================================================== - -.. toctree:: - :maxdepth: 2 - - intro - what - install - using - contributing - packaging - resources - -.. toctree:: - :maxdepth: 1 - - api - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 35b262482..000000000 --- a/docs/install.rst +++ /dev/null @@ -1,291 +0,0 @@ -===================== -Get Certbot -===================== - -.. contents:: Table of Contents - :local: - - -About Certbot -============= - -*Certbot is meant to be run directly on a web server*, normally by a system administrator. In most cases, running Certbot on your personal computer is not a useful option. The instructions below relate to installing and running Certbot on a server. - -Certbot is packaged for many common operating systems and web servers. Check whether -``certbot`` (or ``letsencrypt``) is packaged for your web server's OS by visiting -certbot.eff.org_, where you will also find the correct installation instructions for -your system. - -.. Note:: Unless you have very specific requirements, we kindly suggest that you use the Certbot packages provided by your package manager (see certbot.eff.org_). If such packages are not available, we recommend using ``certbot-auto``, which automates the process of installing Certbot on your system. - -.. _certbot.eff.org: https://certbot.eff.org - - -.. _system_requirements: - -System Requirements -=================== - -Certbot currently requires Python 2.7 or 3.4+ running on a UNIX-like operating -system. By default, it requires root access in order to write to -``/etc/letsencrypt``, ``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to -bind to port 80 (if you use the ``standalone`` plugin) and to read and -modify webserver configurations (if you use the ``apache`` or ``nginx`` -plugins). If none of these apply to you, it is theoretically possible to run -without root privileges, but for most users who want to avoid running an ACME -client as root, either `letsencrypt-nosudo -<https://github.com/diafygi/letsencrypt-nosudo>`_ or `simp_le -<https://github.com/zenhack/simp_le>`_ are more appropriate choices. - -The Apache plugin currently requires an OS with augeas version 1.0; currently `it -supports -<https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/constants.py>`_ -modern OSes based on Debian, Fedora, SUSE, Gentoo and Darwin. - - -Additional integrity verification of certbot-auto script can be done by verifying its digital signature. -This requires a local installation of gpg2, which comes packaged in many Linux distributions under name gnupg or gnupg2. - - -Installing with ``certbot-auto`` requires 512MB of RAM in order to build some -of the dependencies. Installing from pre-built OS packages avoids this -requirement. You can also temporarily set a swap file. See "Problems with -Python virtual environment" below for details. - - -Alternate installation methods -================================ - -If you are offline or your operating system doesn't provide a package, you can use -an alternate method for installing ``certbot``. - -.. _certbot-auto: - -Certbot-Auto ------------- - -The ``certbot-auto`` wrapper script installs Certbot, obtaining some dependencies -from your web server OS and putting others in a python virtual environment. You can -download and run it as follows:: - - user@webserver:~$ wget https://dl.eff.org/certbot-auto - user@webserver:~$ chmod a+x ./certbot-auto - user@webserver:~$ ./certbot-auto --help - -To check the integrity of the ``certbot-auto`` script, -you can use these steps:: - - - user@webserver:~$ wget -N https://dl.eff.org/certbot-auto.asc - user@webserver:~$ gpg2 --keyserver pool.sks-keyservers.net --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 - user@webserver:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto - - - -The output of the last command should look something like:: - - - gpg: Signature made Wed 02 May 2018 05:29:12 AM IST - gpg: using RSA key A2CFB51FA275A7286234E7B24D17C995CD9775F2 - gpg: key 4D17C995CD9775F2 marked as ultimately trusted - gpg: checking the trustdb - gpg: marginals needed: 3 completes needed: 1 trust model: pgp - gpg: depth: 0 valid: 2 signed: 2 trust: 0-, 0q, 0n, 0m, 0f, 2u - gpg: depth: 1 valid: 2 signed: 0 trust: 2-, 0q, 0n, 0m, 0f, 0u - gpg: next trustdb check due at 2027-11-22 - gpg: Good signature from "Let's Encrypt Client Team <letsencrypt-client@eff.org>" [ultimate] - - - -The ``certbot-auto`` command updates to the latest client release automatically. -Since ``certbot-auto`` is a wrapper to ``certbot``, it accepts exactly -the same command line flags and arguments. For more information, see -`Certbot command-line options <https://certbot.eff.org/docs/using.html#command-line-options>`_. - -For full command line help, you can type:: - - ./certbot-auto --help all - -Problems with Python virtual environment ----------------------------------------- - -On a low memory system such as VPS with less than 512MB of RAM, the required dependencies of Certbot will fail to build. -This can be identified if the pip outputs contains something like ``internal compiler error: Killed (program cc1)``. -You can workaround this restriction by creating a temporary swapfile:: - - user@webserver:~$ sudo fallocate -l 1G /tmp/swapfile - user@webserver:~$ sudo chmod 600 /tmp/swapfile - user@webserver:~$ sudo mkswap /tmp/swapfile - user@webserver:~$ sudo swapon /tmp/swapfile - -Disable and remove the swapfile once the virtual environment is constructed:: - - user@webserver:~$ sudo swapoff /tmp/swapfile - user@webserver:~$ sudo rm /tmp/swapfile - -.. _docker-user: - -Running with Docker -------------------- - -Docker_ is an amazingly simple and quick way to obtain a -certificate. However, this mode of operation is unable to install -certificates or configure your webserver, because our installer -plugins cannot reach your webserver from inside the Docker container. - -Most users should use the operating system packages (see instructions at -certbot.eff.org_) or, as a fallback, ``certbot-auto``. You should only -use Docker if you are sure you know what you are doing and have a -good reason to do so. - -You should definitely read the :ref:`where-certs` section, in order to -know how to manage the certs -manually. `Our ciphersuites page <ciphers.html>`__ -provides some information about recommended ciphersuites. If none of -these make much sense to you, you should definitely use the -certbot-auto_ method, which enables you to use installer plugins -that cover both of those hard topics. - -If you're still not convinced and have decided to use this method, from -the server that the domain you're requesting a certficate for resolves -to, `install Docker`_, then issue a command like the one found below. If -you are using Certbot with the :ref:`Standalone` plugin, you will need -to make the port it uses accessible from outside of the container by -including something like ``-p 80:80`` or ``-p 443:443`` on the command -line before ``certbot/certbot``. - -.. code-block:: shell - - sudo docker run -it --rm --name certbot \ - -v "/etc/letsencrypt:/etc/letsencrypt" \ - -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ - certbot/certbot certonly - -Running Certbot with the ``certonly`` command will obtain a certificate and place it in the directory -``/etc/letsencrypt/live`` on your system. Because Certonly cannot install the certificate from -within Docker, you must install the certificate manually according to the procedure -recommended by the provider of your webserver. - -There are also Docker images for each of Certbot's DNS plugins available -at https://hub.docker.com/u/certbot which automate doing domain -validation over DNS for popular providers. To use one, just replace -``certbot/certbot`` in the command above with the name of the image you -want to use. For example, to use Certbot's plugin for Amazon Route 53, -you'd use ``certbot/dns-route53``. You may also need to add flags to -Certbot and/or mount additional directories to provide access to your -DNS API credentials as specified in the :ref:`DNS plugin documentation -<dns_plugins>`. If you would like to obtain a wildcard certificate from -Let's Encrypt's ACMEv2 server, you'll need to include ``--server -https://acme-v02.api.letsencrypt.org/directory`` on the command line as -well. - -For more information about the layout -of the ``/etc/letsencrypt`` directory, see :ref:`where-certs`. - -.. _Docker: https://docker.com -.. _`install Docker`: https://docs.docker.com/engine/installation/ - -Operating System Packages -------------------------- - -**Arch Linux** - -.. code-block:: shell - - sudo pacman -S certbot - -**Debian** - -If you run Debian Stretch or Debian Sid, you can install certbot packages. - -.. code-block:: shell - - sudo apt-get update - sudo apt-get install certbot python-certbot-apache - -If you don't want to use the Apache plugin, you can omit the -``python-certbot-apache`` package. Or you can install ``python-certbot-nginx`` instead. - -Packages exist for Debian Jessie via backports. First you'll have to follow the -instructions at http://backports.debian.org/Instructions/ to enable the Jessie backports -repo, if you have not already done so. Then run: - -.. code-block:: shell - - sudo apt-get install certbot python-certbot-apache -t jessie-backports - -**Fedora** - -.. code-block:: shell - - sudo dnf install certbot python2-certbot-apache - -**FreeBSD** - - * Port: ``cd /usr/ports/security/py-certbot && make install clean`` - * Package: ``pkg install py27-certbot`` - -**Gentoo** - -The official Certbot client is available in Gentoo Portage. If you -want to use the Apache plugin, it has to be installed separately: - -.. code-block:: shell - - emerge -av app-crypt/certbot - emerge -av app-crypt/certbot-apache - -When using the Apache plugin, you will run into a "cannot find an -SSLCertificateFile directive" or "cannot find an SSLCertificateKeyFile -directive for certificate" error if you're sporting the default Gentoo -``httpd.conf``. You can fix this by commenting out two lines in -``/etc/apache2/httpd.conf`` as follows: - -Change - -.. code-block:: shell - - <IfDefine SSL> - LoadModule ssl_module modules/mod_ssl.so - </IfDefine> - -to - -.. code-block:: shell - - #<IfDefine SSL> - LoadModule ssl_module modules/mod_ssl.so - #</IfDefine> - -For the time being, this is the only way for the Apache plugin to recognise -the appropriate directives when installing the certificate. -Note: this change is not required for the other plugins. - -**NetBSD** - - * Build from source: ``cd /usr/pkgsrc/security/py-certbot && make install clean`` - * Install pre-compiled package: ``pkg_add py27-certbot`` - -**OpenBSD** - - * Port: ``cd /usr/ports/security/letsencrypt/client && make install clean`` - * Package: ``pkg_add letsencrypt`` - -**Other Operating Systems** - -OS packaging is an ongoing effort. If you'd like to package -Certbot for your distribution of choice please have a -look at the :doc:`packaging`. - -Installing from source ----------------------- - -Installation from source is only supported for developers and the -whole process is described in the :doc:`contributing`. - -.. warning:: Please do **not** use ``python setup.py install``, ``python pip - install .``, or ``easy_install .``. Please do **not** attempt the - installation commands as superuser/root and/or without virtual environment, - e.g. ``sudo python setup.py install``, ``sudo pip install``, ``sudo - ./venv/bin/...``. These modes of operation might corrupt your operating - system and are **not supported** by the Certbot team! diff --git a/docs/intro.rst b/docs/intro.rst deleted file mode 100644 index 2d4abdc2d..000000000 --- a/docs/intro.rst +++ /dev/null @@ -1,10 +0,0 @@ -===================== -Introduction -===================== - -.. note:: - To get started quickly, use the `interactive installation guide <https://certbot.eff.org>`_. - -.. include:: ../README.rst - :start-after: tag:intro-begin - :end-before: tag:intro-end diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 198e864c3..000000000 --- a/docs/make.bat +++ /dev/null @@ -1,263 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -set I18NSPHINXOPTS=%SPHINXOPTS% . -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^<target^>` where ^<target^> is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. xml to make Docutils-native XML files - echo. pseudoxml to make pseudoxml-XML files for display purposes - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - echo. coverage to run coverage check of the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - - -REM Check if sphinx-build is available and fallback to Python version if any -%SPHINXBUILD% 2> nul -if errorlevel 9009 goto sphinx_python -goto sphinx_ok - -:sphinx_python - -set SPHINXBUILD=python -m sphinx.__init__ -%SPHINXBUILD% 2> nul -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -:sphinx_ok - - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\LetsEncrypt.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\LetsEncrypt.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -if "%1" == "coverage" ( - %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 - echo. - echo.Testing of coverage in the sources finished, look at the ^ -results in %BUILDDIR%/coverage/python.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -:end diff --git a/docs/man/certbot.rst b/docs/man/certbot.rst deleted file mode 100644 index d03f3eed4..000000000 --- a/docs/man/certbot.rst +++ /dev/null @@ -1 +0,0 @@ -.. literalinclude:: ../cli-help.txt diff --git a/docs/packaging.rst b/docs/packaging.rst deleted file mode 100644 index c13a14af3..000000000 --- a/docs/packaging.rst +++ /dev/null @@ -1,126 +0,0 @@ -=============== -Packaging Guide -=============== - -Releases -======== - -We release packages and upload them to PyPI (wheels and source tarballs). - -- https://pypi.python.org/pypi/acme -- https://pypi.python.org/pypi/certbot -- https://pypi.python.org/pypi/certbot-apache -- https://pypi.python.org/pypi/certbot-nginx -- https://pypi.python.org/pypi/certbot-dns-cloudflare -- https://pypi.python.org/pypi/certbot-dns-cloudxns -- https://pypi.python.org/pypi/certbot-dns-digitalocean -- https://pypi.python.org/pypi/certbot-dns-dnsimple -- https://pypi.python.org/pypi/certbot-dns-dnsmadeeasy -- https://pypi.python.org/pypi/certbot-dns-google -- https://pypi.python.org/pypi/certbot-dns-linode -- https://pypi.python.org/pypi/certbot-dns-luadns -- https://pypi.python.org/pypi/certbot-dns-nsone -- https://pypi.python.org/pypi/certbot-dns-ovh -- https://pypi.python.org/pypi/certbot-dns-rfc2136 -- https://pypi.python.org/pypi/certbot-dns-route53 - -The following scripts are used in the process: - -- https://github.com/letsencrypt/letsencrypt/blob/master/tools/release.sh - -We use git tags to identify releases, using `Semantic Versioning`_. For -example: `v0.11.1`. - -.. _`Semantic Versioning`: http://semver.org/ - -Notes for package maintainers -============================= - -0. Please use our tagged releases, not ``master``! - -1. Do not package ``certbot-compatibility-test`` or ``letshelp-certbot`` - it's only used internally. - -2. If you'd like to include automated renewal in your package ``certbot renew -q`` should be added to crontab or systemd timer. Additionally you should include a random per-machine time offset to avoid having a large number of your clients hit Let's Encrypt's servers simultaneously. - -3. ``jws`` is an internal script for ``acme`` module and it doesn't have to be packaged - it's mostly for debugging: you can use it as ``echo foo | jws sign | jws verify``. - -4. Do get in touch with us. We are happy to make any changes that will make packaging easier. If you need to apply some patches don't do it downstream - make a PR here. - -Already ongoing efforts -======================= - - -Arch ----- - -From our official releases: - -- https://www.archlinux.org/packages/community/any/python-acme -- https://www.archlinux.org/packages/community/any/certbot -- https://www.archlinux.org/packages/community/any/certbot-apache -- https://www.archlinux.org/packages/community/any/certbot-nginx -- https://www.archlinux.org/packages/community/any/certbot-dns-cloudflare -- https://www.archlinux.org/packages/community/any/certbot-dns-cloudxns -- https://www.archlinux.org/packages/community/any/certbot-dns-digitalocean -- https://www.archlinux.org/packages/community/any/certbot-dns-dnsimple -- https://www.archlinux.org/packages/community/any/certbot-dns-dnsmadeeasy -- https://www.archlinux.org/packages/community/any/certbot-dns-google -- https://www.archlinux.org/packages/community/any/certbot-dns-luadns -- https://www.archlinux.org/packages/community/any/certbot-dns-nsone -- https://www.archlinux.org/packages/community/any/certbot-dns-rfc2136 -- https://www.archlinux.org/packages/community/any/certbot-dns-route53 - -From ``master``: https://aur.archlinux.org/packages/certbot-git - -Debian (and its derivatives, including Ubuntu) ----------------------------------------------- - -- https://packages.debian.org/sid/certbot -- https://packages.debian.org/sid/python-certbot -- https://packages.debian.org/sid/python-certbot-apache - -Fedora ------- - -In Fedora 23+. - -- https://apps.fedoraproject.org/packages/python-acme -- https://apps.fedoraproject.org/packages/certbot -- https://apps.fedoraproject.org/packages/python-certbot-apache -- https://apps.fedoraproject.org/packages/python-certbot-dns-cloudflare -- https://apps.fedoraproject.org/packages/python-certbot-dns-cloudxns -- https://apps.fedoraproject.org/packages/python-certbot-dns-digitalocean -- https://apps.fedoraproject.org/packages/python-certbot-dns-dnsimple -- https://apps.fedoraproject.org/packages/python-certbot-dns-dnsmadeeasy -- https://apps.fedoraproject.org/packages/python-certbot-dns-google -- https://apps.fedoraproject.org/packages/python-certbot-dns-luadns -- https://apps.fedoraproject.org/packages/python-certbot-dns-nsone -- https://apps.fedoraproject.org/packages/python-certbot-dns-rfc2136 -- https://apps.fedoraproject.org/packages/python-certbot-dns-route53 -- https://apps.fedoraproject.org/packages/python-certbot-nginx - -FreeBSD -------- - -- https://www.freshports.org/security/py-acme/ -- https://www.freshports.org/security/py-certbot/ - -Gentoo ------- - -Currently, all ``certbot`` related packages are in the testing branch: - -- https://packages.gentoo.org/packages/app-crypt/certbot -- https://packages.gentoo.org/packages/app-crypt/certbot-apache -- https://packages.gentoo.org/packages/app-crypt/certbot-nginx -- https://packages.gentoo.org/packages/app-crypt/acme - -GNU Guix --------- - -- https://www.gnu.org/software/guix/package-list.html#certbot - -OpenBSD -------- - -- http://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/security/letsencrypt/client/ diff --git a/docs/resources.rst b/docs/resources.rst deleted file mode 100644 index 459d8a829..000000000 --- a/docs/resources.rst +++ /dev/null @@ -1,7 +0,0 @@ -===================== -Resources -===================== - -.. include:: ../README.rst - :start-after: tag:links-begin - :end-before: tag:links-end diff --git a/docs/using.rst b/docs/using.rst deleted file mode 100644 index e17e56b64..000000000 --- a/docs/using.rst +++ /dev/null @@ -1,996 +0,0 @@ -========== -User Guide -========== - -.. contents:: Table of Contents - :local: - -Certbot Commands -================ - -Certbot uses a number of different commands (also referred -to as "subcommands") to request specific actions such as -obtaining, renewing, or revoking certificates. The most important -and commonly-used commands will be discussed throughout this -document; an exhaustive list also appears near the end of the document. - -The ``certbot`` script on your web server might be named ``letsencrypt`` if your system uses an older package, or ``certbot-auto`` if you used an alternate installation method. Throughout the docs, whenever you see ``certbot``, swap in the correct name as needed. - -.. _plugins: - -Getting certificates (and choosing plugins) -=========================================== - -The Certbot client supports two types of plugins for -obtaining and installing certificates: authenticators and installers. - -Authenticators are plugins used with the ``certonly`` command to obtain a certificate. -The authenticator validates that you -control the domain(s) you are requesting a certificate for, obtains a certificate for the specified -domain(s), and places the certificate in the ``/etc/letsencrypt`` directory on your -machine. The authenticator does not install the certificate (it does not edit any of your server's configuration files to serve the -obtained certificate). If you specify multiple domains to authenticate, they will -all be listed in a single certificate. To obtain multiple separate certificates -you will need to run Certbot multiple times. - -Installers are Plugins used with the ``install`` command to install a certificate. -These plugins can modify your webserver's configuration to -serve your website over HTTPS using certificates obtained by certbot. - -Plugins that do both can be used with the ``certbot run`` command, which is the default -when no command is specified. The ``run`` subcommand can also be used to specify -a combination_ of distinct authenticator and installer plugins. - -=========== ==== ==== =============================================================== ============================= -Plugin Auth Inst Notes Challenge types (and port) -=========== ==== ==== =============================================================== ============================= -apache_ Y Y | Automates obtaining and installing a certificate with Apache. http-01_ (80) -nginx_ Y Y | Automates obtaining and installing a certificate with Nginx. http-01_ (80) -webroot_ Y N | Obtains a certificate by writing to the webroot directory of http-01_ (80) - | an already running webserver. -standalone_ Y N | Uses a "standalone" webserver to obtain a certificate. http-01_ (80) - | Requires port 80 to be available. This is useful on - | systems with no webserver, or when direct integration with - | the local webserver is not supported or not desired. -|dns_plugs| Y N | This category of plugins automates obtaining a certificate by dns-01_ (53) - | modifying DNS records to prove you have control over a - | domain. Doing domain validation in this way is - | the only way to obtain wildcard certificates from Let's - | Encrypt. -manual_ Y N | Helps you obtain a certificate by giving you instructions to http-01_ (80) or - | perform domain validation yourself. Additionally allows you dns-01_ (53) - | to specify scripts to automate the validation task in a - | customized way. -=========== ==== ==== =============================================================== ============================= - -.. |dns_plugs| replace:: :ref:`DNS plugins <dns_plugins>` - -Under the hood, plugins use one of several ACME protocol challenges_ to -prove you control a domain. The options are http-01_ (which uses port 80) -and dns-01_ (requiring configuration of a DNS server on -port 53, though that's often not the same machine as your webserver). A few -plugins support more than one challenge type, in which case you can choose one -with ``--preferred-challenges``. - -There are also many third-party-plugins_ available. Below we describe in more detail -the circumstances in which each plugin can be used, and how to use it. - -.. _challenges: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7 -.. _http-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.2 -.. _dns-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.4 - -Apache ------- - -The Apache plugin currently `supports -<https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/entrypoint.py>`_ -modern OSes based on Debian, Fedora, SUSE, Gentoo and Darwin. -This automates both obtaining *and* installing certificates on an Apache -webserver. To specify this plugin on the command line, simply include -``--apache``. - -Webroot -------- - -If you're running a local webserver for which you have the ability -to modify the content being served, and you'd prefer not to stop the -webserver during the certificate issuance process, you can use the webroot -plugin to obtain a certificate by including ``certonly`` and ``--webroot`` on -the command line. In addition, you'll need to specify ``--webroot-path`` -or ``-w`` with the top-level directory ("web root") containing the files -served by your webserver. For example, ``--webroot-path /var/www/html`` -or ``--webroot-path /usr/share/nginx/html`` are two common webroot paths. - -If you're getting a certificate for many domains at once, the plugin -needs to know where each domain's files are served from, which could -potentially be a separate directory for each domain. When requesting a -certificate for multiple domains, each domain will use the most recently -specified ``--webroot-path``. So, for instance, - -:: - - certbot certonly --webroot -w /var/www/example -d www.example.com -d example.com -w /var/www/other -d other.example.net -d another.other.example.net - -would obtain a single certificate for all of those names, using the -``/var/www/example`` webroot directory for the first two, and -``/var/www/other`` for the second two. - -The webroot plugin works by creating a temporary file for each of your requested -domains in ``${webroot-path}/.well-known/acme-challenge``. Then the Let's Encrypt -validation server makes HTTP requests to validate that the DNS for each -requested domain resolves to the server running certbot. An example request -made to your web server would look like: - -:: - - 66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)" - -Note that to use the webroot plugin, your server must be configured to serve -files from hidden directories. If ``/.well-known`` is treated specially by -your webserver configuration, you might need to modify the configuration -to ensure that files inside ``/.well-known/acme-challenge`` are served by -the webserver. - -Nginx ------ - -The Nginx plugin should work for most configurations. We recommend backing up -Nginx configurations before using it (though you can also revert changes to -configurations with ``certbot --nginx rollback``). You can use it by providing -the ``--nginx`` flag on the commandline. - -:: - - certbot --nginx - -.. _standalone: - -Standalone ----------- - -Use standalone mode to obtain a certificate if you don't want to use (or don't currently have) -existing server software. The standalone plugin does not rely on any other server -software running on the machine where you obtain the certificate. - -To obtain a certificate using a "standalone" webserver, you can use the -standalone plugin by including ``certonly`` and ``--standalone`` -on the command line. This plugin needs to bind to port 80 in -order to perform domain validation, so you may need to stop your -existing webserver. - -It must still be possible for your machine to accept inbound connections from -the Internet on the specified port using each requested domain name. - -By default, Certbot first attempts to bind to the port for all interfaces using -IPv6 and then bind to that port using IPv4; Certbot continues so long as at -least one bind succeeds. On most Linux systems, IPv4 traffic will be routed to -the bound IPv6 port and the failure during the second bind is expected. - -Use ``--<challenge-type>-address`` to explicitly tell Certbot which interface -(and protocol) to bind. - -.. note:: The ``--standalone-supported-challenges`` option has been - deprecated since ``certbot`` version 0.9.0. - -.. _dns_plugins: - -DNS Plugins ------------ - -If you'd like to obtain a wildcard certificate from Let's Encrypt or run -``certbot`` on a machine other than your target webserver, you can use one of -Certbot's DNS plugins. - -These plugins are not included in a default Certbot installation and must be -installed separately. While the DNS plugins cannot currently be used with -``certbot-auto``, they are available in many OS package managers and as Docker -images. Visit https://certbot.eff.org to learn the best way to use the DNS -plugins on your system. - -Once installed, you can find documentation on how to use each plugin at: - -* `certbot-dns-cloudflare <https://certbot-dns-cloudflare.readthedocs.io>`_ -* `certbot-dns-cloudxns <https://certbot-dns-cloudxns.readthedocs.io>`_ -* `certbot-dns-digitalocean <https://certbot-dns-digitalocean.readthedocs.io>`_ -* `certbot-dns-dnsimple <https://certbot-dns-dnsimple.readthedocs.io>`_ -* `certbot-dns-dnsmadeeasy <https://certbot-dns-dnsmadeeasy.readthedocs.io>`_ -* `certbot-dns-google <https://certbot-dns-google.readthedocs.io>`_ -* `certbot-dns-linode <https://certbot-dns-linode.readthedocs.io>`_ -* `certbot-dns-luadns <https://certbot-dns-luadns.readthedocs.io>`_ -* `certbot-dns-nsone <https://certbot-dns-nsone.readthedocs.io>`_ -* `certbot-dns-ovh <https://certbot-dns-ovh.readthedocs.io>`_ -* `certbot-dns-rfc2136 <https://certbot-dns-rfc2136.readthedocs.io>`_ -* `certbot-dns-route53 <https://certbot-dns-route53.readthedocs.io>`_ - -Manual ------- - -If you'd like to obtain a certificate running ``certbot`` on a machine -other than your target webserver or perform the steps for domain -validation yourself, you can use the manual plugin. While hidden from -the UI, you can use the plugin to obtain a certificate by specifying -``certonly`` and ``--manual`` on the command line. This requires you -to copy and paste commands into another terminal session, which may -be on a different computer. - -The manual plugin can use either the ``http`` or the ``dns`` challenge. You can use the ``--preferred-challenges`` option -to choose the challenge of your preference. - -The ``http`` challenge will ask you to place a file with a specific name and -specific content in the ``/.well-known/acme-challenge/`` directory directly -in the top-level directory (“web root”) containing the files served by your -webserver. In essence it's the same as the webroot_ plugin, but not automated. - -When using the ``dns`` challenge, ``certbot`` will ask you to place a TXT DNS -record with specific contents under the domain name consisting of the hostname -for which you want a certificate issued, prepended by ``_acme-challenge``. - -For example, for the domain ``example.com``, a zone file entry would look like: - -:: - - _acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM" - - -Additionally you can specify scripts to prepare for validation and -perform the authentication procedure and/or clean up after it by using -the ``--manual-auth-hook`` and ``--manual-cleanup-hook`` flags. This is -described in more depth in the hooks_ section. - -.. _combination: - -Combining plugins ------------------ - -Sometimes you may want to specify a combination of distinct authenticator and -installer plugins. To do so, specify the authenticator plugin with -``--authenticator`` or ``-a`` and the installer plugin with ``--installer`` or -``-i``. - -For instance, you could create a certificate using the webroot_ plugin -for authentication and the apache_ plugin for installation. - -:: - - certbot run -a webroot -i apache -w /var/www/html -d example.com - -Or you could create a certificate using the manual_ plugin for authentication -and the nginx_ plugin for installation. (Note that this certificate cannot -be renewed automatically.) - -:: - - certbot run -a manual -i nginx -d example.com - -.. _third-party-plugins: - -Third-party plugins -------------------- - -There are also a number of third-party plugins for the client, provided by -other developers. Many are beta/experimental, but some are already in -widespread use: - -=========== ==== ==== =============================================================== -Plugin Auth Inst Notes -=========== ==== ==== =============================================================== -plesk_ Y Y Integration with the Plesk web hosting tool -haproxy_ Y Y Integration with the HAProxy load balancer -s3front_ Y Y Integration with Amazon CloudFront distribution of S3 buckets -gandi_ Y Y Integration with Gandi's hosting products and API -varnish_ Y N Obtain certificates via a Varnish server -external_ Y N A plugin for convenient scripting (See also ticket 2782_) -icecast_ N Y Deploy certificates to Icecast 2 streaming media servers -pritunl_ N Y Install certificates in pritunl distributed OpenVPN servers -proxmox_ N Y Install certificates in Proxmox Virtualization servers -postfix_ N Y STARTTLS Everywhere is becoming a Certbot Postfix/Exim plugin -heroku_ Y Y Integration with Heroku SSL -=========== ==== ==== =============================================================== - -.. _plesk: https://github.com/plesk/letsencrypt-plesk -.. _haproxy: https://github.com/greenhost/certbot-haproxy -.. _s3front: https://github.com/dlapiduz/letsencrypt-s3front -.. _gandi: https://github.com/Gandi/letsencrypt-gandi -.. _icecast: https://github.com/e00E/lets-encrypt-icecast -.. _varnish: http://git.sesse.net/?p=letsencrypt-varnish-plugin -.. _2782: https://github.com/certbot/certbot/issues/2782 -.. _pritunl: https://github.com/kharkevich/letsencrypt-pritunl -.. _proxmox: https://github.com/kharkevich/letsencrypt-proxmox -.. _external: https://github.com/marcan/letsencrypt-external -.. _postfix: https://github.com/EFForg/starttls-everywhere -.. _heroku: https://github.com/gboudreau/certbot-heroku - -If you're interested, you can also :ref:`write your own plugin <dev-plugin>`. - -.. _managing-certs: - -Managing certificates -===================== - -To view a list of the certificates Certbot knows about, run -the ``certificates`` subcommand: - -``certbot certificates`` - -This returns information in the following format:: - - Found the following certs: - Certificate Name: example.com - Domains: example.com, www.example.com - Expiry Date: 2017-02-19 19:53:00+00:00 (VALID: 30 days) - Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem - Private Key Path: /etc/letsencrypt/live/example.com/privkey.pem - -``Certificate Name`` shows the name of the certificate. Pass this name -using the ``--cert-name`` flag to specify a particular certificate for the ``run``, -``certonly``, ``certificates``, ``renew``, and ``delete`` commands. Example:: - - certbot certonly --cert-name example.com - -.. _updating_certs: - -Re-creating and Updating Existing Certificates ----------------------------------------------- - -You can use ``certonly`` or ``run`` subcommands to request -the creation of a single new certificate even if you already have an -existing certificate with some of the same domain names. - -If a certificate is requested with ``run`` or ``certonly`` specifying a -certificate name that already exists, Certbot updates -the existing certificate. Otherwise a new certificate -is created and assigned the specified name. - -The ``--force-renewal``, ``--duplicate``, and ``--expand`` options -control Certbot's behavior when re-creating -a certificate with the same name as an existing certificate. -If you don't specify a requested behavior, Certbot may ask you what you intended. - - -``--force-renewal`` tells Certbot to request a new certificate -with the same domains as an existing certificate. Each domain -must be explicitly specified via ``-d``. If successful, this certificate -is saved alongside the earlier one and symbolic links (the "``live``" -reference) will be updated to point to the new certificate. This is a -valid method of renewing a specific individual -certificate. - -``--duplicate`` tells Certbot to create a separate, unrelated certificate -with the same domains as an existing certificate. This certificate is -saved completely separately from the prior one. Most users will not -need to issue this command in normal circumstances. - -``--expand`` tells Certbot to update an existing certificate with a new -certificate that contains all of the old domains and one or more additional -new domains. With the ``--expand`` option, use the ``-d`` option to specify -all existing domains and one or more new domains. - -Example: - -.. code-block:: none - - certbot --expand -d existing.com,example.com,newdomain.com - -If you prefer, you can specify the domains individually like this: - -.. code-block:: none - - certbot --expand -d existing.com -d example.com -d newdomain.com - -Consider using ``--cert-name`` instead of ``--expand``, as it gives more control -over which certificate is modified and it lets you remove domains as well as adding them. - - -``--allow-subset-of-names`` tells Certbot to continue with certificate generation if -only some of the specified domain authorizations can be obtained. This may -be useful if some domains specified in a certificate no longer point at this -system. - -Whenever you obtain a new certificate in any of these ways, the new -certificate exists alongside any previously obtained certificates, whether -or not the previous certificates have expired. The generation of a new -certificate counts against several rate limits that are intended to prevent -abuse of the ACME protocol, as described -`here <https://community.letsencrypt.org/t/rate-limits-for-lets-encrypt/6769>`__. - -.. _changing: - -Changing a Certificate's Domains -================================ - -The ``--cert-name`` flag can also be used to modify the domains a certificate contains, -by specifying new domains using the ``-d`` or ``--domains`` flag. If certificate ``example.com`` -previously contained ``example.com`` and ``www.example.com``, it can be modified to only -contain ``example.com`` by specifying only ``example.com`` with the ``-d`` or ``--domains`` flag. Example:: - - certbot certonly --cert-name example.com -d example.com - -The same format can be used to expand the set of domains a certificate contains, or to -replace that set entirely:: - - certbot certonly --cert-name example.com -d example.org,www.example.org - - -Revoking certificates ---------------------- - -If your account key has been compromised or you otherwise need to revoke a certificate, -use the ``revoke`` command to do so. Note that the ``revoke`` command takes the certificate path -(ending in ``cert.pem``), not a certificate name or domain. Example:: - - certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem - -You can also specify the reason for revoking your certificate by using the ``reason`` flag. -Reasons include ``unspecified`` which is the default, as well as ``keycompromise``, -``affiliationchanged``, ``superseded``, and ``cessationofoperation``:: - - certbot revoke --cert-path /etc/letsencrypt/live/CERTNAME/cert.pem --reason keycompromise - -Additionally, if a certificate -is a test certificate obtained via the ``--staging`` or ``--test-cert`` flag, that flag must be passed to the -``revoke`` subcommand. -Once a certificate is revoked (or for other certificate management tasks), all of a certificate's -relevant files can be removed from the system with the ``delete`` subcommand:: - - certbot delete --cert-name example.com - -.. note:: If you don't use ``delete`` to remove the certificate completely, it will be renewed automatically at the next renewal event. - -.. note:: Revoking a certificate will have no effect on the rate limit imposed by the Let's Encrypt server. - -.. _renewal: - -Renewing certificates ---------------------- - -.. note:: Let's Encrypt CA issues short-lived certificates (90 - days). Make sure you renew the certificates at least once in 3 - months. - -.. seealso:: Many of the certbot clients obtained through a - distribution come with automatic renewal out of the box, - such as Debian and Ubuntu versions installed through `apt`, - CentOS/RHEL 7 through EPEL, etc. See `Automated Renewals`_ - for more details. - -As of version 0.10.0, Certbot supports a ``renew`` action to check -all installed certificates for impending expiry and attempt to renew -them. The simplest form is simply - -``certbot renew`` - -This command attempts to renew any previously-obtained certificates that -expire in less than 30 days. The same plugin and options that were used -at the time the certificate was originally issued will be used for the -renewal attempt, unless you specify other plugins or options. Unlike ``certonly``, ``renew`` acts on -multiple certificates and always takes into account whether each one is near -expiry. Because of this, ``renew`` is suitable (and designed) for automated use, -to allow your system to automatically renew each certificate when appropriate. -Since ``renew`` only renews certificates that are near expiry it can be -run as frequently as you want - since it will usually take no action. - -The ``renew`` command includes hooks for running commands or scripts before or after a certificate is -renewed. For example, if you have a single certificate obtained using -the standalone_ plugin, you might need to stop the webserver -before renewing so standalone can bind to the necessary ports, and -then restart it after the plugin is finished. Example:: - - certbot renew --pre-hook "service nginx stop" --post-hook "service nginx start" - -If a hook exits with a non-zero exit code, the error will be printed -to ``stderr`` but renewal will be attempted anyway. A failing hook -doesn't directly cause Certbot to exit with a non-zero exit code, but -since Certbot exits with a non-zero exit code when renewals fail, a -failed hook causing renewal failures will indirectly result in a -non-zero exit code. Hooks will only be run if a certificate is due for -renewal, so you can run the above command frequently without -unnecessarily stopping your webserver. - -When Certbot detects that a certificate is due for renewal, ``--pre-hook`` -and ``--post-hook`` hooks run before and after each attempt to renew it. -If you want your hook to run only after a successful renewal, use -``--deploy-hook`` in a command like this. - -``certbot renew --deploy-hook /path/to/deploy-hook-script`` - -For example, if you have a daemon that does not read its certificates as the -root user, a deploy hook like this can copy them to the correct location and -apply appropriate file permissions. - -/path/to/deploy-hook-script - -.. code-block:: none - - #!/bin/sh - - set -e - - for domain in $RENEWED_DOMAINS; do - case $domain in - example.com) - daemon_cert_root=/etc/some-daemon/certs - - # Make sure the certificate and private key files are - # never world readable, even just for an instant while - # we're copying them into daemon_cert_root. - umask 077 - - cp "$RENEWED_LINEAGE/fullchain.pem" "$daemon_cert_root/$domain.cert" - cp "$RENEWED_LINEAGE/privkey.pem" "$daemon_cert_root/$domain.key" - - # Apply the proper file ownership and permissions for - # the daemon to read its certificate and key. - chown some-daemon "$daemon_cert_root/$domain.cert" \ - "$daemon_cert_root/$domain.key" - chmod 400 "$daemon_cert_root/$domain.cert" \ - "$daemon_cert_root/$domain.key" - - service some-daemon restart >/dev/null - ;; - esac - done - -You can also specify hooks by placing files in subdirectories of Certbot's -configuration directory. Assuming your configuration directory is -``/etc/letsencrypt``, any executable files found in -``/etc/letsencrypt/renewal-hooks/pre``, -``/etc/letsencrypt/renewal-hooks/deploy``, and -``/etc/letsencrypt/renewal-hooks/post`` will be run as pre, deploy, and post -hooks respectively when any certificate is renewed with the ``renew`` -subcommand. These hooks are run in alphabetical order and are not run for other -subcommands. (The order the hooks are run is determined by the byte value of -the characters in their filenames and is not dependent on your locale.) - -Hooks specified in the command line, :ref:`configuration file -<config-file>`, or :ref:`renewal configuration files <renewal-config-file>` are -run as usual after running all hooks in these directories. One minor exception -to this is if a hook specified elsewhere is simply the path to an executable -file in the hook directory of the same type (e.g. your pre-hook is the path to -an executable in ``/etc/letsencrypt/renewal-hooks/pre``), the file is not run a -second time. You can stop Certbot from automatically running executables found -in these directories by including ``--no-directory-hooks`` on the command line. - -More information about hooks can be found by running -``certbot --help renew``. - -If you're sure that this command executes successfully without human -intervention, you can add the command to ``crontab`` (since certificates -are only renewed when they're determined to be near expiry, the command -can run on a regular basis, like every week or every day). In that case, -you are likely to want to use the ``-q`` or ``--quiet`` quiet flag to -silence all output except errors. - -If you are manually renewing all of your certificates, the -``--force-renewal`` flag may be helpful; it causes the expiration time of -the certificate(s) to be ignored when considering renewal, and attempts to -renew each and every installed certificate regardless of its age. (This -form is not appropriate to run daily because each certificate will be -renewed every day, which will quickly run into the certificate authority -rate limit.) - -Note that options provided to ``certbot renew`` will apply to -*every* certificate for which renewal is attempted; for example, -``certbot renew --rsa-key-size 4096`` would try to replace every -near-expiry certificate with an equivalent certificate using a 4096-bit -RSA public key. If a certificate is successfully renewed using -specified options, those options will be saved and used for future -renewals of that certificate. - -An alternative form that provides for more fine-grained control over the -renewal process (while renewing specified certificates one at a time), -is ``certbot certonly`` with the complete set of subject domains of -a specific certificate specified via `-d` flags. You may also want to -include the ``-n`` or ``--noninteractive`` flag to prevent blocking on -user input (which is useful when running the command from cron). - -``certbot certonly -n -d example.com -d www.example.com`` - -All of the domains covered by the certificate must be specified in -this case in order to renew and replace the old certificate rather -than obtaining a new one; don't forget any `www.` domains! Specifying -a subset of the domains creates a new, separate certificate containing -only those domains, rather than replacing the original certificate. -When run with a set of domains corresponding to an existing certificate, -the ``certonly`` command attempts to renew that specific certificate. - -Please note that the CA will send notification emails to the address -you provide if you do not renew certificates that are about to expire. - -Certbot is working hard to improve the renewal process, and we -apologize for any inconvenience you encounter in integrating these -commands into your individual environment. - -.. note:: ``certbot renew`` exit status will only be 1 if a renewal attempt failed. - This means ``certbot renew`` exit status will be 0 if no certificate needs to be updated. - If you write a custom script and expect to run a command only after a certificate was actually renewed - you will need to use the ``--deploy-hook`` since the exit status will be 0 both on successful renewal - and when renewal is not necessary. - -.. _renewal-config-file: - - -Modifying the Renewal Configuration File ----------------------------------------- - -When a certificate is issued, by default Certbot creates a renewal configuration file that -tracks the options that were selected when Certbot was run. This allows Certbot -to use those same options again when it comes time for renewal. These renewal -configuration files are located at ``/etc/letsencrypt/renewal/CERTNAME``. - -For advanced certificate management tasks, it is possible to manually modify the certificate's -renewal configuration file, but this is discouraged since it can easily break Certbot's -ability to renew your certificates. If you choose to modify the renewal configuration file -we advise you to test its validity with the ``certbot renew --dry-run`` command. - -.. warning:: Modifying any files in ``/etc/letsencrypt`` can damage them so Certbot can no longer properly manage its certificates, and we do not recommend doing so. - -For most tasks, it is safest to limit yourself to pointing symlinks at the files there, or using -``--deploy-hook`` to copy / make new files based upon those files, if your operational situation requires it -(for instance, combining certificates and keys in different way, or having copies of things with different -specific permissions that are demanded by other programs). - -If the contents of ``/etc/letsencrypt/archive/CERTNAME`` are moved to a new folder, first specify -the new folder's name in the renewal configuration file, then run ``certbot update_symlinks`` to -point the symlinks in ``/etc/letsencrypt/live/CERTNAME`` to the new folder. - -If you would like the live certificate files whose symlink location Certbot updates on each run to -reside in a different location, first move them to that location, then specify the full path of -each of the four files in the renewal configuration file. Since the symlinks are relative links, -you must follow this with an invocation of ``certbot update_symlinks``. - -For example, say that a certificate's renewal configuration file previously contained the following -directives:: - - archive_dir = /etc/letsencrypt/archive/example.com - cert = /etc/letsencrypt/live/example.com/cert.pem - privkey = /etc/letsencrypt/live/example.com/privkey.pem - chain = /etc/letsencrypt/live/example.com/chain.pem - fullchain = /etc/letsencrypt/live/example.com/fullchain.pem - -The following commands could be used to specify where these files are located:: - - mv /etc/letsencrypt/archive/example.com /home/user/me/certbot/example_archive - sed -i 's,/etc/letsencrypt/archive/example.com,/home/user/me/certbot/example_archive,' /etc/letsencrypt/renewal/example.com.conf - mv /etc/letsencrypt/live/example.com/*.pem /home/user/me/certbot/ - sed -i 's,/etc/letsencrypt/live/example.com,/home/user/me/certbot,g' /etc/letsencrypt/renewal/example.com.conf - certbot update_symlinks - -Automated Renewals ------------------- - -Many Linux distributions provide automated renewal when you use the -packages installed through their system package manager. The -following table is an *incomplete* list of distributions which do so, -as well as their methods for doing so. - -If you are not sure whether or not your system has this already -automated, refer to your distribution's documentation, or check your -system's crontab (typically in `/etc/crontab/` and `/etc/cron.*/*` and -systemd timers (`systemctl list-timers`). - -.. csv-table:: Distributions with Automated Renewal - :header: "Distribution Name", "Distribution Version", "Automation Method" - - "CentOS", "EPEL 7", "systemd" - "Debian", "jessie", "cron, systemd" - "Debian", "stretch", "cron, systemd" - "Debian", "testing/sid", "cron, systemd" - "Fedora", "26", "systemd" - "Fedora", "27", "systemd" - "RHEL", "EPEL 7", "systemd" - "Ubuntu", "17.10", "cron, systemd" - "Ubuntu", "certbot PPA", "cron, systemd" - -.. _where-certs: - -Where are my certificates? -========================== - -All generated keys and issued certificates can be found in -``/etc/letsencrypt/live/$domain``. In the case of creating a SAN certificate -with multiple alternative names, ``$domain`` is the first domain passed in -via -d parameter. Rather than copying, please point -your (web) server configuration directly to those files (or create -symlinks). During the renewal_, ``/etc/letsencrypt/live`` is updated -with the latest necessary files. - -.. note:: ``/etc/letsencrypt/archive`` and ``/etc/letsencrypt/keys`` - contain all previous keys and certificates, while - ``/etc/letsencrypt/live`` symlinks to the latest versions. - -The following files are available: - -``privkey.pem`` - Private key for the certificate. - - .. warning:: This **must be kept secret at all times**! Never share - it with anyone, including Certbot developers. You cannot - put it into a safe, however - your server still needs to access - this file in order for SSL/TLS to work. - - .. note:: As of Certbot version 0.29.0, private keys for new certificate - default to ``0600``. Any changes to the group mode or group owner (gid) - of this file will be preserved on renewals. - - This is what Apache needs for `SSLCertificateKeyFile - <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatekeyfile>`_, - and Nginx for `ssl_certificate_key - <http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key>`_. - -``fullchain.pem`` - All certificates, **including** server certificate (aka leaf certificate or - end-entity certificate). The server certificate is the first one in this file, - followed by any intermediates. - - This is what Apache >= 2.4.8 needs for `SSLCertificateFile - <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_, - and what Nginx needs for `ssl_certificate - <http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate>`_. - -``cert.pem`` and ``chain.pem`` (less common) - ``cert.pem`` contains the server certificate by itself, and - ``chain.pem`` contains the additional intermediate certificate or - certificates that web browsers will need in order to validate the - server certificate. If you provide one of these files to your web - server, you **must** provide both of them, or some browsers will show - "This Connection is Untrusted" errors for your site, `some of the time - <https://whatsmychaincert.com/>`_. - - Apache < 2.4.8 needs these for `SSLCertificateFile - <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_. - and `SSLCertificateChainFile - <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatechainfile>`_, - respectively. - - If you're using OCSP stapling with Nginx >= 1.3.7, ``chain.pem`` should be - provided as the `ssl_trusted_certificate - <http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate>`_ - to validate OCSP responses. - -.. note:: All files are PEM-encoded. - If you need other format, such as DER or PFX, then you - could convert using ``openssl``. You can automate that with - ``--deploy-hook`` if you're using automatic renewal_. - -.. _hooks: - -Pre and Post Validation Hooks -============================= - -Certbot allows for the specification of pre and post validation hooks when run -in manual mode. The flags to specify these scripts are ``--manual-auth-hook`` -and ``--manual-cleanup-hook`` respectively and can be used as follows: - -:: - - certbot certonly --manual --manual-auth-hook /path/to/http/authenticator.sh --manual-cleanup-hook /path/to/http/cleanup.sh -d secure.example.com - -This will run the ``authenticator.sh`` script, attempt the validation, and then run -the ``cleanup.sh`` script. Additionally certbot will pass relevant environment -variables to these scripts: - -- ``CERTBOT_DOMAIN``: The domain being authenticated -- ``CERTBOT_VALIDATION``: The validation string (HTTP-01 and DNS-01 only) -- ``CERTBOT_TOKEN``: Resource name part of the HTTP-01 challenge (HTTP-01 only) - -Additionally for cleanup: - -- ``CERTBOT_AUTH_OUTPUT``: Whatever the auth script wrote to stdout - -Example usage for HTTP-01: - -:: - - certbot certonly --manual --preferred-challenges=http --manual-auth-hook /path/to/http/authenticator.sh --manual-cleanup-hook /path/to/http/cleanup.sh -d secure.example.com - -/path/to/http/authenticator.sh - -.. code-block:: none - - #!/bin/bash - echo $CERTBOT_VALIDATION > /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN - -/path/to/http/cleanup.sh - -.. code-block:: none - - #!/bin/bash - rm -f /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN - -Example usage for DNS-01 (Cloudflare API v4) (for example purposes only, do not use as-is) - -:: - - certbot certonly --manual --preferred-challenges=dns --manual-auth-hook /path/to/dns/authenticator.sh --manual-cleanup-hook /path/to/dns/cleanup.sh -d secure.example.com - -/path/to/dns/authenticator.sh - -.. code-block:: none - - #!/bin/bash - - # Get your API key from https://www.cloudflare.com/a/account/my-account - API_KEY="your-api-key" - EMAIL="your.email@example.com" - - # Strip only the top domain to get the zone id - DOMAIN=$(expr match "$CERTBOT_DOMAIN" '.*\.\(.*\..*\)') - - # Get the Cloudflare zone id - ZONE_EXTRA_PARAMS="status=active&page=1&per_page=20&order=status&direction=desc&match=all" - ZONE_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones?name=$DOMAIN&$ZONE_EXTRA_PARAMS" \ - -H "X-Auth-Email: $EMAIL" \ - -H "X-Auth-Key: $API_KEY" \ - -H "Content-Type: application/json" | python -c "import sys,json;print(json.load(sys.stdin)['result'][0]['id'])") - - # Create TXT record - CREATE_DOMAIN="_acme-challenge.$CERTBOT_DOMAIN" - RECORD_ID=$(curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \ - -H "X-Auth-Email: $EMAIL" \ - -H "X-Auth-Key: $API_KEY" \ - -H "Content-Type: application/json" \ - --data '{"type":"TXT","name":"'"$CREATE_DOMAIN"'","content":"'"$CERTBOT_VALIDATION"'","ttl":120}' \ - | python -c "import sys,json;print(json.load(sys.stdin)['result']['id'])") - # Save info for cleanup - if [ ! -d /tmp/CERTBOT_$CERTBOT_DOMAIN ];then - mkdir -m 0700 /tmp/CERTBOT_$CERTBOT_DOMAIN - fi - echo $ZONE_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID - echo $RECORD_ID > /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID - - # Sleep to make sure the change has time to propagate over to DNS - sleep 25 - -/path/to/dns/cleanup.sh - -.. code-block:: none - - #!/bin/bash - - # Get your API key from https://www.cloudflare.com/a/account/my-account - API_KEY="your-api-key" - EMAIL="your.email@example.com" - - if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID ]; then - ZONE_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID) - rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/ZONE_ID - fi - - if [ -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID ]; then - RECORD_ID=$(cat /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID) - rm -f /tmp/CERTBOT_$CERTBOT_DOMAIN/RECORD_ID - fi - - # Remove the challenge TXT record from the zone - if [ -n "${ZONE_ID}" ]; then - if [ -n "${RECORD_ID}" ]; then - curl -s -X DELETE "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" \ - -H "X-Auth-Email: $EMAIL" \ - -H "X-Auth-Key: $API_KEY" \ - -H "Content-Type: application/json" - fi - fi - -.. _lock-files: - -Changing the ACME Server -======================== - -By default, Certbot uses Let's Encrypt's initial production server at -https://acme-v01.api.letsencrypt.org/. You can tell Certbot to use a -different CA by providing ``--server`` on the command line or in a -:ref:`configuration file <config-file>` with the URL of the server's -ACME directory. For example, if you would like to use Let's Encrypt's -new ACMEv2 server, you would add ``--server -https://acme-v02.api.letsencrypt.org/directory`` to the command line. -Certbot will automatically select which version of the ACME protocol to -use based on the contents served at the provided URL. - -If you use ``--server`` to specify an ACME CA that implements a newer -version of the spec, you may be able to obtain a certificate for a -wildcard domain. Some CAs (such as Let's Encrypt) require that domain -validation for wildcard domains must be done through modifications to -DNS records which means that the dns-01_ challenge type must be used. To -see a list of Certbot plugins that support this challenge type and how -to use them, see plugins_. - -Lock Files -========== - -When processing a validation Certbot writes a number of lock files on your system -to prevent multiple instances from overwriting each other's changes. This means -that by default two instances of Certbot will not be able to run in parallel. - -Since the directories used by Certbot are configurable, Certbot -will write a lock file for all of the directories it uses. This include Certbot's -``--work-dir``, ``--logs-dir``, and ``--config-dir``. By default these are -``/var/lib/letsencrypt``, ``/var/log/letsencrypt``, and ``/etc/letsencrypt`` -respectively. Additionally if you are using Certbot with Apache or nginx it will -lock the configuration folder for that program, which are typically also in the -``/etc`` directory. - -Note that these lock files will only prevent other instances of Certbot from -using those directories, not other processes. If you'd like to run multiple -instances of Certbot simultaneously you should specify different directories -as the ``--work-dir``, ``--logs-dir``, and ``--config-dir`` for each instance -of Certbot that you would like to run. - -.. _config-file: - -Configuration file -================== - -Certbot accepts a global configuration file that applies its options to all invocations -of Certbot. Certificate specific configuration choices should be set in the ``.conf`` -files that can be found in ``/etc/letsencrypt/renewal``. - -By default no cli.ini file is created, after creating one -it is possible to specify the location of this configuration file with -``certbot-auto --config cli.ini`` (or shorter ``-c cli.ini``). An -example configuration file is shown below: - -.. include:: ../examples/cli.ini - :code: ini - -By default, the following locations are searched: - -- ``/etc/letsencrypt/cli.ini`` -- ``$XDG_CONFIG_HOME/letsencrypt/cli.ini`` (or - ``~/.config/letsencrypt/cli.ini`` if ``$XDG_CONFIG_HOME`` is not - set). - -Since this configuration file applies to all invocations of certbot it is incorrect -to list domains in it. Listing domains in cli.ini may prevent renewal from working. -Additionally due to how arguments in cli.ini are parsed, options which wish to -not be set should not be listed. Options set to false will instead be read -as being set to true by older versions of Certbot, since they have been listed -in the config file. - -.. keep it up to date with constants.py - -.. _log-rotation: - -Log Rotation -============ - -By default certbot stores status logs in ``/var/log/letsencrypt``. By default -certbot will begin rotating logs once there are 1000 logs in the log directory. -Meaning that once 1000 files are in ``/var/log/letsencrypt`` Certbot will delete -the oldest one to make room for new logs. The number of subsequent logs can be -changed by passing the desired number to the command line flag -``--max-log-backups``. - -.. note:: Some distributions, including Debian and Ubuntu, disable - certbot's internal log rotation in favor of a more traditional - logrotate script. If you are using a distribution's packages and - want to alter the log rotation, check `/etc/logrotate.d/` for a - certbot rotation script. - -.. _command-line: - -Certbot command-line options -============================ - -Certbot supports a lot of command line options. Here's the full list, from -``certbot --help all``: - -.. literalinclude:: cli-help.txt - -Getting help -============ - -If you're having problems, we recommend posting on the Let's Encrypt -`Community Forum <https://community.letsencrypt.org>`_. - -If you find a bug in the software, please do report it in our `issue -tracker <https://github.com/certbot/certbot/issues>`_. Remember to -give us as much information as possible: - -- copy and paste exact command line used and the output (though mind - that the latter might include some personally identifiable - information, including your email and domains) -- copy and paste logs from ``/var/log/letsencrypt`` (though mind they - also might contain personally identifiable information) -- copy and paste ``certbot --version`` output -- your operating system, including specific version -- specify which installation method you've chosen diff --git a/docs/what.rst b/docs/what.rst deleted file mode 100644 index 3d33346c2..000000000 --- a/docs/what.rst +++ /dev/null @@ -1,31 +0,0 @@ -====================== -What is a Certificate? -====================== - -A public key or digital *certificate* (formerly called an SSL certificate) uses a public key -and a private key to enable secure communication between a client program (web browser, email client, -etc.) and a server over an encrypted SSL (secure socket layer) or TLS (transport layer security) connection. -The certificate is used both to encrypt the initial stage of communication (secure key exchange) -and to identify the server. The certificate -includes information about the key, information about the server identity, and the digital signature -of the certificate issuer. If the issuer is trusted by the software that initiates the communication, -and the signature is valid, then the key can be used to communicate securely with the server identified by -the certificate. Using a certificate is a good way to prevent "man-in-the-middle" attacks, in which -someone in between you and the server you think you are talking to is able to insert their own (harmful) -content. - -You can use Certbot to easily obtain and configure a free certificate from Let's Encrypt, a -joint project of EFF, Mozilla, and many other sponsors. - -Certificates and Lineages -========================= - -Certbot introduces the concept of a *lineage,* which is a collection of all the versions of a certificate -plus Certbot configuration information maintained for that certificate from -renewal to renewal. Whenever you renew a certificate, Certbot keeps the same configuration unless -you explicitly change it, for example by adding or removing domains. If you add domains, you can -either add them to an existing lineage or create -a new one. - -See also: -:ref:`updating_certs` |