Automatic renewal
Scheduled task
A single scheduled task or cronjob is responsible to renew all certificates created by the program, but will only do so when it’s actually neccessary. The task is created by the program itself after successfully creating the first certificate. The task runs once every day and checks five conditions to determine if it should renew:
- The certificate is getting too old. This is based on the known history and validity dates, recorded in the internal certificate cache and
*.renewal.jsonfiles. Certificates are considered due for renewal when it’s been issued more thanScheduledTask.RenewalDaysdays in the past, or it is valid for less thanScheduledTask.RenewalMinimumValidDaysdays in the future. - The source (list of domains) has changed, e.g. an extra binding has been added to an IIS site.
- The server tells the client that a renewal should happen, e.g. due to a security incident or because of anticipated load peaks. This mechanism is called ACME Renewal Information (ARI) and is a draft specification.
- The certificate has been revoked by the user.
- The certificate has not been succesfully installed yet.
Customization
Some properties for the scheduled task can be changed in settings.json or the Task Scheduler, as long as its name is left unmodified. By default it runs randomly betweem 9:00am and 11:00am (to help spread load at the server) using the SYSTEM account.
Health checks
The health of the scheduled task is checked each time the program is run manually. It can also be (re)created from the menu (More options... > (Re)create scheduled task).
Monitoring
The renewal process can be monitored from the Windows Event Viewer and log files
written to %programdata%\simple-acme\$baseuri$\Log. Logs are retained for 120 days by default. You can also set up notifications to be informed about any problems that the program encounters.
Testing and troubleshooting
To test or troubleshoot the renewal process, renewals can be triggered manually from the menu or the command line with ‑‑renew ‑‑force switches. We recommend doing so while running with the ‑‑verbose parameter to get maximum log visibility. When listing the details for a renewal, the program will show any errors that have been recorded during previous runs.
The program's built in certificate cache protects users from running into rate limits while debugging the renewal process. On a cache hit, the program still goes through all the steps, but doesn't actually request a new certificate from the server. To bypass the cache, the argument ‑‑nocache or the setting Cache.ReuseDays can be used.
Arguments
‑‑renew |
Renew any certificates that are due. This argument is used by the scheduled task. Note that it's not possible to change certificate properties and renew at the same time. | |
|---|---|---|
‑‑force |
[‑‑renew] Always execute the renewal, disregarding the validity of the current certificates and the prefered schedule. | |
‑‑nocache |
Bypass the cache on certificate requests. Applies to both new requests and renewals. |
Settings
ScheduledTask.RenewalDays |
The number of days to renew a certificate after. Let's Encrypt certificates are currently for a max of 90 days so it is advised to not increase the days much.
If you increase the days, please note that you will have less time to fix any issues if the certificate doesn't renew correctly. Default: 55
|
|
|---|---|---|
ScheduledTask.RenewalDaysRange |
To spread service load, program run time and/or to minimize downtime, those managing a large amount of renewals may want to spread them out of the course of multiple days/weeks. The number of days specified here will be substracted from RenewalDays to create a range within which the renewal will e processed. E.g. if RenewalDays is 55 and RenewalDaysRange is 10, the renewal will be processed between 45 and 55 days after issuing.
If you use an order plugin to split your renewal into multiple orders, orders may run on different days.
Type: number Default: 0
|
|
ScheduledTask.RenewalDisableServerSchedule |
By default, servers implementing ARI may suggest that renewals should happen earlier than the regularly scheduled moment. When set to true, ARI suggestions will be ignored (not recommended).
Type: boolean Default: false
|
|
ScheduledTask.RenewalMinimumValidDays |
The minimum number of days a certificate should still be valid. If the certificate is valid for a smaller number of days, it will be renewed regardless of the RenewalDays setting.
Type: number Default: 7
|
|
ScheduledTask.StartBoundary |
Configures start time for the scheduled task.
Type: string Default: "09:00:00"
(9:00 am)
|
|
ScheduledTask.ExecutionTimeLimit |
Configures time after which the scheduled task will be terminated if it hangs for whatever reason.
Type: string Default: "02:00:00"
(2 hours)
|
|
ScheduledTask.RandomDelay |
Configures random time to wait for starting the scheduled task. This spreads the load on the servers and thus prevents users from getting TooManyRequests errors.
Type: string Default: "04:00:00"
(4 hours)
|
|
Cache.ReuseDays |
When renewing or re-creating a previously requested certificate that has the exact same set of domain names, the program will used a cached version for this many days, to prevent users from running into rate limits while experimenting. Set this to a high value if you regularly re-request the same certificates, e.g. for a Continuous Deployment scenario.
Setting this to 0 will not entirely disable the cache (the program also needs the files for different reasons), but it will prevent the files from being used for renewals and will also ensure that no private key material is stored in the cache, unless specifically requested by ‑‑reuse-privatekey.
Type: number Default: 1
|
Looking for win-acme?
simple-acme is a backwards compatible, drop-in replacement built by the same person. Project history.