starred/certbot-certbot-2
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-07-28 08:05:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/master' into plugin-docs

Browse Source
This commit is contained in:
Peter Eckersley
2016-05-12 19:20:23 -07:00
parent ff2d8da20d d68322f48d
commit a12405ace0
32 changed files with 1493 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/using.rst
+60 -56
View File
@@ -10,12 +10,12 @@ User Guide
Installation
============
.. _letsencrypt-auto:
.. _certbot-auto:
letsencrypt-auto
certbot-auto
----------------
``letsencrypt-auto`` is a wrapper which installs some dependencies
``certbot-auto`` is a wrapper which installs some dependencies
from your OS standard package repositories (e.g. using `apt-get` or
`yum`), and for other dependencies it sets up a virtualized Python
environment with packages downloaded from PyPI [#venv]_. It also
@@ -25,33 +25,33 @@ To install and run the client, just type...
.. code-block:: shell
./letsencrypt-auto
./certbot-auto
.. hint:: During the beta phase, Let's Encrypt enforces strict rate limits on
the number of certificates issued for one domain. It is recommended to
initially use the test server via `--test-cert` until you get the desired
.. hint:: The Let's Encrypt servers enforce rate
limits on the number of certificates issued for one domain. It is recommended
to initially use the test server via `--test-cert` until you get the desired
certificates.
Throughout the documentation, whenever you see references to
``letsencrypt`` script/binary, you can substitute in
``letsencrypt-auto``. For example, to get basic help you would type:
``certbot`` script/binary, you can substitute in
``certbot-auto``. For example, to get basic help you would type:
.. code-block:: shell
./letsencrypt-auto --help
./certbot-auto --help
or for full help, type:
.. code-block:: shell
./letsencrypt-auto --help all
./certbot-auto --help all
``letsencrypt-auto`` is the recommended method of running the Let's Encrypt
``certbot-auto`` is the recommended method of running the Certbot
client beta releases on systems that don't have a packaged version. Debian,
Arch Linux, Gentoo, FreeBSD, and OpenBSD now have native packages, so on those
systems you can just install ``letsencrypt`` (and perhaps
``letsencrypt-apache``). If you'd like to run the latest copy from Git, or
systems you can just install ``certbot`` (and perhaps
``certbot-apache``). If you'd like to run the latest copy from Git, or
run your own locally modified copy of the client, follow the instructions in
the :doc:`contributing`. Some `other methods of installation`_ are discussed
below.
@@ -60,11 +60,11 @@ below.
Plugins
=======
The Let's Encrypt client supports a number of different "plugins" that can be
The Certbot client supports a number of different "plugins" that can be
used to obtain and/or install certificates. Plugins that can obtain a cert
are called "authenticators" and can be used with the "certonly" command.
Plugins that can install a cert are called "installers". Plugins that do both
can be used with the "letsencrypt run" command, which is the default.
can be used with the "certbot run" command, which is the default.
=========== ==== ==== ===============================================================
Plugin Auth Inst Notes
@@ -79,7 +79,7 @@ standalone_ Y N Uses a "standalone" webserver to obtain a cert. Requires
webserver is not supported or not desired.
manual_ Y N Helps you obtain a cert by giving you instructions to perform
domain validation yourself.
nginx_ Y Y Very experimental and not included in letsencrypt-auto_.
nginx_ Y Y Very experimental and not included in certbot-auto_.
=========== ==== ==== ===============================================================
Third-party plugins
@@ -145,16 +145,16 @@ specified ``--webroot-path``. So, for instance,
::
letsencrypt 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.
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 letsencrypt. An example request
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:
::
@@ -188,7 +188,7 @@ specified port using each requested domain name.
Manual
------
If you'd like to obtain a cert running ``letsencrypt`` on a machine
If you'd like to obtain a cert 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 cert by specifying
@@ -201,11 +201,10 @@ Nginx
In the future, if you're running Nginx you will hopefully be able to use this
plugin to automatically obtain and install your certificate. The Nginx plugin is
still experimental, however, and is not installed with letsencrypt-auto_. If
still experimental, however, and is not installed with certbot-auto_. If
installed, you can select this plugin on the command line by including
``--nginx``.
Renewal
=======
@@ -213,11 +212,11 @@ Renewal
days). Make sure you renew the certificates at least once in 3
months.
The ``letsencrypt`` client now supports a ``renew`` action to check
The ``certbot`` client now supports a ``renew`` action to check
all installed certificates for impending expiry and attempt to renew
them. The simplest form is simply
``letsencrypt renew``
``certbot renew``
This will attempt to renew any previously-obtained certificates that
expire in less than 30 days. The same plugin and options that were used
@@ -228,14 +227,14 @@ You can also specify hooks to be run before or after a certificate is
renewed. For example, if you want to use the standalone_ plugin to renew
your certificates, you may want to use a command like
``letsencrypt renew --standalone --pre-hook "service nginx stop" --post-hook "service nginx start"``
``certbot renew --standalone --pre-hook "service nginx stop" --post-hook "service nginx start"``
This will stop Nginx so standalone can bind to the necessary ports and
then restart Nginx after the plugin is finished. The hooks will only be
run if a certificate is due for renewal, so you can run this command
frequently without unnecessarily stopping your webserver. More
information about renewal hooks can be found by running
``letsencrypt --help renew``.
``certbot --help renew``.
If you're sure that this command executes successfully without human
intervention, you can add the command to ``crontab`` (since certificates
@@ -251,9 +250,9 @@ certificate regardless of its age. (This form is not appropriate to run
daily because each certificate will be renewed every day, which will
quickly run into the certificate authority rate limit.)
Note that options provided to ``letsencrypt renew`` will apply to
Note that options provided to ``certbot renew`` will apply to
*every* certificate for which renewal is attempted; for example,
``letsencrypt renew --rsa-key-size 4096`` would try to replace every
``certbot renew --rsa-key-size 4096`` would try to replace every
near-expiry certificate with an equivalent certificate using a 4096-bit
RSA public key. If a certificate is successfully renewed using
specified options, those options will be saved and used for future
@@ -262,12 +261,12 @@ renewals of that certificate.
An alternative form that provides for more fine-grained control over the
renewal process (while renewing specified certificates one at a time),
is ``letsencrypt certonly`` with the complete set of subject domains of
is ``certbot certonly`` with the complete set of subject domains of
a specific certificate specified via `-d` flags. You may also want to
include the ``-n`` or ``--noninteractive`` flag to prevent blocking on
user input (which is useful when running the command from cron).
``letsencrypt certonly -n -d example.com -d www.example.com``
``certbot certonly -n -d example.com -d www.example.com``
(All of the domains covered by the certificate must be specified in
this case in order to renew and replace the old certificate rather
@@ -280,7 +279,7 @@ The ``certonly`` form attempts to renew one individual certificate.
Please note that the CA will send notification emails to the address
you provide if you do not renew certificates that are about to expire.
Let's Encrypt is working hard on improving the renewal process, and we
Certbot is working hard on improving the renewal process, and we
apologize for any inconveniences you encounter in integrating these
commands into your individual environment.
@@ -311,7 +310,7 @@ The following files are available:
Private key for the certificate.
.. warning:: This **must be kept secret at all times**! Never share
it with anyone, including Let's Encrypt developers. You cannot
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.
@@ -364,7 +363,7 @@ Configuration file
==================
It is possible to specify configuration file with
``letsencrypt-auto --config cli.ini`` (or shorter ``-c cli.ini``). An
``certbot-auto --config cli.ini`` (or shorter ``-c cli.ini``). An
example configuration file is shown below:
.. include:: ../examples/cli.ini
@@ -383,13 +382,14 @@ By default, the following locations are searched:
Getting help
============
If you're having problems you can chat with us on `IRC (#letsencrypt @
Freenode) <https://webchat.freenode.net?channels=%23letsencrypt>`_ or
get support on our `forums <https://community.letsencrypt.org>`_.
If you're having problems you can chat with us on `IRC (#certbot @
OFTC) <https://webchat.oftc.net?channels=%23certbot>`_ or at
`IRC (#letsencrypt @ freenode) <https://webchat.freenode.net?channels=%23letsencrypt>`_
or get support on the Let's Encrypt `forums <https://community.letsencrypt.org>`_.
If you find a bug in the software, please do report it in our `issue
tracker
<https://github.com/letsencrypt/letsencrypt/issues>`_. Remember to
<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
@@ -397,7 +397,7 @@ give us as much information as possible:
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 ``letsencrypt --version`` output
- copy and paste ``certbot --version`` output
- your operating system, including specific version
- specify which installation_ method you've chosen
@@ -414,10 +414,10 @@ plugins cannot reach it from inside the Docker container.
You should definitely read the :ref:`where-certs` section, in order to
know how to manage the certs
manually. https://github.com/letsencrypt/letsencrypt/wiki/Ciphersuite-guidance
manually. https://github.com/certbot/certbot/wiki/Ciphersuite-guidance
provides some information about recommended ciphersuites. If none of
these make much sense to you, you should definitely use the
letsencrypt-auto_ method, which enables you to use installer plugins
certbot-auto_ method, which enables you to use installer plugins
that cover both of those hard topics.
If you're still not convinced and have decided to use this method,
@@ -426,7 +426,7 @@ to, `install Docker`_, then issue the following command:
.. code-block:: shell
sudo docker run -it --rm -p 443:443 -p 80:80 --name letsencrypt \
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" \
quay.io/letsencrypt/letsencrypt:latest auth
@@ -456,19 +456,19 @@ Operating System Packages
.. code-block:: shell
sudo pacman -S letsencrypt letsencrypt-apache
sudo pacman -S letsencrypt
**Debian**
If you run Debian Stretch or Debian Sid, you can install letsencrypt packages.
If you run Debian Stretch or Debian Sid, you can install certbot packages.
.. code-block:: shell
sudo apt-get update
sudo apt-get install letsencrypt python-letsencrypt-apache
sudo apt-get install certbot python-certbot-apache
If you don't want to use the Apache plugin, you can omit the
``python-letsencrypt-apache`` package.
``python-certbot-apache`` package.
Packages exist for Debian Jessie via backports. First you'll have to follow the
instructions at http://backports.debian.org/Instructions/ to enable the Jessie backports
@@ -486,7 +486,7 @@ repo, if you have not already done so. Then run:
**Gentoo**
The official Let's Encrypt client is available in Gentoo Portage. If you
The official Certbot client is available in Gentoo Portage. If you
want to use the Apache plugin, it has to be installed separately:
.. code-block:: shell
@@ -495,8 +495,12 @@ want to use the Apache plugin, it has to be installed separately:
emerge -av app-crypt/letsencrypt-apache
Currently, only the Apache plugin is included in Portage. However, if you
want the nginx plugin, you can use Layman to add the mrueg overlay which
does include the nginx plugin package:
Warning!
You can use Layman to add the mrueg overlay which does include a package for the
Certbot Nginx plugin, however, this plugin is known to be buggy and should only
be used with caution after creating a backup up your Nginx configuration.
We strongly recommend you use the app-crypt/letsencrypt package instead until
the Nginx plugin is ready.
.. code-block:: shell
@@ -533,7 +537,7 @@ Note: this change is not required for the other plugins.
**Other Operating Systems**
OS packaging is an ongoing effort. If you'd like to package
Let's Encrypt client for your distribution of choice please have a
Certbot for your distribution of choice please have a
look at the :doc:`packaging`.
@@ -549,19 +553,19 @@ whole process is described in the :doc:`contributing`.
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
Let's Encrypt team!
Certbot team!
Comparison of different methods
-------------------------------
Unless you have a very specific requirements, we kindly ask you to use
the letsencrypt-auto_ method. It's the fastest, the most thoroughly
Unless you have a very specific requirements, we kindly suggest that you use
the certbot-auto_ method. It's the fastest, the most thoroughly
tested and the most reliable way of getting our software and the free
SSL certificates!
TLS/SSL certificates!
Beyond the methods discussed here, other methods may be possible, such as
installing Let's Encrypt directly with pip from PyPI or downloading a ZIP
installing Certbot directly with pip from PyPI or downloading a ZIP
archive from GitHub may be technically possible but are not presently
recommended or supported.