Add documentation for .renewal.json format

[adipose]

I have been trying to understand if win-acme has a post-hook script option, like certbot. This script would only run after a successful renewal.

It seems like such an obvious feature to support, but after reading comments about the --script, I've come to understand that it doesn't apply to renewals. One comment was made about "too many options" in reference to this. I don't understand how a single option to run a script would be a big deal.

--postrenewscript

If this is not possible, what is currently the recommended method of restarting apache on windows after a successful renewal?

[WouterTinus]

You are mistaken about the script installation plugin, of course it runs after each succesful renewal.

The comments that you are referring to are about something else. Some people expect/want to be able to modify their renewal parameters (e.g. which script runs) on the fly, at the same time as actually renewing them. But in win-acme configuration and running are mostly seperated.

[adipose]

That makes sense. I have a scheduled task that renews the certs, and I tried adding an "install" script there, but got this error:

Renewal Installation parameters cannot be changed during a renewal. Recreate/overwrite the renewal or edit the .json file if you want to make changes.

Which, naturally, is what you're telling me. But I don't see any obvious documentation on how to modify the .json to add the script. It's probably quite simple, but I don't see the details anywhere.

[WouterTinus]

But I don't see any obvious documentation on how to modify the .json to add the script. It's probably quite simple, but I don't see the details anywhere.

Editing the .json is meant for advanced users. It's pretty straightforward if you're willing to take some time to compare a couple of different renewals, but if you're not planning to script anything then I'd rather suggest going for the first option, which is to simply re-create the renewal.

[adipose]

I did as you said, and went through the process of adding an entirely new entry, so that I could add a single script to the end of my renewal, which was otherwise already set up correctly. But hopefully someone finds my research useful, because it is quite simple, if you only had the documentation to do it. What you need to do is replace the "null" plugin with the "manual script" plugin. Below are two sample entries. You could also add multiple entries inside the brackets, I believe, in case you already had some you wanted to keep.

The secret sauce is in the plugin ids, which seems like a fairly cryptic identifier for those wanting to make a simple update to their settings.

Entry for the null plugin:

  "InstallationPluginOptions": [
    {
      "Plugin": "aecc502c-5f75-43d2-b578-f95d50c79ea1"
    }

Entry for a manual script plugin:

  "InstallationPluginOptions": [
    {
      "Script": "d:\\winacme\\Scripts\\restart_apache.cmd",
      "Plugin": "3bb22c70-358d-4251-86bd-11858363d913"
    }
  ],

The ids come from .cs files in the various plugin folders (https://github.com/win-acme/win-acme/tree/master/src/main.lib/Plugins/InstallationPlugins). For example, the script one can be found here:

https://github.com/win-acme/win-acme/blob/master/src/main.lib/Plugins/InstallationPlugins/Script/ScriptOptions.cs

[WouterTinus]

Thanks for documenting your steps, that might prove to be very useful for someone else looking to do something similar. You can feel free to do a PR to add this to the manual too at https://github.com/win-acme/win-acme.github.io

[adipose]

Happy to, but I can't quite identify the right section for it.

[WouterTinus]

I'd say it probably deserves its own page in the "Advanced usage" section. Then we can link to it from every place where the .json files are mentioned.