Custom script

Perform validation challenge with your own script

Description

Run an external script or program to prepare for the validation challenge. Use this option to create TXT records at DNS providers that are not supported by native plugins (yet?) or to handle HTTP challenges in unconventional ways (e.g. calling into some API, starting a custom web server, etc.)

General

A preparation script is always required to prepare for the challenge answer. Providing a cleanup script to undo any changes made by the former is optional. You may also point to a single script to handle both tasks using different arguments.

Challenge type selection

For backwards compatibility, the script default to handling DNS challenges. To switch to HTTP challenges, you must provide the argument --validationmode http-01 in unattended mode. In interactive mode this will simply be question asked during the setup process.

Argument customization

The plugin has some hard-coded default argument templates which can be overruled according to your needs and preferences. Depending on the chosen challenge type, simple-acme will replace certain pre-defined tokens in the argument template to derive the actual arguments that will be passed to the script, thus enabling dynamic arguments to be passed. For example if your script handles DNS challenges and needs arguments like: ‑‑host _acme-challenge.example.com ‑‑token DGyRejmCefe7v4NfDGDKfA then the argument template provided to simple-acme should look like this: ‑‑host {RecordName} ‑‑token {Token}

DNS challenge arguments

For DNS challenges following replacements are made to the arguments:

Default for preparation: create {Identifier} {RecordName} {Token}

Default for cleanup: delete {Identifier} {RecordName} {Token}

HTTP challenge arguments

For HTTP challenges following replacements are made to the arguments:

Default for preparation: prepare {Identifier} {Path} {Token}

Default for cleanup: cleanup {Identifier} {Path} {Token}

Parallelism

You can use ‑‑validationscriptparallelism to specify if your script supports parallelism. You may use the following values:

Reference scripts

Some reference scripts are available on GitHub, including ones for EasyDNS, ZoneEdit, deSEC and Windows DNS.

External resources

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 parameters and such) in order to use them.

Command line

Examples

JSON

Arguments

Settings