From c2d0acbb31f7a4fed6d3b0c13fab946600de6179 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Tue, 17 Nov 2015 15:02:07 -0800 Subject: [PATCH 1/3] Expanded plugin documentation --- docs/using.rst | 61 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 55 insertions(+), 6 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 334e2e197..a326e4deb 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -140,8 +140,6 @@ SSL certificates! Plugins ======= -Officially supported plugins: - ========== = = ================================================================ Plugin A I Notes and status ========== = = ================================================================ @@ -161,11 +159,62 @@ manual Y N Hidden from standard UI, use with ``-a manual``. Requires to 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's not enough, you can always :ref:`write your own plugin -`. +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 +webserver. To specify this plugin on the command line, simply include +``--apache``. + +Standalone +---------- + +To obtain a cert using a "standalone" webserver, you can use the +standalone plugin. This plugin needs to bind to port 80 or 443 in +order to perform domain validation, so you may need to stop your +existing webserver. To control which port the plugin uses, include +one of the options shown below on the command line. + + * ``--standalone-supported-challenges http-01`` to use port 80 + * ``--standalone-supported-challenges tls-sni-01`` to use port 443 + +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. To use +this plugin, you need to specify ``--webroot-path`` on the command +line 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. + +Manual +------ + +If you'd like to obtain a cert running ``letsencrypt`` 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 +``-a manual`` or ``--authenticator manual`` on the command line. This +requires you to copy and paste commands into another terminal session. + +Nginx +----- + +In the future, if you're running Nginx you can use this plugin to +automatically obtain and install your certificate. The Nginx plugin +is still experimental, however, and is not installed with +letsencrypt-auto_. + +Third party plugins +------------------- + +These plugins are listed at +https://github.com/letsencrypt/letsencrypt/wiki/Plugins. If you're +interested, you can also :ref:`write your own plugin `. Renewal ======= From c82e8691d34f5851cd7ae44eaccb830b9fc77963 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Tue, 17 Nov 2015 15:15:29 -0800 Subject: [PATCH 2/3] Condense table and fixes #1445 --- docs/using.rst | 31 +++++++++++++------------------ 1 file changed, 13 insertions(+), 18 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index a326e4deb..53f0d5d2a 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -140,24 +140,17 @@ SSL certificates! Plugins ======= -========== = = ================================================================ -Plugin A I Notes and status -========== = = ================================================================ -standalone Y N Very stable. Uses port 80 (force by - ``--standalone-supported-challenges http-01``) or 443 - (force by ``--standalone-supported-challenges tls-sni-01``). -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_. -========== = = ================================================================ +=========== = = =============================================================== +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_. +=========== = = =============================================================== Apache ------ @@ -190,6 +183,8 @@ line 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. Manual ------ From 369321f90d4c3f0753477b4e98db79e0fbf677d3 Mon Sep 17 00:00:00 2001 From: Brad Warren Date: Tue, 17 Nov 2015 17:55:20 -0800 Subject: [PATCH 3/3] Specify flags and certonly --- docs/using.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 53f0d5d2a..5e3554312 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -165,7 +165,8 @@ Standalone ---------- To obtain a cert using a "standalone" webserver, you can use the -standalone plugin. This plugin needs to bind to port 80 or 443 in +standalone plugin by including ``certonly`` and ``--standalone`` +on the command line. This plugin needs to bind to port 80 or 443 in order to perform domain validation, so you may need to stop your existing webserver. To control which port the plugin uses, include one of the options shown below on the command line. @@ -177,10 +178,11 @@ 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. To use -this plugin, you need to specify ``--webroot-path`` on the command -line with the root directory of the files served by your webserver. -For example, ``--webroot-path /var/www/html`` or +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 +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 @@ -192,9 +194,9 @@ Manual If you'd like to obtain a cert running ``letsencrypt`` 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 -``-a manual`` or ``--authenticator manual`` on the command line. This -requires you to copy and paste commands into another terminal session. +the UI, you can use the plugin to obtain a cert by specifying +``certonly`` and ``--manual`` on the command line. This requires you +to copy and paste commands into another terminal session. Nginx ----- @@ -202,7 +204,8 @@ Nginx In the future, if you're running Nginx you can use this plugin to automatically obtain and install your certificate. The Nginx plugin is still experimental, however, and is not installed with -letsencrypt-auto_. +letsencrypt-auto_. If installed, you can select this plugin on the +command line by including ``--nginx``. Third party plugins -------------------