From c33ee0e2df28b7bc5a8648468f2886a3d43ba5b9 Mon Sep 17 00:00:00 2001 From: Noah Swartz Date: Mon, 21 Aug 2017 12:30:04 -0700 Subject: add warnings and clarity to config documentation (#4991) --- docs/using.rst | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 8d9a22847..11915d896 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -544,8 +544,15 @@ commands into your individual environment. Modifying the Renewal Configuration File ---------------------------------------- +When a certificate is issued, by default Certbot creates a renewal configuration file that +tracks the options that were selected when Certbot was run. This allows Certbot +to use those same options again when it comes time for renewal. These renewal +configuration files are located at ``/etc/letsencrypt/renewal/CERTNAME``. + For advanced certificate management tasks, it is possible to manually modify the certificate's -renewal configuration file, located at ``/etc/letsencrypt/renewal/CERTNAME``. +renewal configuration file, but this is discouraged since it can easily break Certbot's +ability to renew your certificates. If you choose to modify the renewal configuration file +we advise you to test its validity with the ``certbot renew --dry-run`` command. .. warning:: Modifying any files in ``/etc/letsencrypt`` can damage them so Certbot can no longer properly manage its certificates, and we do not recommend doing so. @@ -796,7 +803,12 @@ of Certbot that you would like to run. Configuration file ================== -It is possible to specify configuration file with +Certbot accepts a global configuration file that applies its options to all invocations +of Certbot. Certificate specific configuration choices should be set in the ``.conf`` +files that can be found in ``/etc/letsencrypt/renewal``. + +By default no cli.ini file is created, after creating one +it is possible to specify the location of this configuration file with ``certbot-auto --config cli.ini`` (or shorter ``-c cli.ini``). An example configuration file is shown below: @@ -810,6 +822,13 @@ By default, the following locations are searched: ``~/.config/letsencrypt/cli.ini`` if ``$XDG_CONFIG_HOME`` is not set). +Since this configuration file applies to all invocations of certbot it is incorrect +to list domains in it. Listing domains in cli.ini may prevent renewal from working. +Additionally due to how arguments in cli.ini are parsed, options which wish to +not be set should not be listed. Options set to false will instead be read +as being set to true by older versions of Certbot, since they have been listed +in the config file. + .. keep it up to date with constants.py .. _log-rotation: -- cgit v1.2.3