From eff373f7ecc9703e053426dc04bc1900cd0218d1 Mon Sep 17 00:00:00 2001 From: Peter Conrad Date: Fri, 15 Dec 2017 11:27:00 -0800 Subject: [PATCH] Restructured RST files significantly. Next commit will be a pass through the content. --- README.rst | 61 ++-- docs/challenges.rst | 91 +++--- docs/contributing.rst | 126 ++++---- docs/index.rst | 21 +- docs/install.rst | 323 ++++++++++++++++---- docs/intro.rst | 14 +- docs/using.rst | 694 ++++++------------------------------------ docs/what.rst | 13 +- 8 files changed, 520 insertions(+), 823 deletions(-) diff --git a/README.rst b/README.rst index a18028aee..042697fa6 100644 --- a/README.rst +++ b/README.rst @@ -1,10 +1,13 @@ -.. This file contains a series of comments that are used to include sections of this README in other files. Do not modify these comments unless you know what you are doing. tag:intro-begin +s file contains a series of comments that are used to include sections of this README in other files. Do not modify these comments unless you know what you are doing. tag:intro-begin Certbot is part of EFF’s effort to encrypt the entire Internet. Secure communication over the Web relies on HTTPS, which requires the use of a digital certificate that lets browsers verify the identity of web servers (e.g., is that really google.com?). Web servers obtain their certificates from trusted third parties called certificate authorities (CAs). Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. Anyone who has gone through the trouble of setting up a secure website knows what a hassle getting and maintaining a certificate is. Certbot and Let’s Encrypt can automate away the pain and let you turn on and manage HTTPS with simple commands. Using Certbot and Let's Encrypt is free, so there’s no need to arrange payment. -How you use Certbot depends on the configuration of your web server. The best way to get started is to use our `interactive guide `_. It generates instructions based on your configuration settings. In most cases, you’ll need `root or administrator access `_ to your web server to run Certbot. +.. Note:: The best way to get started is to use our `interactive Guide `_. + +The Interactive Guide generates instructions based on your web server and operating system. +In most cases, you’ll need `root or administrator access `_ to your web server to run Certbot. If you’re using a hosted service and don’t have direct access to your web server, you might not be able to use Certbot. Check with your hosting provider for documentation about uploading certificates or using certificates issued by Let’s Encrypt. @@ -22,6 +25,16 @@ Until May 2016, Certbot was named simply ``letsencrypt`` or ``letsencrypt-auto`` depending on install method. Instructions on the Internet, and some pieces of the software, may still refer to this older name. +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 + + Contributing ------------ @@ -48,7 +61,7 @@ interactively. For full command line help, you can type:: - ./certbot-auto --help all +  ./certbot-auto --help all You can also tell it exactly what you want it to do from the command line. @@ -56,7 +69,7 @@ For instance, if you want to obtain a cert for ``example.com``, ``www.example.com``, and ``other.example.net``, using the Apache plugin to both obtain and install the certs, you could do this:: - ./certbot-auto --apache -d example.com -d www.example.com -d other.example.net +  ./certbot-auto --apache -d example.com -d www.example.com -d other.example.net (The first time you run the command, it will make an account, and ask for an email and agreement to the Let's Encrypt Subscriber Agreement; you can @@ -65,14 +78,14 @@ automate those with ``--email`` and ``--agree-tos``) If you want to use a webserver that doesn't have full plugin support yet, you can still use "standalone" or "webroot" plugins to obtain a certificate:: - ./certbot-auto certonly --standalone --email admin@example.com -d example.com -d www.example.com -d other.example.net +  ./certbot-auto certonly --standalone --email admin@example.com -d example.com -d www.example.com -d other.example.net Understanding the client in more depth -------------------------------------- To understand what the client is doing in detail, it's important to -understand the way it uses plugins. Please see the `explanation of +understand the way it uses plugins.  Please see the `explanation of plugins `_ in the User Guide. @@ -104,20 +117,20 @@ ACME working area in github: https://github.com/ietf-wg-acme/acme .. _Freenode: https://webchat.freenode.net?channels=%23letsencrypt .. |build-status| image:: https://travis-ci.org/certbot/certbot.svg?branch=master - :target: https://travis-ci.org/certbot/certbot - :alt: Travis CI status +   :target: https://travis-ci.org/certbot/certbot +   :alt: Travis CI status .. |coverage| image:: https://coveralls.io/repos/certbot/certbot/badge.svg?branch=master - :target: https://coveralls.io/r/certbot/certbot - :alt: Coverage status +   :target: https://coveralls.io/r/certbot/certbot +   :alt: Coverage status .. |docs| image:: https://readthedocs.org/projects/letsencrypt/badge/ - :target: https://readthedocs.org/projects/letsencrypt/ - :alt: Documentation status +   :target: https://readthedocs.org/projects/letsencrypt/ +   :alt: Documentation status .. |container| image:: https://quay.io/repository/letsencrypt/letsencrypt/status - :target: https://quay.io/repository/letsencrypt/letsencrypt - :alt: Docker Repository on Quay.io +   :target: https://quay.io/repository/letsencrypt/letsencrypt +   :alt: Docker Repository on Quay.io .. Do not modify this comment unless you know what you're doing. tag:links-end @@ -135,27 +148,29 @@ Current Features * Supports multiple web servers: - - apache/2.x - - nginx/0.8.48+ - - webroot (adds files to webroot directories in order to prove control of - domains and obtain certs) - - standalone (runs its own simple webserver to prove you control a domain) - - other server software via `third party plugins `_ +  - apache/2.x +  - nginx/0.8.48+ +  - webroot (adds files to webroot directories in order to prove control of +    domains and obtain certs) +  - standalone (runs its own simple webserver to prove you control a domain) +  - other server software via `third party plugins `_ * The private key is generated locally on your system. * Can talk to the Let's Encrypt CA or optionally to other ACME - compliant services. +  compliant services. * Can get domain-validated (DV) certificates. * Can revoke certificates. * Adjustable RSA key bit-length (2048 (default), 4096, ...). * Can optionally install a http -> https redirect, so your site effectively - runs https only (Apache only) +  runs https only (Apache only) * Fully automated. * Configuration changes are logged and can be reverted. * Supports an interactive text UI, or can be driven entirely from the - command line. +  command line. * Free and Open Source Software, made with Python. .. Do not modify this comment unless you know what you're doing. tag:features-end For extensive documentation on using and contributing to Certbot, go to https://certbot.eff.org/docs. If you would like to contribute to the project or run the latest code from git, you should read our `developer guide `_. + + diff --git a/docs/challenges.rst b/docs/challenges.rst index 95c3b56a8..800a3843d 100644 --- a/docs/challenges.rst +++ b/docs/challenges.rst @@ -1,85 +1,82 @@ + +.. _challenges: + + 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 +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  three tasks that only someone who controls the domain should be able to accomplish: -* Posting a specified file in a specified location on a web site (the HTTP-01 challenge) -* Offering a specified temporary certificate on a web site (the TLS-SNI-01 challenge) -* Posting a specified DNS record in the domain name system (the DNS-01 challenge) +* Posting a specified file in a specified location on a web site (the HTTP-01_ challenge) +* Offering a specified temporary certificate on a web site (the TLS-SNI-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 +The DNS-01 challenge, in particular, requires configuration of a DNS server on +port 53, though that's often not the same machine as your webserver. + +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: +.. _challenges: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7 +.. _ TLS-SNI-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.3 +.. _ 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 plugin: (TLS-SNI-01) Tries to edit your Apache configuration files to temporarily serve - a Certbot-generated certificate for a specified name. Use the Apache plugin when you're running - Certbot on a web server with Apache listening on port 443. -* NGINX plugin: (TLS-SNI-01) Tries to edit your NGINX configuration files to temporarily serve a - Certbot-generated certificate for a specified name. Use the NGINX plugin when you're running - Certbot on a web server with NGINX listening on port 443. -* 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: (TLS-SNI-01 or HTTP-01) Tries to run a temporary web server listening on either HTTP on - port 80 (for HTTP-01) or HTTPS on port 443 (for TLS-SNI-01). Use the Standalone plugin if no existing program - is listening to these ports. Choose TLS-SNI-01 or HTTP-01 using the `--preferred-challenges` option. -* 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. 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. +* 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 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. +  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. TLS-SNI-01 Challenge ~~~~~~~~~~~~~~~~~~~~ -* The TLS-SNI-01 challenge doesn’t work with content delivery networks (CDNs) - like CloudFlare and Akamai because the domain name is pointed at the CDN, not directly at your server. +* The TLS-SNI-01 challenge doesn’t work with content delivery networks (CDNs)  +  like CloudFlare and Akamai because the domain name is pointed at the CDN, not directly at your server. * Make sure port 443 is open, publicly reachable from the Internet, and not blocked by a router or firewall. * When using the Apache plugin, make sure you are running Apache and no other web server on port 443. * When using the NGINX plugin, make sure you are running NGINX and no other web server on port 443. * With either the Apache or NGINX plugin, certbot modifies your web server configuration. If you get - an error after successfully completing the challenge, then you have received a certificate but the - plugin was unable to modify your web server configuration, meaning that you'll have to install the certificate manually. - In that case, please file a bug to help us improve certbot! +  an error after successfully completing the challenge, then you have received a certificate but the +  plugin was unable to modify your web server configuration, meaning that you'll have to install the certificate manually. +  In that case, please file a bug to help us improve certbot! * When using the Standalone plugin, make sure another program is not already listening to port 443 on the server. 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. +* 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/contributing.rst b/docs/contributing.rst index c144a4f74..b2eb49c5f 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -3,7 +3,7 @@ Developer Guide =============== .. contents:: Table of Contents - :local: +   :local: .. _getting_started: @@ -20,7 +20,7 @@ running: .. code-block:: shell - git clone https://github.com/certbot/certbot +   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 @@ -31,17 +31,17 @@ a new plugin is introduced. .. code-block:: shell - cd certbot - ./certbot-auto --os-packages-only - ./tools/venv.sh +   cd certbot +   ./certbot-auto --os-packages-only +   ./tools/venv.sh Then in each shell where you're working on the client, do: .. code-block:: shell - source ./venv/bin/activate - export SERVER=https://acme-staging.api.letsencrypt.org/directory - source tests/integration/_common.sh +   source ./venv/bin/activate +   export SERVER=https://acme-staging.api.letsencrypt.org/directory +   source tests/integration/_common.sh After that, your shell will be using the virtual environment, and you run the client by typing `certbot` or `certbot_test`. The latter is an alias that @@ -58,12 +58,12 @@ More information can be found in the `virtualenv docs`_. Find issues to work on ---------------------- -You can find the open issues in the `github issue tracker`_. Comparatively -easy ones are marked `Good Volunteer Task`_. If you're starting work on +You can find the open issues in the `github issue tracker`_.  Comparatively +easy ones are marked `Good Volunteer Task`_.  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 +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 `. @@ -113,7 +113,7 @@ and working. Fetch and start Boulder using: .. code-block:: shell - ./tests/boulder-fetch.sh +  ./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. @@ -123,14 +123,14 @@ Boulder: .. code-block:: shell - export SERVER=http://localhost:4000/directory - source tests/integration/_common.sh +   export SERVER=http://localhost:4000/directory +   source tests/integration/_common.sh Run the integration tests using: .. code-block:: shell - ./tests/boulder-integration.sh +  ./tests/boulder-integration.sh .. _removing all containers and volumes: https://www.digitalocean.com/community/tutorials/how-to-remove-docker-images-containers-and-volumes @@ -138,13 +138,13 @@ Code components and layout ========================== acme - contains all protocol specific code +  contains all protocol specific code certbot - main client code +  main client code certbot-apache and certbot-nginx - client code to configure specific web servers +  client code to configure specific web servers certbot.egg-info - configuration for packaging Certbot +  configuration for packaging Certbot Plugin-architecture @@ -196,7 +196,7 @@ possibly tweak the security configuration to make it more correct and secure 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 +`~.NginxConfigurator`.  External projects have made some progress toward support for IIS, Icecast and Plesk. Installers and Authenticators will oftentimes be the same class/object @@ -241,10 +241,10 @@ virtualenv like this: .. code-block:: shell - . venv/bin/activate - . tests/integration/_common.sh - pip install -e examples/plugins/ - certbot_test plugins +  . 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. @@ -258,13 +258,13 @@ 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. +   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 +    http://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points .. _coding-style: @@ -278,26 +278,26 @@ Please: 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:: +   use `Sphinx-style`_ documentation:: - def foo(arg): - """Short description. +        def foo(arg): +            """Short description. - :param int arg: Some number. +            :param int arg: Some number. - :returns: Argument - :rtype: int +            :returns: Argument +            :rtype: int - """ - return arg +            """ +            return arg 4. Remember to use ``pylint``. .. _Google Python Style Guide: - https://google.github.io/styleguide/pyguide.html +  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 +  https://www.python.org/dev/peps/pep-0008 Submitting a pull request ========================= @@ -306,14 +306,14 @@ 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 ``./tools/venv.sh``. - (this is a **very important** step) +   virtualenv. You can do this by running ``./tools/venv.sh``. +   (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. +   including coverage. The ``--skip-missing-interpreters`` argument ignores +   missing versions of Python needed for running the tests. Fix any errors. 5. If your code touches communication with an ACME server/Boulder, you - should run the integration tests, see `integration`_. +   should run the integration tests, see `integration`_. 6. Submit the PR. 7. Did your tests pass on Travis? If they didn't, fix any errors. @@ -323,7 +323,7 @@ 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 +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. @@ -331,16 +331,16 @@ the ``letsencrypt-auto-source`` and 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 +``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 +   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 +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. @@ -350,12 +350,12 @@ 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/*`` +   ``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 +root of the repository.  These scripts will be updated by the core developers during the next release. @@ -367,7 +367,7 @@ commands: .. code-block:: shell - make -C docs clean html man +   make -C docs clean html man This should generate documentation in the ``docs/_build/html`` directory. @@ -383,26 +383,26 @@ testing Certbot. This is especially useful for macOS users. 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 ` section. +  Docker Compose after installing Docker Engine and activating your shell as +  described in the :ref:`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' +  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 +  docker-compose run --rm --service-ports development bash Now running the check for linting errors described above is as easy as:: - tox -e lint +  tox -e lint .. _prerequisites: @@ -413,7 +413,7 @@ OS-level dependencies can be installed like so: .. code-block:: shell - letsencrypt-auto-source/letsencrypt-auto --os-packages-only +    letsencrypt-auto-source/letsencrypt-auto --os-packages-only In general... @@ -421,7 +421,7 @@ In general... * `Python`_ 2.6/2.7 is required * `Augeas`_ is required for the Python bindings * ``virtualenv`` and ``pip`` are used for managing other python library - dependencies +  dependencies .. _Python: https://wiki.python.org/moin/BeginnersGuide/Download .. _Augeas: http://augeas.net/ @@ -439,12 +439,14 @@ For squeeze you will need to: FreeBSD ------- -Packages can be installed on FreeBSD using ``pkg``, -or any other port-management tool (``portupgrade``, ``portmanager``, etc.) -from the pre-built package or can be built and installed from ports. -Either way will ensure proper installation of all the dependencies required +Packages can be installed on FreeBSD using ``pkg``,  +or any other port-management tool (``portupgrade``, ``portmanager``, etc.)  +from the pre-built package or can be built and installed from ports.  +Either way will ensure proper installation of all the dependencies required  for the package. 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 index 17cde1adf..b0cb0622c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,20 +2,21 @@ Welcome to the Certbot documentation! ================================================== .. toctree:: - :maxdepth: 2 +   :maxdepth: 2 +   start intro - what - install - using - contributing - packaging - resources +   install +   using +   contributing +   packaging +   resources + reference .. toctree:: - :maxdepth: 1 +   :maxdepth: 1 - api +   api Indices and tables @@ -24,3 +25,5 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + + diff --git a/docs/install.rst b/docs/install.rst index 1f6a45e07..b6772e3f2 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,22 +1,15 @@ ===================== -Get Certbot +Manual Installation ===================== .. contents:: Table of Contents - :local: +   :local: +.. Note:: The easiest way to install Certbot is by visiting `certbot.eff.org`_, +where you can find the correct installation instructions for many web server +and OS combinations. -About Certbot -============= - -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 +.. _certbot.eff.org: https://certbot.eff.org/ System Requirements @@ -26,7 +19,7 @@ Certbot currently requires Python 2.6, 2.7, or 3.3+. By default, it requires root access in order to write to ``/etc/letsencrypt``, ``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to bind to ports 80 and 443 (if you use the ``standalone`` plugin) and to read and modify webserver -configurations (if you use the ``apache`` or ``nginx`` plugins). If none of +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 `_ or @@ -57,16 +50,16 @@ The ``certbot-auto`` wrapper script installs Certbot, obtaining some dependencie 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 +  user@webserver:~$ wget https://dl.eff.org/certbot-auto +  user@webserver:~$ chmod a+x ./certbot-auto +  user@webserver:~$ ./certbot-auto --help .. hint:: The certbot-auto download is protected by HTTPS, which is pretty good, but if you'd like to - double check the integrity of the ``certbot-auto`` script, you can use these steps for verification before running it:: +          double check the integrity of the ``certbot-auto`` script, you can use these steps for verification before running it:: - user@server:~$ wget -N https://dl.eff.org/certbot-auto.asc - user@server:~$ gpg2 --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 - user@server:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto +            user@server:~$ wget -N https://dl.eff.org/certbot-auto.asc +            user@server:~$ gpg2 --recv-key A2CFB51FA275A7286234E7B24D17C995CD9775F2 +            user@server:~$ gpg2 --trusted-key 4D17C995CD9775F2 --verify certbot-auto.asc certbot-auto The ``certbot-auto`` command updates to the latest client release automatically. Since ``certbot-auto`` is a wrapper to ``certbot``, it accepts exactly @@ -75,24 +68,7 @@ the same command line flags and arguments. For more information, see 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 +  ./certbot-auto --help all Running with Docker ------------------- @@ -121,10 +97,10 @@ to, `install Docker`_, then issue the following command: .. code-block:: shell - sudo docker run -it --rm -p 443:443 -p 80:80 --name certbot \ - -v "/etc/letsencrypt:/etc/letsencrypt" \ - -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ - certbot/certbot certonly +   sudo docker run -it --rm -p 443:443 -p 80:80 --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 @@ -144,7 +120,7 @@ Operating System Packages .. code-block:: shell - sudo pacman -S certbot +   sudo pacman -S certbot **Debian** @@ -152,8 +128,8 @@ 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 +   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. @@ -164,18 +140,18 @@ repo, if you have not already done so. Then run: .. code-block:: shell - sudo apt-get install certbot python-certbot-apache -t jessie-backports +   sudo apt-get install certbot python-certbot-apache -t jessie-backports **Fedora** .. code-block:: shell - sudo dnf install certbot python2-certbot-apache +    sudo dnf install certbot python2-certbot-apache **FreeBSD** - * Port: ``cd /usr/ports/security/py-certbot && make install clean`` - * Package: ``pkg install py27-certbot`` +  * Port: ``cd /usr/ports/security/py-certbot && make install clean`` +  * Package: ``pkg install py27-certbot`` **Gentoo** @@ -184,8 +160,8 @@ 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 +   emerge -av app-crypt/certbot +   emerge -av app-crypt/certbot-apache When using the Apache plugin, you will run into a "cannot find a cert or key directive" error if you're sporting the default Gentoo ``httpd.conf``. @@ -196,17 +172,17 @@ Change .. code-block:: shell - - LoadModule ssl_module modules/mod_ssl.so - +   +   LoadModule ssl_module modules/mod_ssl.so +   to .. code-block:: shell - # - LoadModule ssl_module modules/mod_ssl.so - # +   # +   LoadModule ssl_module modules/mod_ssl.so +   # For the time being, this is the only way for the Apache plugin to recognise the appropriate directives when installing the certificate. @@ -214,13 +190,13 @@ 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`` +  * 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`` +  * Port: ``cd /usr/ports/security/letsencrypt/client && make install clean`` +  * Package: ``pkg_add letsencrypt`` **Other Operating Systems** @@ -235,9 +211,222 @@ 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! +   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! + +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 + + +.. _getting_certs: + + +Getting Certificates +==================== + + + + +XXX This section needs to have command-line examples for each plug-in. + +.. _apache: + +Apache +------ + +The Apache plugin currently requires an OS with augeas version 1.0; currently `it +supports +`_ +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``. + +* Apache plugin: (TLS-SNI-01) Tries to edit your Apache configuration files to temporarily serve  +  a Certbot-generated certificate for a specified name. Use the Apache plugin when you're running  +  Certbot on a web server with Apache listening on port 443. + +.. _manual: + +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``, ``dns`` or the +``tls-sni`` 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" + +When using the ``tls-sni`` challenge, ``certbot`` will prepare a self-signed +SSL certificate for you with the challenge validation appropriately +encoded into a subjectAlternatNames entry. You will need to configure +your SSL server to present this challenge SSL certificate to the ACME +server using SNI. + +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. + +* 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.  + +.. _nginx: + +Nginx +----- + +The Nginx plugin has been distributed with Certbot since version 0.9.0 and 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 + +* NGINX plugin: (TLS-SNI-01) Tries to edit your NGINX configuration files to temporarily serve a  +  Certbot-generated certificate for a specified name. Use the NGINX plugin when you're running  +  Certbot on a web server with NGINX listening on port 443. + +.. _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 or 443 in +order to perform domain validation, so you may need to stop your +existing webserver. To control which port the plugin uses, include +one of the options shown below on the command line. + +    * ``--preferred-challenges http`` to use port 80 +    * ``--preferred-challenges tls-sni`` to use port 443 + +It must still be possible for your machine to accept inbound connections from +the Internet on the specified port using each requested domain name. + +.. note:: The ``--standalone-supported-challenges`` option has been +   deprecated since ``certbot`` version 0.9.0. + +* Standalone plugin: (TLS-SNI-01 or HTTP-01) Tries to run a temporary web server listening on either HTTP on  +  port 80 (for HTTP-01) or HTTPS on port 443 (for TLS-SNI-01). Use the Standalone plugin if no existing program  +  is listening to these ports. Choose TLS-SNI-01 or HTTP-01 using the `--preferred-challenges` option. + +.. _webroot: + +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. + +* 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. + + +.. _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 may want to create a certificate using the webroot_ plugin +for authentication and the apache_ plugin for installation, perhaps because you +use a proxy or CDN for SSL and only want to secure the connection between them +and your origin server, which cannot use the tls-sni-01_ challenge due to the +intermediate proxy. + +:: + +    certbot run -a webroot -i apache -w /var/www/html -d example.com + diff --git a/docs/intro.rst b/docs/intro.rst index 2d4abdc2d..4baf9a39f 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,10 +1,16 @@ ===================== -Introduction +Overview ===================== .. note:: - To get started quickly, use the `interactive installation guide `_. +    To get started quickly, use the `interactive installation guide `_. .. include:: ../README.rst - :start-after: tag:intro-begin - :end-before: tag:intro-end +    :start-after: tag:intro-begin +    :end-before: tag:intro-end + +.. include:: what.rst + +.. include:: how.rst + + diff --git a/docs/using.rst b/docs/using.rst index 4fd0b5ec8..b5e3e29ef 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -1,269 +1,20 @@ -========== -User Guide -========== + +rking with Certificates +========================= .. contents:: Table of Contents - :local: +   :local: -Certbot Commands +Before You Begin ================ -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) -=========================================== +* Figure out which plugin to use +* Use the plugin to get the certificate -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 tls-sni-01_ (443) - | 2.4 on Debian-based distributions with ``libaugeas0`` 1.0+. -webroot_ Y N | Obtains a certificate by writing to the webroot directory of http-01_ (80) - | an already running webserver. -nginx_ Y Y | Automates obtaining and installing a certificate with Nginx. tls-sni-01_ (443) - | Shipped with Certbot 0.9.0. -standalone_ Y N | Uses a "standalone" webserver to obtain a certificate. http-01_ (80) or - | Requires port 80 or 443 to be available. This is useful on tls-sni-01_ (443) - | systems with no webserver, or when direct integration with - | the local webserver is not supported or not desired. -manual_ Y N | Helps you obtain a certificate by giving you instructions to http-01_ (80), - | perform domain validation yourself. Additionally allows you dns-01_ (53) or - | to specify scripts to automate the validation task in a tls-sni-01_ (443) - | customized way. -=========== ==== ==== =============================================================== ============================= - -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), -tls-sni-01_ (port 443) 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 -.. _tls-sni-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.3 -.. _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 requires an OS with augeas version 1.0; currently `it -supports -`_ -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 has been distributed with Certbot since version 0.9.0 and 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 ----------- - -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 or 443 in -order to perform domain validation, so you may need to stop your -existing webserver. To control which port the plugin uses, include -one of the options shown below on the command line. - - * ``--preferred-challenges http`` to use port 80 - * ``--preferred-challenges tls-sni`` to use port 443 - -It must still be possible for your machine to accept inbound connections from -the Internet on the specified port using each requested domain name. - -.. note:: The ``--standalone-supported-challenges`` option has been - deprecated since ``certbot`` version 0.9.0. - -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``, ``dns`` or the -``tls-sni`` 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" - -When using the ``tls-sni`` challenge, ``certbot`` will prepare a self-signed -SSL certificate for you with the challenge validation appropriately -encoded into a subjectAlternatNames entry. You will need to configure -your SSL server to present this challenge SSL certificate to the ACME -server using SNI. - -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 may want to create a certificate using the webroot_ plugin -for authentication and the apache_ plugin for installation, perhaps because you -use a proxy or CDN for SSL and only want to secure the connection between them -and your origin server, which cannot use the tls-sni-01_ challenge due to the -intermediate proxy. - -:: - - certbot run -a webroot -i apache -w /var/www/html -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 `. .. _managing-certs: @@ -277,18 +28,18 @@ the ``certificates`` subcommand: 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 +  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 +  certbot certonly --cert-name example.com .. _updating_certs: @@ -332,13 +83,13 @@ Example: .. code-block:: none - certbot --expand -d existing.com,example.com,newdomain.com +  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 +  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. @@ -359,19 +110,19 @@ abuse of the ACME protocol, as described .. _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 +  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 +  certbot certonly --cert-name example.com -d example.org,www.example.org Revoking certificates @@ -381,13 +132,13 @@ If your account key has been compromised or you otherwise need to revoke a certi 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 +  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 +  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 @@ -395,7 +146,7 @@ is a test certificate obtained via the ``--staging`` or ``--test-cert`` flag, th 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 +  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. @@ -407,8 +158,8 @@ 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. +   days). Make sure you renew the certificates at least once in 3 +   months. As of version 0.10.0, Certbot supports a ``renew`` action to check all installed certificates for impending expiry and attempt to renew @@ -432,7 +183,7 @@ 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" +  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 @@ -457,34 +208,34 @@ apply appropriate file permissions. .. code-block:: none - #!/bin/sh +   #!/bin/sh - set -e +   set -e - for domain in $RENEWED_DOMAINS; do - case $domain in - example.com) - daemon_cert_root=/etc/some-daemon/certs +   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 +                   # 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" +                   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" +                   # 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 +                   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 @@ -557,63 +308,16 @@ 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 cert needs to be updated. - If you write a custom script and expect to run a command only after a cert was actually renewed - you will need to use the ``--post-hook`` since the exit status will be 0 both on successful renewal - and when renewal is not necessary. +  This means ``certbot renew`` exit status will be 0 if no cert needs to be updated. +  If you write a custom script and expect to run a command only after a cert was actually renewed +  you will need to use the ``--post-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 .. _where-certs: + Where are my certificates? ========================== @@ -624,277 +328,57 @@ 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. +   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. +  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. +  .. 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. - This is what Apache needs for `SSLCertificateKeyFile - `_, - and Nginx for `ssl_certificate_key - `_. +  This is what Apache needs for `SSLCertificateKeyFile +  `_, +  and Nginx for `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. +  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 - `_, - and what Nginx needs for `ssl_certificate - `_. +  This is what Apache >= 2.4.8 needs for `SSLCertificateFile +  `_, +  and what Nginx needs for `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 - `_. +  ``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 +  `_. - Apache < 2.4.8 needs these for `SSLCertificateFile - `_. - and `SSLCertificateChainFile - `_, - respectively. +  Apache < 2.4.8 needs these for `SSLCertificateFile +  `_. +  and `SSLCertificateChainFile +  `_, +  respectively. - If you're using OCSP stapling with Nginx >= 1.3.7, ``chain.pem`` should be - provided as the `ssl_trusted_certificate - `_ - to validate OCSP responses. +  If you're using OCSP stapling with Nginx >= 1.3.7, ``chain.pem`` should be +  provided as the `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_. +   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) -- ``CERTBOT_CERT_PATH``: The challenge SSL certificate (TLS-SNI-01 only) -- ``CERTBOT_KEY_PATH``: The private key associated with the aforementioned SSL certificate (TLS-SNI-01 only) -- ``CERTBOT_SNI_DOMAIN``: The SNI name for which the ACME server expects to be presented the self-signed certificate located at ``$CERTBOT_CERT_PATH`` (TLS-SNI-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: - -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 be 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/logs/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``. - -.. _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 `_. - -You can also chat with us on IRC: `(#letsencrypt @ -freenode) `_ - -If you find a bug in the software, please do report it in our `issue -tracker `_. 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 index 3d33346c2..dfc7f3812 100644 --- a/docs/what.rst +++ b/docs/what.rst @@ -2,14 +2,14 @@ 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, +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) +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 +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. @@ -23,9 +23,10 @@ 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 +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. +a new one.  See also: :ref:`updating_certs` +