We know a lot of Public Beta users will need to renew certificates soon and our existing recommendations for how to do so require a little more scripting than we’d like. (Fortunately, people have posted a lot of recipes that are working well for them in various environments—thanks for those contributions!)
We wanted to offer something better in our Python client to automatically renew certs that are near expiry (for people who got their certs using that client). We’ve decided on a new approach called
letsencrypt renew, which does a better job of remembering the settings you chose when obtaining a cert, and of reporting the results of renewal cleanly.
We’d like for people who are willing to give this a try and let us know how it works for you!
To help us test
letsencrypt renew before the 0.4.0 release, you need to get the development version of the client from git:
Then you can run it and tell us what happens and whether you found anything confusing or whether anything was broken in your situation. Currently,
letsencrypt renew tries to renew all certificates that it regards as due for renewal. If you have a large number of certificates, you may want to consider how this interacts with the rate limit; there’s another thread talking about our efforts to make sure that the rate limit won’t interfere with certificate renewals.
Q. What’s the difference between
letsencrypt renew and
letsencrypt certonly is used to obtain a single certificate (which might be a renewal of a previous one if you specify exactly the same domain names with
-d). It aims to let you choose parameters for that cert from scratch, rather than using any of the parameters from a previously-obtained cert.
letsencrypt renew is used to renew many certificates (if necessary), using the same parameters and defaults that were originally chosen at the time that each one was first obtained.
Q. How does
letsencrypt renew remember my settings?
letsencrypt renew uses a set of conf files in
/etc/letsencrypt/renew to remember how certificates were obtained. For now, it’s advisable to view those files as a magical black box; in version 0.5.0 we’ll be cleaning them up and documenting their contents for users who want to tweak things. Important note: if you generated a certificate with client versions 0.3.0 or below, and then renewed it manually using different settings, you may need to perform a another manual renewal with code from git master / 0.4.0+ before
letsencrypt renew works for you. That’s because previous versions of the client would write descriptions of certificate “lineages” (series of certificates that replace each other) to /etc/letsencrypt/renew, but never update those conf files if the user switched to different settings. This has been fixed in git, and will ship in 0.4.0.
Q. What’s the new
A. The new
--dry-run flag for both
renew performs the certificate request(s) against the staging server, which issues test certificates that are not trusted by browsers. This verifies whether you’re apparently able to get a certificate, in your current configuration, using the method that you specified (for example, if you were using
webroot authentication, whether your
webroot configuration is capable of being validated by the CA). With
--dry-run, the certificates obtained are not actually saved to disk and your configuration is not updated. You can use this to simulate what would apparently happen if you ran the command without
Q. Why does
letsencrypt renew only renew some certificates?
letsencrypt renew has a notion of when certificates are due for renewal, currently 30 days before their expiry. We will soon document ways of changing this. Only certificates that are due for renewal get renewed, unless you specify
letsencrypt renew --renew-by-default, which attempts to renewal all certificates, regardless of how old they are.
letsencrypt renew work with the standalone plugin?
A. Yes, but you may need to stop your web server first and then start it again afterwards. If you have some cert lineages that use standalone, and some that use webroot, you won’t be able to get a single run of
letsencrypt renew that works for everything at once, and may wish to keep using renewal via “certonly”
Q. Can I automate
letsencrypt renew to run from
A. When 0.4.0 is released, yes. Right now
letsencrypt renew is being tested, so we can’t promise that nothing will change for the release.
Q. Okay, if this thing is going to be run from
cron, why does it print output?
cron needs it to be silent…
A. For the time being it will be best to wrap
letsencrypt renew in a simple script. We considered implementing
--quiet, and will probably still do so in the future, but unfortunately suppressing output in case of success isn’t a satisfactory renewal solution. The problem is that a cert renew command can have two kinds of success: (1) it succeeded because no certs were due for renewal; (2) some certs were due for renewal and it succeeded in renewing them. UNIX only supports one type of “success” return code. But in many situations those calling the renewer will need to know the difference between the two types of success because in case (2), extra legwork such as reloading TLS servers (the ones that don’t have client installer plugins) needs to happen. So for 0.4.0, we will recommend a small script to grep or redirect the output of
letsencrypt renew in your
Q. Do renewals count against the rate limit?
A. Yes, currently renewals count against the rate limit in the same way as new certs. It is possible to hit the rate limit using
letsencrypt renew and have it fail or partially fail for that reason. Rate limit policies related to renewals may be adjusted in the future.
Q. What’s this
-n for short) is a feature we shipped in 0.3.0. It ensures that the client will never stop to ask the user a question: if there isn’t a sensible default answer to a question, an error will be raised. This is ideal for any scripting of the client (including renewal), and also good for power users on the command line. You can use it to replace the combination of
--keep in previously written renewal scripts.