mirror of
https://github.com/certbot/certbot.git
synced 2026-07-27 00:00:44 +02:00
Merge pull request #1622 from letsencrypt/docs
Various improvements to using.rst docs
This commit is contained in:
bmw
+144
-98
@@ -28,13 +28,8 @@ Firstly, please `install Git`_ and run the following commands:
|
||||
git clone https://github.com/letsencrypt/letsencrypt
|
||||
cd letsencrypt
|
||||
|
||||
.. warning:: Alternatively you could `download the ZIP archive`_ and
|
||||
extract the snapshot of our repository, but it's strongly
|
||||
recommended to use the above method instead.
|
||||
|
||||
.. _`install Git`: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
|
||||
.. _`download the ZIP archive`:
|
||||
https://github.com/letsencrypt/letsencrypt/archive/master.zip
|
||||
|
||||
To install and run the client you just need to type:
|
||||
|
||||
@@ -61,107 +56,48 @@ or for full help, type:
|
||||
|
||||
./letsencrypt-auto --help all
|
||||
|
||||
Running with Docker
|
||||
-------------------
|
||||
|
||||
Docker_ is an amazingly simple and quick way to obtain a
|
||||
certificate. However, this mode of operation is unable to install
|
||||
certificates or configure your webserver, because our installer
|
||||
plugins cannot reach 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
|
||||
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
|
||||
that cover both of those hard topics.
|
||||
|
||||
If you're still not convinced and have decided to use this method,
|
||||
from the server that the domain you're requesting a cert for resolves
|
||||
to, `install Docker`_, then issue the following command:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo docker run -it --rm -p 443:443 -p 80:80 --name letsencrypt \
|
||||
-v "/etc/letsencrypt:/etc/letsencrypt" \
|
||||
-v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
|
||||
quay.io/letsencrypt/letsencrypt:latest auth
|
||||
|
||||
and follow the instructions (note that ``auth`` command is explicitly
|
||||
used - no installer plugins involved). Your new cert will be available
|
||||
in ``/etc/letsencrypt/live`` on the host.
|
||||
|
||||
.. _Docker: https://docker.com
|
||||
.. _`install Docker`: https://docs.docker.com/userguide/
|
||||
|
||||
|
||||
Operating System Packages
|
||||
--------------------------
|
||||
|
||||
**FreeBSD**
|
||||
|
||||
* Port: ``cd /usr/ports/security/py-letsencrypt && make install clean``
|
||||
* Package: ``pkg install py27-letsencrypt``
|
||||
|
||||
**Arch Linux**
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo pacman -S letsencrypt letsencrypt-apache
|
||||
|
||||
**Other Operating Systems**
|
||||
|
||||
Unfortunately, this is an ongoing effort. If you'd like to package
|
||||
Let's Encrypt client for your distribution of choice please have a
|
||||
look at the :doc:`packaging`.
|
||||
|
||||
|
||||
From source
|
||||
-----------
|
||||
|
||||
Installation from source is only supported for developers and the
|
||||
whole process is described in the :doc:`contributing`.
|
||||
|
||||
.. warning:: Please do **not** use ``python setup.py install`` or
|
||||
``python pip 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
|
||||
Let's Encrypt 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
|
||||
tested and the most reliable way of getting our software and the free
|
||||
SSL certificates!
|
||||
``letsencrypt-auto`` is the recommended method of running the Let's Encrypt
|
||||
client beta releases on systems that don't have a packaged version. Debian
|
||||
experimental, Arch linux and FreeBSD 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
|
||||
run your own locally modified copy of the client, follow the instructions in
|
||||
the :doc:`contributing`. Some `other methods of installation`_ are discussed
|
||||
below.
|
||||
|
||||
|
||||
Plugins
|
||||
=======
|
||||
|
||||
=========== = = ===============================================================
|
||||
Plugin A I Notes
|
||||
=========== = = ===============================================================
|
||||
apache_ Y Y Automates obtaining and installing a cert with Apache 2.4 on
|
||||
Debian-based distributions with ``libaugeas0`` 1.0+.
|
||||
standalone_ Y N Uses a "standalone" webserver to obtain a cert.
|
||||
webroot_ Y N Obtains a cert using an already running webserver.
|
||||
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_.
|
||||
=========== = = ===============================================================
|
||||
The Let's Encrypt 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.
|
||||
|
||||
=========== ==== ==== ===============================================================
|
||||
Plugin Auth Inst Notes
|
||||
=========== ==== ==== ===============================================================
|
||||
apache_ Y Y Automates obtaining and installing a cert with Apache 2.4 on
|
||||
Debian-based distributions with ``libaugeas0`` 1.0+.
|
||||
standalone_ Y N Uses a "standalone" webserver to obtain a cert.
|
||||
webroot_ Y N Obtains a cert by writing to the webroot directory of an
|
||||
already running webserver.
|
||||
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_.
|
||||
=========== ==== ==== ===============================================================
|
||||
|
||||
Future plugins for IMAP servers, SMTP servers, IRC servers, etc, are likely to
|
||||
be installers but not authenticators.
|
||||
|
||||
Apache
|
||||
------
|
||||
|
||||
If you're running Apache 2.4 on a Debian-based OS with version 1.0+ of
|
||||
the ``libaugeas0`` package available, you can use the Apache plugin.
|
||||
This automates both obtaining and installing certs on an Apache
|
||||
This automates both obtaining *and* installing certs on an Apache
|
||||
webserver. To specify this plugin on the command line, simply include
|
||||
``--apache``.
|
||||
|
||||
@@ -184,13 +120,22 @@ Webroot
|
||||
If you're running a webserver that you don't want to stop to use
|
||||
standalone, you can use the webroot plugin to obtain a cert by
|
||||
including ``certonly`` and ``--webroot`` on the command line. In
|
||||
addition, you'll need to specify ``--webroot-path`` with the root
|
||||
addition, you'll need to specify ``--webroot-path`` or ``-w`` with the root
|
||||
directory of 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 multiple domains are specified, they must all use the same path.
|
||||
Additionally, your server must be configured to serve files from
|
||||
hidden directories.
|
||||
|
||||
If you're getting a certificate for many domains at once, each domain will use
|
||||
the most recent ``--webroot-path``. So for instance:
|
||||
|
||||
``letsencrypt certonly --webroot -w /var/www/example/ -d www.example.com -d example.com -w /var/www/eg -d eg.is -d www.eg.is``
|
||||
|
||||
Would obtain a single certificate for all of those names, using the
|
||||
``/var/www/example`` webroot directory for the first two, and
|
||||
``/var/www/eg`` for the second two.
|
||||
|
||||
Note that to use the webroot plugin, your server must be configured to serve
|
||||
files from hidden directories.
|
||||
|
||||
Manual
|
||||
------
|
||||
@@ -352,6 +297,107 @@ give us us as much information as possible:
|
||||
- your operating system, including specific version
|
||||
- specify which installation_ method you've chosen
|
||||
|
||||
Other methods of installation
|
||||
=============================
|
||||
|
||||
Running with Docker
|
||||
-------------------
|
||||
|
||||
Docker_ is an amazingly simple and quick way to obtain a
|
||||
certificate. However, this mode of operation is unable to install
|
||||
certificates or configure your webserver, because our installer
|
||||
plugins cannot reach 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
|
||||
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
|
||||
that cover both of those hard topics.
|
||||
|
||||
If you're still not convinced and have decided to use this method,
|
||||
from the server that the domain you're requesting a cert for resolves
|
||||
to, `install Docker`_, then issue the following command:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo docker run -it --rm -p 443:443 -p 80:80 --name letsencrypt \
|
||||
-v "/etc/letsencrypt:/etc/letsencrypt" \
|
||||
-v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
|
||||
quay.io/letsencrypt/letsencrypt:latest auth
|
||||
|
||||
and follow the instructions (note that ``auth`` command is explicitly
|
||||
used - no installer plugins involved). Your new cert will be available
|
||||
in ``/etc/letsencrypt/live`` on the host.
|
||||
|
||||
.. _Docker: https://docker.com
|
||||
.. _`install Docker`: https://docs.docker.com/userguide/
|
||||
|
||||
|
||||
Operating System Packages
|
||||
--------------------------
|
||||
|
||||
**FreeBSD**
|
||||
|
||||
* Port: ``cd /usr/ports/security/py-letsencrypt && make install clean``
|
||||
* Package: ``pkg install py27-letsencrypt``
|
||||
|
||||
**Arch Linux**
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo pacman -S letsencrypt letsencrypt-apache
|
||||
|
||||
**Debian Experimental**
|
||||
|
||||
If you run Debian unstable, you can install experimental letsencrypt packages.
|
||||
Add the line ``deb http://ftp.us.debian.org/debian/ experimental main`` (or
|
||||
the equivalent for your country) to ``/etc/apt/sources.list``, then run
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get -t experimental install letsencrypt python-letsencrypt-apache
|
||||
|
||||
If you don't want to use the Apache plugin, you can ommit the
|
||||
``python-letsencrypt-apache`` package.
|
||||
|
||||
**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
|
||||
look at the :doc:`packaging`.
|
||||
|
||||
|
||||
From source
|
||||
-----------
|
||||
|
||||
Installation from source is only supported for developers and the
|
||||
whole process is described in the :doc:`contributing`.
|
||||
|
||||
.. warning:: Please do **not** use ``python setup.py install`` or
|
||||
``python pip 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
|
||||
Let's Encrypt 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
|
||||
tested and the most reliable way of getting our software and the free
|
||||
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
|
||||
archive from GitHub may be technically possible but are not presently
|
||||
recommended or supported.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user