diff --git a/docs/contributing.rst b/docs/contributing.rst index 395493cef..5f2a84605 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -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 ======================== diff --git a/docs/index.rst b/docs/index.rst index 72be096f9..68289d760 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,7 @@ Welcome to the Let's Encrypt client documentation! intro using contributing - plugins + packaging .. toctree:: :maxdepth: 1 diff --git a/docs/packaging.rst b/docs/packaging.rst new file mode 100644 index 000000000..5f09b65fa --- /dev/null +++ b/docs/packaging.rst @@ -0,0 +1,6 @@ +=============== +Packaging Guide +=============== + +Documentation can be found at +https://github.com/letsencrypt/letsencrypt/wiki/Packaging. diff --git a/docs/plugins.rst b/docs/plugins.rst deleted file mode 100644 index 33d63e84f..000000000 --- a/docs/plugins.rst +++ /dev/null @@ -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 diff --git a/docs/using.rst b/docs/using.rst index 883efc78c..cf4d4fe90 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -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 +`. + + +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 + `_, + and nginx for `ssl_certificate_key + `_. + +``cert.pem`` + Server certificate only. + + This is what Apache needs for `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 + `_. + +``fullchain.pem`` + All certificates, **including** server certificate. This is + concatenation of ``chain.pem`` and ``cert.pem``. + + This is what nginx needs for `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) `_ or +get support on our `forums `_. -.. code-block:: shell +If you find a bug in the software, please do report it in our `issue +tracker +`_. 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 + `_) we don't pollute the main + OS space with packages from PyPI!