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 succesful 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.
Example scripts
Many examples of .ps1 scripts are included with the program in the Scripts folder included in the main distribution package, for example for Exchange, RDS and SQL Server. Please use these as a reference only.
Example scripts have been tested by their authors, but as always you should exercise extreme caution when running something that you find on the internet, because every environment is different. You may have a different system design or software versions, so always test thoroughly and create your own local copy to prevent future versions of the example from causing issues.
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 and DNS 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.