diff --git a/docs/challenges.rst b/docs/challenges.rst index d80a79db5..03d815381 100644 --- a/docs/challenges.rst +++ b/docs/challenges.rst @@ -5,20 +5,20 @@ 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 (See the IETF draft of the `HTTP-01`_ challenge) -* Offering a specified temporary certificate on a web site (See the IETF draft of the `TLS-SNI-01`_ challenge)  +* Offering a specified temporary certificate on a web site (See the IETF draft of the `TLS-SNI-01`_ challenge) * Posting a specified DNS record in the domain name system (See the IETF draft of the `DNS-01`_ challenge) 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  +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. .. _TLS-SNI-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.3 @@ -32,7 +32,7 @@ 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  + 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. @@ -42,7 +42,7 @@ General tips: HTTP-01 Challenge ~~~~~~~~~~~~~~~~~ -* Make sure the domain name exists and is already pointed to the public IP address of the server where  +* 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 @@ -50,12 +50,12 @@ HTTP-01 Challenge 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  +* 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  +* 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. @@ -66,7 +66,7 @@ HTTP-01 Challenge TLS-SNI-01 Challenge ~~~~~~~~~~~~~~~~~~~~ -* The TLS-SNI-01 challenge doesn’t work with content delivery networks (CDNs)  +* 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. @@ -83,7 +83,7 @@ TLS-SNI-01 Challenge DNS-01 Challenge ~~~~~~~~~~~~~~~~ -* When using the manual plugin, make sure your DNS records are correctly updated;  +* 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/configure.rst b/docs/configure.rst index d879a92ef..72bcfe79c 100644 --- a/docs/configure.rst +++ b/docs/configure.rst @@ -68,13 +68,13 @@ Certbot accepts a global configuration file that applies its options to all invo 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  +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 + :code: ini By default, the following locations are searched: diff --git a/docs/contributing.rst b/docs/contributing.rst index 912ab7134..5c43bfd4b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -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. @@ -280,15 +280,15 @@ Please: 3. Follow the `Google Python Style Guide`_, with the exception that we use `Sphinx-style`_ documentation:: def foo(arg): -    """Short description. + """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``. @@ -305,14 +305,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. @@ -322,7 +322,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. @@ -330,16 +330,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. @@ -349,12 +349,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. @@ -366,7 +366,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. @@ -382,26 +382,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: @@ -412,7 +412,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... @@ -420,7 +420,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/ @@ -438,10 +438,10 @@ 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 diff --git a/docs/how.rst b/docs/how.rst index 31fd1ff5c..5329758e0 100644 --- a/docs/how.rst +++ b/docs/how.rst @@ -40,22 +40,22 @@ 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) +Plugin Auth Inst Notes Challenge types (and port) =========== ==== ==== =============================================================== ============================= -apache_     Y    Y    | Automates obtaining and installing a certificate with Apache  :ref:`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  :ref:`HTTP-01 ` (80) -                      | an already running webserver. -nginx_      Y    Y    | Automates obtaining and installing a certificate with Nginx.  :ref:`TLS-SNI-01 ` (443) -                      | Shipped with Certbot 0.9.0. -standalone_ Y    N    | Uses a "standalone" webserver to obtain a certificate.        :ref:`HTTP-01 ` (80) or -                      | Requires port 80 or 443 to be available. This is useful on    :ref:`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  :ref:`HTTP-01 ` (80), -                      | perform domain validation yourself. Additionally allows you   :ref:`DNS-01 ` (53) or -                      | to specify scripts to automate the validation task in a       :ref:`TLS-SNI-01 ` (443) -                      | customized way. +apache_ Y Y | Automates obtaining and installing a certificate with Apache :ref:`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 :ref:`HTTP-01 ` (80) + | an already running webserver. +nginx_ Y Y | Automates obtaining and installing a certificate with Nginx. :ref:`TLS-SNI-01 ` (443) + | Shipped with Certbot 0.9.0. +standalone_ Y N | Uses a "standalone" webserver to obtain a certificate. :ref:`HTTP-01 ` (80) or + | Requires port 80 or 443 to be available. This is useful on :ref:`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 :ref:`HTTP-01 ` (80), + | perform domain validation yourself. Additionally allows you :ref:`DNS-01 ` (53) or + | to specify scripts to automate the validation task in a :ref:`TLS-SNI-01 ` (443) + | customized way. =========== ==== ==== =============================================================== ============================= A few @@ -72,19 +72,19 @@ other developers. Many are beta/experimental, but some are already in widespread use: =========== ==== ==== =============================================================== -Plugin      Auth Inst Notes +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_ 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 @@ -162,87 +162,87 @@ Example usage for HTTP-01:: .. code-block:: none -   #!/bin/bash -   echo $CERTBOT_VALIDATION > /var/www/htdocs/.well-known/acme-challenge/$CERTBOT_TOKEN + #!/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 + #!/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 + 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 + #!/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" + # 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" '.*\.\(.*\..*\)') + # 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'])") + # 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 + # 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 + # 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 + #!/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" + # 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/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 + 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 + # 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 diff --git a/docs/index.rst b/docs/index.rst index 2a7dbf80e..ed1572021 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,25 +2,25 @@ Welcome to the Certbot documentation! ================================================== .. toctree:: -   :maxdepth: 2 + :maxdepth: 2 -   start + start intro what how challenges -   install -   using -   contributing -   packaging -   resources + install + using + contributing + packaging + resources reference configure .. toctree:: -   :maxdepth: 1 + :maxdepth: 1 -   api + api Indices and tables diff --git a/docs/install.rst b/docs/install.rst index 1991c27f1..9553c6a61 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -3,7 +3,7 @@ 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 @@ -19,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 @@ -52,14 +52,14 @@ 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:~$ ./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 @@ -68,7 +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 + ./certbot-auto --help all Running with Docker ------------------- @@ -97,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 @@ -120,7 +120,7 @@ Operating System Packages .. code-block:: shell -   sudo pacman -S certbot + sudo pacman -S certbot **Debian** @@ -128,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. @@ -140,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** @@ -160,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``. @@ -172,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. @@ -190,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** @@ -211,11 +211,11 @@ 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 ---------------------------------------- @@ -224,15 +224,15 @@ On a low memory system such as VPS with less than 512MB of RAM, the required dep 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 + 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 + user@webserver:~$ sudo swapoff /tmp/swapfile + user@webserver:~$ sudo rm /tmp/swapfile .. _getting_certs: @@ -259,9 +259,9 @@ 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. +* 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: @@ -290,7 +290,7 @@ 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" + _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 @@ -303,9 +303,9 @@ 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.  +* 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: @@ -318,11 +318,11 @@ 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 + 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. + 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: @@ -341,18 +341,18 @@ 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 + * ``--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. + 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. +* 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: @@ -375,7 +375,7 @@ 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 + 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. @@ -395,8 +395,8 @@ 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. + 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: @@ -417,7 +417,7 @@ 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 + certbot run -a webroot -i apache -w /var/www/html -d example.com diff --git a/docs/intro.rst b/docs/intro.rst index 4baf9a39f..ea92b20dc 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -3,11 +3,11 @@ 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 diff --git a/docs/start.rst b/docs/start.rst index b3afc1999..eac2f41a4 100644 --- a/docs/start.rst +++ b/docs/start.rst @@ -32,10 +32,10 @@ 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) + 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) + 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/using.rst b/docs/using.rst index 16557839f..aa08f684a 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -2,7 +2,7 @@ Working with Certificates ========================= .. contents:: Table of Contents -   :local: + :local: Before You Begin ================ @@ -27,18 +27,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: @@ -82,13 +82,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. @@ -116,12 +116,12 @@ by specifying new domains using the ``-d`` or ``--domains`` flag. If certificate 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 @@ -131,13 +131,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 @@ -145,7 +145,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. @@ -157,8 +157,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 @@ -182,7 +182,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 @@ -207,34 +207,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 @@ -307,10 +307,10 @@ 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. @@ -327,57 +327,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_. diff --git a/docs/what.rst b/docs/what.rst index 409809b01..5fc4b82c6 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,9 @@ 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`