starred/certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-08-01 18:56:55 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: describe how to modify renewal config (#9014)

Browse Source 
* docs: describe how to modify renewal config

* Apply suggestions from code review

Co-authored-by: ohemorange <ebportnoy@gmail.com>

* reword warning about manual modifications

* explain the flags in the --force-renewal command

Co-authored-by: ohemorange <ebportnoy@gmail.com>
This commit is contained in:
alexzorin
2021-11-18 12:14:10 -08:00
committed by GitHub
co-authored by ohemorange
parent 2746fc572f
commit d2578e05e7
1 changed files with 32 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
certbot/docs/using.rst
+32 -35
View File
@@ -747,53 +747,50 @@ commands into your individual environment.
and when renewal is not necessary. and when renewal is not necessary.
.. _renewal-config-file: .. _renewal-config-file:
.. _Modifying the Renewal Configuration File:
Modifying the Renewal Configuration of Existing Certificates
------------------------------------------------------------
Modifying the Renewal Configuration File When creating a certificate, Certbot will keep track of all of the relevant options chosen by the user. At renewal
---------------------------------------- time, Certbot will remember these options and apply them once again.
When a certificate is issued, by default Certbot creates a renewal configuration file that Sometimes, you may encounter the need to change some of these options for future certificate renewals. To achieve this,
tracks the options that were selected when Certbot was run. This allows Certbot you will need to perform the following steps:
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 1. Perform a *dry run renewal* with the amended options on the command line. This allows you to confirm that the change
renewal configuration file, but this is discouraged since it can easily break Certbot's is valid and will result in successful future renewals.
ability to renew your certificates. If you choose to modify the renewal configuration file 2. If the dry run is successful, perform a *live renewal* of the certificate. This will persist the change for future
we advise you to test its validity with the ``certbot renew --dry-run`` command. renewals. If the certificate is not yet due to expire, you will need to force a renewal using ``--force-renewal``.
.. 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. .. note:: Rate limits from the certificate authority may prevent you from performing multiple renewals in a short
period of time. It is strongly recommended to perform the second step only once, when you have decided on what
options should change.
For most tasks, it is safest to limit yourself to pointing symlinks at the files there, or using As a practical example, if you were using the ``webroot`` authenticator and had relocated your website to another directory,
``--deploy-hook`` to copy / make new files based upon those files, if your operational situation requires it you would need to change the ``--webroot-path`` to the new directory. Following the above advice:
(for instance, combining certificates and keys in different way, or having copies of things with different
specific permissions that are demanded by other programs).
If the contents of ``/etc/letsencrypt/archive/CERTNAME`` are moved to a new folder, first specify 1. Perform a *dry-run renewal* of the individual certificate with the amended options::
the new folder's name in the renewal configuration file, then run ``certbot update_symlinks`` to
point the symlinks in ``/etc/letsencrypt/live/CERTNAME`` to the new folder.
If you would like the live certificate files whose symlink location Certbot updates on each run to certbot renew --cert-name example.com --webroot-path /path/to/new/location --dry-run
reside in a different location, first move them to that location, then specify the full path of
each of the four files in the renewal configuration file. Since the symlinks are relative links,
you must follow this with an invocation of ``certbot update_symlinks``.
For example, say that a certificate's renewal configuration file previously contained the following 2. If the dry-run was successful, make the change permanent by performing a *live renewal* of the certificate with the
directives:: amended options, including ``--force-renewal``::
archive_dir = /etc/letsencrypt/archive/example.com certbot renew --cert-name example.com --webroot-path /path/to/new/location --force-renewal
cert = /etc/letsencrypt/live/example.com/cert.pem
privkey = /etc/letsencrypt/live/example.com/privkey.pem
chain = /etc/letsencrypt/live/example.com/chain.pem
fullchain = /etc/letsencrypt/live/example.com/fullchain.pem
The following commands could be used to specify where these files are located:: ``--cert-name`` selects the particular certificate to be modified. Without this option, all certificates will be selected.
``--webroot-path`` is the option intended to be changed. All other previously selected options will be kept the same
and do not need to be included in the command.
For advanced certificate management tasks, it is also possible to manually modify the certificate's renewal configuration
file, but this is discouraged since it can easily break Certbot's ability to renew your certificates. These renewal
configuration files are located at ``/etc/letsencrypt/renewal/CERTNAME.conf``. If you choose to modify the renewal
configuration file we advise you to make a backup of the file beforehand and test its validity with the ``certbot renew --dry-run`` command.
.. warning:: Manually modifying files under ``/etc/letsencrypt/renewal/`` can damage them if done improperly and we do not recommend doing so.
mv /etc/letsencrypt/archive/example.com /home/user/me/certbot/example_archive
sed -i 's,/etc/letsencrypt/archive/example.com,/home/user/me/certbot/example_archive,' /etc/letsencrypt/renewal/example.com.conf
mv /etc/letsencrypt/live/example.com/*.pem /home/user/me/certbot/
sed -i 's,/etc/letsencrypt/live/example.com,/home/user/me/certbot,g' /etc/letsencrypt/renewal/example.com.conf
certbot update_symlinks
Automated Renewals Automated Renewals
------------------ ------------------