Custom script
Start external script or program
| Plugin type | Installation | |
|---|---|---|
| Download | Built-in | |
| Compatibility | All platforms |
Description
Runs an external script or executable after a successful renewal. This may be a .bat or .exe on Windows, .sh on Linux or .ps1 on all platforms. You provide the program with the path to the script and it will run automatically.
Reference scripts
Many examples of .ps1 scripts are published on GitHub, including ones for Exchange, RDS, WinRM, Admin Center, SSTP, SQL Server, Java KeyStore (JKS), Azure, Sparx and Veeam. Please use these as a reference only.
Reference scripts have been tested by their authors, but as always you should exercise extreme caution when running something that you find on the internet. Your configuration or software versions may be different than those of the original contributor, so always test thoroughly and maintain your own local copy.
Parameter replacement
The following variables can be provided from the program to the script as command line arguments.
| Value | Replaced with |
|---|---|
{0} or {CertCommonName} | Common name (primary domain name) of the newly issued certificate |
{1} or {CachePassword} | The .pfx password (generated randomly for each renewal) |
{2} or {CacheFile} | Full path of the cached .pfx file (*) |
{6} or {CacheFolder} | Directory containing the cached .pfx file (*) |
{4} or {CertFriendlyName} | Friendly name of the newly issued certificate |
{5} or {CertThumbprint} | Thumbprint of the newly issued certificate |
{7} or {RenewalId} | Id of the renewal i.e. xxx when renewing xxx.renewal.json |
{3} or {StorePath} | Path or store name used by the (first) store plugin |
{StoreType} | Name of the (first) store plugin (e.g. CentralSsl or PemFiles) |
{OldCertCommonName} | Common name (primary domain name) of the previously issued certificate |
{OldCertFriendlyName} | Common name (primary domain name) of the previously issued certificate |
{OldCertThumbprint} | Common name (primary domain name) of the previously issued certificate |
{vault://json/mysecret} | Secret from the secret vault |
(*) This parameter will be empty if cache is disabled
Replacement example
If you need your scripts parameters to look something like this: action=import file=C:\mydomain.pfx password=***** Then your argument string should look like this: action=import file={CacheFile} password={CachePassword}
Parameter escaping
If you need to put double quotes around your parameters from the command line, you have to escape them with a slash, for example:
‑‑scriptparameters "action=import file=\"{CacheFile}\" password=\"{CachePassword}\""
For Powershell scripts, string parameters can also be delimited with single quotes, for example:
‑‑scriptparameters "action=import file='{CacheFile}' password='{CachePassword}'"
Command line
--installation script |
Activates the plugin | |
|---|---|---|
‑‑script |
Path to script file to run after retrieving the certificate. This may be any executable file or a Powershell (.ps1) script. | |
‑‑scriptparameters |
Parameters for the script to run after retrieving the certificate. Refer to /reference/plugins/installation/script for further instructions. |
Examples
| Typical | --installation script ‑‑script C:\script.bat [‑‑scriptparameters x] |
|---|
JSON
| ID | 3bb22c70-358d-4251-86bd-11858363d913 |
|---|
Settings
Script.PowershellExecutablePath |
Customize this value to use a different version of Powershell to execute .ps1 scripts. E.g. C:\\Program Files\\PowerShell\\6.0.0\\pwsh.exe for Powershell Core 6.
Paths should be JSON-encoded, e.g. Default: "powershell.exe"
|
|
|---|---|---|
Script.Timeout |
Time in seconds to allow installation, executing and validation scripts to run before terminating them forcefully.
Type: number Default: 600
|
Looking for win-acme?
simple-acme is a backwards compatible, drop-in replacement built by the same person. Project history.