From f3915705668f1da08077c2f5e42b317b14df462b Mon Sep 17 00:00:00 2001 From: Noah Swartz Date: Thu, 30 Jun 2016 19:01:02 -0700 Subject: [PATCH 1/3] seth and noah updated some confusing things --- README.rst | 11 +++-- docs/using.rst | 119 +++++++++++++++++++++++++++++++++++++------------ 2 files changed, 97 insertions(+), 33 deletions(-) diff --git a/README.rst b/README.rst index c71079f9a..59be650dd 100644 --- a/README.rst +++ b/README.rst @@ -41,7 +41,7 @@ certbot.eff.org_ to find out), you can install it from there, and run it by typing ``certbot`` (or ``letsencrypt``). Because not all operating systems have packages yet, we provide a temporary solution via the ``certbot-auto`` wrapper script, which obtains some dependencies from -your OS and puts others in a python virtual environment:: +your OS and puts others in a Python virtual environment:: user@webserver:~$ wget https://dl.eff.org/certbot-auto user@webserver:~$ chmod a+x ./certbot-auto @@ -60,9 +60,12 @@ And for full command line help, you can type:: ``certbot-auto`` updates to the latest client release automatically. And since ``certbot-auto`` is a wrapper to ``certbot``, it accepts exactly -the same command line flags and arguments. More details about this script and -other installation methods can be found `in the User Guide -`_. +the same command line flags and arguments. Throughout our and others' documentation +you should substitute the name of the command that certbot.eff.org_ told you +to use on your system. (``certbot-auto`` should always be run from the directory +where it has been downloaded and invoked via ``./certbot-auto``). +More details about this script and other installation methods can be found +`in the User Guide `_. How to run the client --------------------- diff --git a/docs/using.rst b/docs/using.rst index fb96bb853..bb6741cc4 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -9,34 +9,46 @@ Getting Certbot =============== To get specific instructions for installing Certbot on your OS, we recommend -visiting certbot.eff.org_. If you're offline, you can find some general -instructions `in the README / Introduction `__ +visiting certbot.eff.org_. For general information on how to install Certbot, +and the difference between the ``certbot``, ``certbot-auto``, ``letsencrypt``, +and ``letsencrypt-auto`` commands, please refer to the +`README / Introduction `__ __ installation_ .. _certbot.eff.org: https://certbot.eff.org .. _certbot-auto: -The name of the certbot command -------------------------------- - -Many platforms now have native packages that give you a ``certbot`` or (for -older packages) ``letsencrypt`` command you can run. On others, the -``certbot-auto`` / ``letsencrypt-auto`` installer and wrapper script is a -stand-in. Throughout the documentation, whenever you see references to -``certbot`` script/binary, you should substitute in the name of the command -that certbot.eff.org_ told you to use on your system (``certbot``, -``letsencrypt``, or ``certbot-auto``). +Commands +======== +The Certbot client uses a number of different "commands" (also referred +to, equivalently, as "subcommands") to request specific actions such as +obtaining, renewing, or revoking certificates. Some of the most important +and most commonly-used commands will be discussed throughout this +document; an exhaustive list also appears near the end of the document. Plugins ======= The Certbot 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 "certbot run" command, which is the default. +used to obtain and/or install certificates. + +Plugins that can obtain a cert are called "authenticators" and can be used with +the "certonly" command. This will carry out the steps needed to validate that you +control the domain(s) you are requesting a cert for, obtain a cert for the specified +domain(s), and place it in the ``/etc/letsencrypt`` directory on your +machine - without editing any of your server's configuration files to serve the +obtained certificate. If you specify multiple domains to authenticate, they will +all be listed in a single certificate. To obtain multiple seperate certificates +you will need to run Certbot multiple times. + +Plugins that can install a cert are called "installers" and can be used with the +"install" command. These plugins can modify your webserver's configuration to +serve your website over HTTPS using certificates obtained by certbot. + +Plugins that do both can be used with the "certbot run" command, which is the default +when no command is specified. =========== ==== ==== =============================================================== Plugin Auth Inst Notes @@ -54,7 +66,8 @@ manual_ Y N Helps you obtain a cert by giving you instructions to perf nginx_ Y Y Very experimental and not included in certbot-auto_. =========== ==== ==== =============================================================== -There are many third-party-plugins_ available. +There are many third-party-plugins_ available. Below we describe in more detail +the circumstances in which each plugin can be used, and how to use it. Apache ------ @@ -183,7 +196,54 @@ postfix_ N Y STARTTLS Everywhere is becoming a Certbot Postfix/Exim plu If you're interested, you can also :ref:`write your own plugin `. +Re-running Certbot +================== +Running Certbot with the ``certonly`` or ``run`` commands always requests +the creation of a single new certificate, even if you already have an +existing certificate with some of the same domain names. The ``--force-renewal``, +``--duplicate``, and ``--expand`` options control Certbot's behavior in this case. +If you don't specify a requested behavior, Certbot may ask you what you intended. + +``--force-renewal`` tells Certbot to request a new certificate +with the same domains as an existing certificate. (Each and every domain +must be explicitly specified via ``-d``.) If successful, this certificate +will be saved alongside the earlier one and symbolic links (the "``live``" +reference) will be updated to point to the new certificate. This is a +valid method of explicitly requesting the renewal of a specific individual +certificate. + +``--duplicate`` tells Certbot to create a separate, unrelated certificate +with the same domains as an existing certificate. This certificate will +be saved completely separately from the prior one. Most users probably +do not want this behavior. + +``--expand`` tells Certbot to update an existing certificate with a new +certificate that contains all of the old domains and one or more additional +new domains. + +Whenever you obtain a new certificate in any of these ways, the new +certificate exists alongside any previously-obtained certificates, whether +or not the previous certificates have expired. The generation of a new +certificate counts against several rate limits that are intended to prevent +abuse of the ACME protocol, as described +`here `__. + +Certbot also provides a ``renew`` command. This command examines *all* existing +certificates to determine whether or not each is near expiry. For any existing +certificate that is near expiry, ``certbot renew`` will attempt to obtain a +new certificate for the same domains. Unlike ``certonly``, ``renew`` acts on +multiple certificates and always takes into account whether each one is near +expiry. Because of this, ``renew`` is suitable (and designed) for automated use, +to allow your system to automatically renew each certificate when appropriate. +Since ``renew`` will only renew certificates that are near expiry it can be +run as frequently as you want - since it will usually take no action. + +Typically, ``certbot renew`` runs a reduced risk of rate-limit problems +because it renews certificates only when necessary, and because some of +the Let's Encrypt CA's rate limit policies treat the issuance of a new +certificate under these circumstances more generously. More details about +the use of ``certbot renew`` are provided below. Renewal ======= @@ -204,10 +264,11 @@ at the time the certificate was originally issued will be used for the renewal attempt, unless you specify other plugins or options. You can also specify hooks to be run before or after a certificate is -renewed. For example, if you want to use the standalone_ plugin to renew -your certificates, you may want to use a command like +renewed. For example, if you have only a single cert and you obtained it using +the standalone_ plugin, it will be used by default when renewing. In that case +you may want to use a command like this to renew your certificate. -``certbot renew --standalone --pre-hook "service nginx stop" --post-hook "service nginx start"`` +``certbot renew --pre-hook "service nginx stop" --post-hook "service nginx start"`` This will stop Nginx so standalone can bind to the necessary ports and then restart Nginx after the plugin is finished. The hooks will only be @@ -223,12 +284,13 @@ can run on a regular basis, like every week or every day). In that case, you are likely to want to use the ``-q`` or ``--quiet`` quiet flag to silence all output except errors. -The ``--force-renew`` flag may be helpful for automating renewal; -it causes the expiration time of the certificate(s) to be ignored when -considering renewal, and attempts to renew each and every installed -certificate regardless of its age. (This form is not appropriate to run -daily because each certificate will be renewed every day, which will -quickly run into the certificate authority rate limit.) +If you are manually renewing all of your certificates, the +``--force-renewal`` flag may be helpful; it causes the expiration time of +the certificate(s) to be ignored when considering renewal, and attempts to +renew each and every installed certificate regardless of its age. (This +form is not appropriate to run daily because each certificate will be +renewed every day, which will quickly run into the certificate authority +rate limit.) Note that options provided to ``certbot renew`` will apply to *every* certificate for which renewal is attempted; for example, @@ -238,7 +300,6 @@ RSA public key. If a certificate is successfully renewed using specified options, those options will be saved and used for future renewals of that certificate. - An alternative form that provides for more fine-grained control over the renewal process (while renewing specified certificates one at a time), is ``certbot certonly`` with the complete set of subject domains of @@ -253,8 +314,8 @@ this case in order to renew and replace the old certificate rather than obtaining a new one; don't forget any `www.` domains! Specifying a subset of the domains creates a new, separate certificate containing only those domains, rather than replacing the original certificate.) -The ``certonly`` form attempts to renew one individual certificate. - +When run with a set of domains corresponding to an existing certificate, +the ``certonly`` command attempts to renew that one individual certificate. Please note that the CA will send notification emails to the address you provide if you do not renew certificates that are about to expire. From 0c0603b9ea33ef95a13e676668c6cf3ef0204e11 Mon Sep 17 00:00:00 2001 From: Noah Swartz Date: Wed, 17 Aug 2016 14:58:14 -0700 Subject: [PATCH 2/3] copy peter's OS update below --- docs/using.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 2fc25685e..4dabd0d3e 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -286,8 +286,10 @@ the circumstances in which each plugin can be used, and how to use it. 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. +The Apache plugin currently requires OS with augeas version 1.0; currently `it +supports +`_ +modern OSes based on Debian, Fedora, SUSE, Gentoo and Darwin. This automates both obtaining *and* installing certs on an Apache webserver. To specify this plugin on the command line, simply include ``--apache``. From 44cf40472e206979d71e5b396cb7bec12d8c30c4 Mon Sep 17 00:00:00 2001 From: Noah Swartz Date: Wed, 17 Aug 2016 15:43:35 -0700 Subject: [PATCH 3/3] add allow subset --- docs/using.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/using.rst b/docs/using.rst index 4dabd0d3e..20b6cc5c7 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -262,7 +262,8 @@ Plugins that can install a cert are called "installers" and can be used with the serve your website over HTTPS using certificates obtained by certbot. Plugins that do both can be used with the "certbot run" command, which is the default -when no command is specified. +when no command is specified. The "run" subcommand can also be used to specify +a combination of distinct authenticator and installer plugins. =========== ==== ==== =============================================================== Plugin Auth Inst Notes @@ -438,6 +439,11 @@ do not want this behavior. certificate that contains all of the old domains and one or more additional new domains. +``--allow-subset-of-names`` tells Certbot to continue with cert generation if +only some of the specified domain authorazations can be obtained. This may +be useful if some domains specified in a certificate no longer point at this +system. + Whenever you obtain a new certificate in any of these ways, the new certificate exists alongside any previously-obtained certificates, whether or not the previous certificates have expired. The generation of a new