mirror of
https://github.com/certbot/certbot.git
synced 2026-07-27 08:09:10 +02:00
bmw
+30
-5
@@ -1,6 +1,10 @@
|
||||
============
|
||||
Contributing
|
||||
============
|
||||
===============
|
||||
Developer Guide
|
||||
===============
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
|
||||
|
||||
.. _hacking:
|
||||
|
||||
@@ -207,6 +211,27 @@ We currently offer a pythondialog and "text" mode for displays. Display
|
||||
plugins implement the `~letsencrypt.interfaces.IDisplay`
|
||||
interface.
|
||||
|
||||
.. _dev-plugin:
|
||||
|
||||
Writing your own plugin
|
||||
=======================
|
||||
|
||||
Let's Encrypt client supports dynamic discovery of plugins through the
|
||||
`setuptools entry points`_. This way you can, for example, create a
|
||||
custom implementation of `~letsencrypt.interfaces.IAuthenticator` or
|
||||
the `~letsencrypt.interfaces.IInstaller` without having to merge it
|
||||
with the core upstream source code. An example is provided in
|
||||
``examples/plugins/`` directory.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. _`setuptools entry points`:
|
||||
https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
|
||||
|
||||
|
||||
.. _coding-style:
|
||||
|
||||
@@ -271,8 +296,6 @@ commands:
|
||||
This should generate documentation in the ``docs/_build/html``
|
||||
directory.
|
||||
|
||||
.. _prerequisites:
|
||||
|
||||
|
||||
Other methods for running the client
|
||||
====================================
|
||||
@@ -326,6 +349,8 @@ Now run tests inside the Docker image:
|
||||
tox -e py27
|
||||
|
||||
|
||||
.. _prerequisites:
|
||||
|
||||
Notes on OS dependencies
|
||||
========================
|
||||
|
||||
|
||||
+1
-1
@@ -7,7 +7,7 @@ Welcome to the Let's Encrypt client documentation!
|
||||
intro
|
||||
using
|
||||
contributing
|
||||
plugins
|
||||
packaging
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
===============
|
||||
Packaging Guide
|
||||
===============
|
||||
|
||||
Documentation can be found at
|
||||
https://github.com/letsencrypt/letsencrypt/wiki/Packaging.
|
||||
@@ -1,19 +0,0 @@
|
||||
=======
|
||||
Plugins
|
||||
=======
|
||||
|
||||
Let's Encrypt client supports dynamic discovery of plugins through the
|
||||
`setuptools entry points`_. This way you can, for example, create a
|
||||
custom implementation of `~letsencrypt.interfaces.IAuthenticator` or
|
||||
the `~letsencrypt.interfaces.IInstaller` without having to merge it
|
||||
with the core upstream source code. An example is provided in
|
||||
``examples/plugins/`` directory.
|
||||
|
||||
.. 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.
|
||||
|
||||
.. _`setuptools entry points`:
|
||||
https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
|
||||
+230
-34
@@ -1,45 +1,104 @@
|
||||
==============================
|
||||
Using the Let's Encrypt client
|
||||
==============================
|
||||
==========
|
||||
User Guide
|
||||
==========
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:local:
|
||||
|
||||
Getting the code
|
||||
================
|
||||
.. _installation:
|
||||
|
||||
Please `install Git`_ and run the following commands:
|
||||
Installation
|
||||
============
|
||||
|
||||
.. _letsencrypt-auto:
|
||||
|
||||
letsencrypt-auto
|
||||
----------------
|
||||
|
||||
``letsencrypt-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
|
||||
provides automated updates.
|
||||
|
||||
Firstly, please `install Git`_ and run the following commands:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git clone https://github.com/letsencrypt/letsencrypt
|
||||
cd letsencrypt
|
||||
|
||||
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.
|
||||
.. 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
|
||||
|
||||
|
||||
Installation and Usage
|
||||
======================
|
||||
|
||||
To install and run the client you just need to type:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
./letsencrypt-auto
|
||||
|
||||
(Once letsencrypt is packaged by distributions, the command will just be
|
||||
``letsencrypt``. ``letsencrypt-auto`` is a wrapper which installs virtualized
|
||||
dependencies and provides automated updates during the beta program)
|
||||
|
||||
The ``letsencrypt`` commandline tool has a builtin help:
|
||||
Throughout the documentation, whenever you see references to
|
||||
``letsencrypt`` script/binary, you can substitute in
|
||||
``letsencrypt-auto``. For example, to get the help you would type:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
./letsencrypt-auto --help
|
||||
./letsencrypt-auto --help
|
||||
|
||||
|
||||
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 your requesting a cert for resolves
|
||||
to, `install Docker`_, issue the following command:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo docker run -it --rm -p 443:443 --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/
|
||||
|
||||
|
||||
Distro packages
|
||||
---------------
|
||||
|
||||
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
|
||||
@@ -50,8 +109,137 @@ The ``letsencrypt`` commandline tool has a builtin help:
|
||||
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!
|
||||
|
||||
|
||||
Plugins
|
||||
=======
|
||||
|
||||
Officially supported plugins:
|
||||
|
||||
========== = = ================================================================
|
||||
Plugin A I Notes and status
|
||||
========== = = ================================================================
|
||||
standalone Y N Very stable. Uses port 80 (force by
|
||||
``--standalone-supported-challenges simpleHttp``) or 443
|
||||
(force by ``standalone-supported-challenges dvsni``).
|
||||
apache Y Y Alpha. Automates Apache installation, works fairly well but on
|
||||
Debian-based distributions only for now.
|
||||
webroot Y N Works with already running webserver, by writing necessary files
|
||||
to the disk (``--webroot-path`` should be pointed to your
|
||||
``public_html``). Currently, when multiple domains are specified
|
||||
(`-d`), they must all use the same web root path.
|
||||
manual Y N Hidden from standard UI, use with ``--a manual``. Requires to
|
||||
copy and paste commands into a new terminal session. Allows to
|
||||
run client on machine different than target webserver, e.g. your
|
||||
laptop.
|
||||
nginx Y Y Very experimental. Not included in letsencrypt-auto_.
|
||||
========== = = ================================================================
|
||||
|
||||
Third party plugins are listed at
|
||||
https://github.com/letsencrypt/letsencrypt/wiki/Plugins. If that
|
||||
that's not enough, you can always :ref:`write your own plugin
|
||||
<dev-plugin>`.
|
||||
|
||||
|
||||
Renewal
|
||||
=======
|
||||
|
||||
.. note:: Let's Encrypt CA issues short lived certificates (90
|
||||
days). Make sure you renew the certificates at least once in 3
|
||||
months.
|
||||
|
||||
In order to renew certificates simply call the ``letsencrypt`` (or
|
||||
letsencrypt-auto_) again, and use the same values when prompted. You
|
||||
can automate it slightly by passing necessary flags on the CLI (see
|
||||
`--help all`), or even further using the :ref:`config-file`. If you're
|
||||
sure that UI doesn't prompt for any details you can add the command to
|
||||
``crontab`` (make it less than every 90 days to avoid problems, say
|
||||
every month).
|
||||
|
||||
Let's Encrypt is working hard on automating the renewal process. Until
|
||||
the tool is ready, we are sorry for the inconvenience!
|
||||
|
||||
|
||||
.. _where-certs:
|
||||
|
||||
Where are my certificates?
|
||||
==========================
|
||||
|
||||
First of all, we encourage you to use Apache or nginx installers, both
|
||||
which perform the certificate managemant automatically. If, however,
|
||||
you prefer to manage everything by hand, this section provides
|
||||
information on where to find necessary files.
|
||||
|
||||
All generated keys and issued certificates can be found in
|
||||
``/etc/letsencrypt/live/$domain``. Rather than copying, please point
|
||||
your (web) server configuration directly to those files (or create
|
||||
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.
|
||||
|
||||
The following files are available:
|
||||
|
||||
``privkey.pem``
|
||||
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
|
||||
put it into 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>`_.
|
||||
|
||||
``cert.pem``
|
||||
Server certificate only.
|
||||
|
||||
This is what Apache needs for `SSLCertificateFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile>`_.
|
||||
|
||||
``chain.pem``
|
||||
All certificates that need to be served by the browser **excluding**
|
||||
server certificate, i.e. root and intermediate certificates only.
|
||||
|
||||
This is what Apache needs for `SSLCertificateChainFile
|
||||
<https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatechainfile>`_.
|
||||
|
||||
``fullchain.pem``
|
||||
All certificates, **including** server certificate. This is
|
||||
concatenation of ``chain.pem`` and ``cert.pem``.
|
||||
|
||||
This is what nginx needs for `ssl_certificate
|
||||
<http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate>`_.
|
||||
|
||||
|
||||
For both chain files, all certificates are ordered from root (primary
|
||||
certificate) towards leaf.
|
||||
|
||||
Please note, that **you must use** either ``chain.pem`` or
|
||||
``fullchain.pem``. In case of webservers, using only ``cert.pem``,
|
||||
will cause nasty errors served through the browsers!
|
||||
|
||||
.. note:: All files are PEM-encoded (as the filename suffix
|
||||
suggests). If you need other format, such as DER or PFX, then you
|
||||
could convert using ``openssl``, but this means you will not
|
||||
benefit from automatic renewal_!
|
||||
|
||||
|
||||
.. _config-file:
|
||||
|
||||
Configuration file
|
||||
------------------
|
||||
==================
|
||||
|
||||
It is possible to specify configuration file with
|
||||
``letsencrypt-auto --config cli.ini`` (or shorter ``-c cli.ini``). An
|
||||
@@ -70,22 +258,30 @@ By default, the following locations are searched:
|
||||
.. keep it up to date with constants.py
|
||||
|
||||
|
||||
Running with Docker
|
||||
===================
|
||||
Getting help
|
||||
============
|
||||
|
||||
Docker_ is another way to quickly obtain testing certs. From the
|
||||
server that the domain your requesting a cert for resolves to,
|
||||
`install Docker`_, issue the following command:
|
||||
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>`_.
|
||||
|
||||
.. code-block:: shell
|
||||
If you find a bug in the software, please do report it in our `issue
|
||||
tracker
|
||||
<https://github.com/letsencrypt/letsencrypt/issues>`_. Remember to
|
||||
give us us as much information as possible:
|
||||
|
||||
sudo docker run -it --rm -p 443:443 --name letsencrypt \
|
||||
-v "/etc/letsencrypt:/etc/letsencrypt" \
|
||||
-v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
|
||||
quay.io/letsencrypt/letsencrypt:latest auth
|
||||
- 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 ``letsencrypt --version`` output
|
||||
- your operating system, including specific version
|
||||
- specify which installation_ method you've chosen
|
||||
|
||||
and follow the instructions. Your new cert will be available in
|
||||
``/etc/letsencrypt/certs``.
|
||||
|
||||
.. _Docker: https://docker.com
|
||||
.. _`install Docker`: https://docs.docker.com/userguide/
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#venv] By using this virtualized Python environment (`virtualenv
|
||||
<https://virtualenv.pypa.io>`_) we don't pollute the main
|
||||
OS space with packages from PyPI!
|
||||
|
||||
Reference in New Issue
Block a user