upstream/certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-06-04 06:15:36 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Restructured RST files significantly. Next commit will be a pass through the content.

Browse source
This commit is contained in:
Peter Conrad 2017-12-15 11:27:00 -08:00
parent 3a8ffc3589
commit eff373f7ec
8 changed files with 520 additions and 823 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
README.rst
View file

@ -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 <https://certbot.eff.org>`_. It generates instructions based on your configuration settings. In most cases, you’ll need `root or administrator access <https://certbot.eff.org/faq/#does-certbot-require-root-administrator-privileges>`_ to your web server to run Certbot.
.. Note:: The best way to get started is to use our `interactive Guide <https://certbot.eff.org>`_.
The Interactive Guide generates instructions based on your web server and operating system.
In most cases, you’ll need `root or administrator access <https://certbot.eff.org/faq/#does-certbot-require-root-administrator-privileges>`_ 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 <https://certbot.eff.org/docs/using.html#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 <https://certbot.eff.org/docs/using.html#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 <https://certbot.eff.org/docs/using.html#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 <https://certbot.eff.org/docs/contributing.html>`_.

91
docs/challenges.rst
View file

@ -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.

126
docs/contributing.rst
View file

@ -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 <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 <getting_started>` section.
  Docker Compose after installing Docker Engine and activating your shell as
  described in the :ref:`Getting Started <getting_started>` section.
Now you can develop on your host machine, but run Certbot and test your changes
in Docker. When using ``docker-compose`` make sure you are inside your clone of
the Certbot repository. As an example, you can run the following command to
check for linting errors::
docker-compose run --rm --service-ports development bash -c 'tox -e lint'
  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``.

21
docs/index.rst
View file

@ -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`

323
docs/install.rst
View file

@ -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 <https://github.com/diafygi/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
<IfDefine SSL>
LoadModule ssl_module modules/mod_ssl.so
</IfDefine>
   <IfDefine SSL>
   LoadModule ssl_module modules/mod_ssl.so
   </IfDefine>
to
.. code-block:: shell
#<IfDefine SSL>
LoadModule ssl_module modules/mod_ssl.so
#</IfDefine>
   #<IfDefine SSL>
   LoadModule ssl_module modules/mod_ssl.so
   #</IfDefine>
For the time being, this is the only way for the Apache plugin to recognise
the appropriate directives when installing the certificate.
@ -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
<https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/constants.py>`_
modern OSes based on Debian, Fedora, SUSE, Gentoo and Darwin.
This automates both obtaining *and* installing certificates on an Apache
webserver. To specify this plugin on the command line, simply include
``--apache``.
* 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

14
docs/intro.rst
View file

@ -1,10 +1,16 @@
=====================
Introduction
Overview
=====================
.. note::
To get started quickly, use the `interactive installation guide <https://certbot.eff.org>`_.
    To get started quickly, use the `interactive installation guide <https://certbot.eff.org>`_.
.. include:: ../README.rst
:start-after: tag:intro-begin
:end-before: tag:intro-end
    :start-after: tag:intro-begin
    :end-before: tag:intro-end
.. include:: what.rst
.. include:: how.rst

694
docs/using.rst
View file

@ -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
<https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/constants.py>`_
modern OSes based on Debian, Fedora, SUSE, Gentoo and Darwin.
This automates both obtaining *and* installing certificates on an Apache
webserver. To specify this plugin on the command line, simply include
``--apache``.
Webroot
-------
If you're running a local webserver for which you have the ability
to modify the content being served, and you'd prefer not to stop the
webserver during the certificate issuance process, you can use the webroot
plugin to obtain a certificate by including ``certonly`` and ``--webroot`` on
the command line. In addition, you'll need to specify ``--webroot-path``
or ``-w`` with the top-level directory ("web root") containing the files
served by your webserver. For example, ``--webroot-path /var/www/html``
or ``--webroot-path /usr/share/nginx/html`` are two common webroot paths.
If you're getting a certificate for many domains at once, the plugin
needs to know where each domain's files are served from, which could
potentially be a separate directory for each domain. When requesting a
certificate for multiple domains, each domain will use the most recently
specified ``--webroot-path``. So, for instance,
::
certbot certonly --webroot -w /var/www/example/ -d www.example.com -d example.com -w /var/www/other -d other.example.net -d another.other.example.net
would obtain a single certificate for all of those names, using the
``/var/www/example`` webroot directory for the first two, and
``/var/www/other`` for the second two.
The webroot plugin works by creating a temporary file for each of your requested
domains in ``${webroot-path}/.well-known/acme-challenge``. Then the Let's Encrypt
validation server makes HTTP requests to validate that the DNS for each
requested domain resolves to the server running certbot. An example request
made to your web server would look like:
::
66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"
Note that to use the webroot plugin, your server must be configured to serve
files from hidden directories. If ``/.well-known`` is treated specially by
your webserver configuration, you might need to modify the configuration
to ensure that files inside ``/.well-known/acme-challenge`` are served by
the webserver.
Nginx
-----
The Nginx plugin 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 <dev-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
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatekeyfile>`_,
and Nginx for `ssl_certificate_key
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key>`_.
  This is what Apache needs for `SSLCertificateKeyFile
  <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatekeyfile>`_,
  and Nginx for `ssl_certificate_key
  <http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key>`_.
``fullchain.pem``
All certificates, **including** server certificate (aka leaf certificate or
end-entity certificate). The server certificate is the first one in this file,
followed by any intermediates.
  All certificates, **including** server certificate (aka leaf certificate or
  end-entity certificate). The server certificate is the first one in this file,
  followed by any intermediates.
This is what Apache >= 2.4.8 needs for `SSLCertificateFile
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_,
and what Nginx needs for `ssl_certificate
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate>`_.
  This is what Apache >= 2.4.8 needs for `SSLCertificateFile
  <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_,
  and what Nginx needs for `ssl_certificate
  <http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate>`_.
``cert.pem`` and ``chain.pem`` (less common)
``cert.pem`` contains the server certificate by itself, and
``chain.pem`` contains the additional intermediate certificate or
certificates that web browsers will need in order to validate the
server certificate. If you provide one of these files to your web
server, you **must** provide both of them, or some browsers will show
"This Connection is Untrusted" errors for your site, `some of the time
<https://whatsmychaincert.com/>`_.
  ``cert.pem`` contains the server certificate by itself, and
  ``chain.pem`` contains the additional intermediate certificate or
  certificates that web browsers will need in order to validate the
  server certificate. If you provide one of these files to your web
  server, you **must** provide both of them, or some browsers will show
  "This Connection is Untrusted" errors for your site, `some of the time
  <https://whatsmychaincert.com/>`_.
Apache < 2.4.8 needs these for `SSLCertificateFile
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_.
and `SSLCertificateChainFile
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatechainfile>`_,
respectively.
  Apache < 2.4.8 needs these for `SSLCertificateFile
  <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_.
  and `SSLCertificateChainFile
  <https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatechainfile>`_,
  respectively.
If you're using OCSP stapling with Nginx >= 1.3.7, ``chain.pem`` should be
provided as the `ssl_trusted_certificate
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate>`_
to validate OCSP responses.
  If you're using OCSP stapling with Nginx >= 1.3.7, ``chain.pem`` should be
  provided as the `ssl_trusted_certificate
  <http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_trusted_certificate>`_
  to validate OCSP responses.
.. note:: All files are PEM-encoded.
If you need other format, such as DER or PFX, then you
could convert using ``openssl``. You can automate that with
``--deploy-hook`` if you're using automatic renewal_.
   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 <https://community.letsencrypt.org>`_.
You can also chat with us on IRC: `(#letsencrypt @
freenode) <https://webchat.freenode.net?channels=%23letsencrypt>`_
If you find a bug in the software, please do report it in our `issue
tracker <https://github.com/certbot/certbot/issues>`_. Remember to
give us as much information as possible:
- copy and paste exact command line used and the output (though mind
that the latter might include some personally identifiable
information, including your email and domains)
- copy and paste logs from ``/var/log/letsencrypt`` (though mind they
also might contain personally identifiable information)
- copy and paste ``certbot --version`` output
- your operating system, including specific version
- specify which installation method you've chosen

13
docs/what.rst
View file

@ -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`