Custom script
Create verification records with your own script
| Plugin type | DNS validation | |
|---|---|---|
| Download | Built-in | |
| Compatibility | All platforms |
Description
Run an external script or program to create or update the validation records.
Create
A script that creates a DNS TXT record at your provider must be provided. The argument template
passed to the script will be create {Identifier} {RecordName} {Token} by default, with the following
replacements made by simple-acme:
| Value | Replaced with |
|---|---|
{Identifier} | Host name that's being validated, e.g. sub.example.com |
{RecordName} | Full name of the TXT record that will be queried, e.g. _acme-challenge.sub.example.com |
{ZoneName} | Registerable domain, e.g. example.com |
{NodeName} | Relative record name, e.g. _acme-challenge.sub |
{Token} | Content of the TXT record, e.g. DGyRejmCefe7v4NfDGDKfA |
{vault://json/mysecret} | Secret from the secret vault |
The order and format of arguments may be customized by providing a diffent argument template. For example if your script needs arguments like: ‑‑host _acme-challenge.example.com ‑‑token DGyRejmCefe7v4NfDGDKfA then the argument template string provided to simple-acme should look like this: ‑‑host {RecordName} ‑‑token {Token}
Delete
Optionally, another script may be provided to delete the record after validation. The arguments template for that
script is delete {Identifier} {RecordName} {Token} by default. The order and format of arguments may be
customized by providing a diffent argument template, just like for the create script.
Combined
You can also choose to use the same script for create and delete, with each their own argument string.
Parallelism
You can use ‑‑dnsscriptparallelism to specify if your script supports parallelism. You may use the following values:
| Value | Meaning |
|---|---|
| 0 | Serial, default serial behaviour |
| 1 | Allow multiple new records to created as the same time. Only do this when you are sure multiple instances of "create" running at the same time will not interfere with eachother. Typically difficult to achieve and therefor not recommended. |
| 2 | Allow multiple validations to run at the same time. This is possible in theory with any DNS provider, but you must be sure that your script is non-destructive, e.g. it should not overwrite pre-existing TXT records, nor delete more than the one specifically asked for |
| 3 | Combination of 1 and 2 |
This only has any effect when DisableParallelism is set to false
External esources
A lot of good reference scripts are available from the POSH-ACME project. Note that these scripts are not compatible with simple-acme. You will have to make changes (e.g. in terms of accepted parameter and such) in order to use them.
Command line
--validation script |
Activates the plugin | |
|---|---|---|
‑‑dnsscript |
Path to script that creates and deletes validation records, depending on its parameters. If this parameter is provided then ‑‑dnscreatescript and ‑‑dnsdeletescript are ignored. | |
‑‑dnscreatescript |
Path to script that creates the validation TXT record. | |
‑‑dnscreatescriptarguments |
Default parameters passed to the script are "create {Identifier} {RecordName} {Token}", but that can be customized using this argument. | |
‑‑dnsdeletescript |
Path to script to remove TXT record. | |
‑‑dnsdeletescriptarguments |
Default parameters passed to the script are "delete {Identifier} {RecordName} {Token}", but that can be customized using this argument. | |
‑‑dnsscriptparallelism |
Configure parallelism mode. 0 is fully serial (default), 1 allows multiple records to be created simultaneously, 2 allows multiple records to be validated simultaneously and 3 is a combination of both forms of parallelism. |
Examples
| Create script only | --validation script ‑‑dnscreatescript c:\create.ps1 [‑‑dnscreatescriptarguments {args}] |
|
|---|---|---|
| Separate create and delete scripts | --validation script ‑‑dnscreatescript c:\create.ps1 ‑‑dnsdeletescript c:\delete.ps1 [‑‑dnscreatescriptarguments {args}] [‑‑dnsdeletescriptarguments {args}] |
|
| Combined script | --validation script ‑‑dnsscript c:\create-and-delete.ps1 [‑‑dnscreatescriptarguments {args}] [‑‑dnsdeletescriptarguments {args}] |
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
|
|
Validation.DisableMultiThreading |
Disable multithreading features for validation. Inceases runtime but may help to fix bugs caused by race conditions.
Type: boolean Default: true
|
JSON
| ID | 8f1da72e-f727-49f0-8546-ef69e5ecec32 |
|---|
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
|
|
Validation.DisableMultiThreading |
Disable multithreading features for validation. Inceases runtime but may help to fix bugs caused by race conditions.
Type: boolean Default: true
|
Looking for win-acme?
simple-acme is a backwards compatible, drop-in replacement built by the same person. Project history.