Skip to content

Renewal Management

Wouter Tinus edited this page Jan 27, 2019 · 2 revisions

Fundamentals

Renewals are stored in the ConfigPath which typically means %ProgramData%\win-acme\acme-v02.api.letsencrypt.org. Each file that fits the pattern *.renewal.json is considered to be a renewal.

File names

The files are randomly named by the program, but you are free to rename them if that suits you. The only requirement is that they must be unique, which is enforced by checking that the "Id" field in the JSON must match with the name of file.

Content

The renewal files consist of three parts:

  • Metadata, e.g. it's identifier, friendly name and the encrypted version of the password that is used for the cached .pfx archive.
  • Plugin configuration, e.g. everything that the plugins need to know to do their jobs, according to the command line arguments and menu choices that were given at creation time.
  • History, e.g. a record of each successful and failed attempt to get a certificate for this renewal.

Creating

  • Creating a renewal can be done interactively from the main menu. The option N uses the easiest defaults for IIS users and the option M offers advanced options, for example for Apache, Exchange, wildcard certificates, etc.
  • Any certificate that can be created from the main menu, can also be created from the command line. The command line even offers some options that the menu does not, check out the documentation about plugins to read all about it.
  • It's also possible to add .json files to the folder yourself, either manually or using some clever tooling or scripting, to create a light-weight integration between your own management tools and win-acme.

Renewing

  • Conditional renewal can be triggered from the main menu (renew scheduled) and from the command line with the --renew switch. The program will then check two conditions to determine if it should request and install a new certificate,
    • If the last successful renewal happened too long ago. This is based on the known history stored in the file and the application setting RenewalDays which defaults to 55 days.
    • If the target has changed since the last successful renewal, e.g. an extra binding has been added to an IIS site.
  • Force renewal can be triggered from the main menu (renew specific/renew all) and from the command line with the --renew --force switches. Then no conditions are checked.

Typically a regular conditional renewal is done by a scheduled task that runs once every day. This is automatically created when configuring the first renewal, or when the user asks for it from the main menu.

Modifying

Many people mistakenly try to modify their renewal by issuing commands like --renew --webroot C:\NewRoot hoping that the existing webroot will be overwritten. The reason this doesn't work is because the renew cycle checks all renewals, each of which can use any of the hundreds of possible combinations of plugins so it's just very complex to figure out what the true intention of such a command should be. Therefore these functions are completely separated.

Modifying a renewal is essential the same as re-creating it, either from the command line or the main menu. If it turns out that a newly configured certificate has the same FriendlyName as a previously created one, then in interactive mode the user is asked whether the new configuration should replace the old one. In unattended mode, its overwritten without asking any questions (the automation calling the program is assumed to know what it's doing).

Cancelling

  • You can cancel a renewal from the main menu. The program will then delete the .json file and forget about it. Nothing is done to the installed certificate, that will keep working until its natural expiry date, which gives you plenty of time to set up a new renewal or find an alternative solution.
  • You can cancel from the command line using the arguments --cancel --friendlyname xxx. The effects are the same as above.
  • You can delete the .json file yourself. The effects are the same as above.

Revoking

  • This is unfortunately not supported by version 2.0 yet. Please use the latest version of WACS 1.9.x if you need this feature.
You can’t perform that action at this time.