diff --git a/docs/using.rst b/docs/using.rst index d6ae2c5ee..b546e3005 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -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