External program
Solving the DNS-01 challenge using an external program.
- Code:
exec - Since: v0.5.0
Here is an example bash command using the External program provider:
EXEC_PATH=/the/path/to/myscript.sh \
lego --email you@example.com --dns exec -d '*.example.com' -d example.com runBase Configuration
| Environment Variable Name | Description |
|---|---|
EXEC_MODE |
RAW, none |
EXEC_PATH |
The path of the the external program. |
Additional Configuration
| Environment Variable Name | Description |
|---|---|
EXEC_POLLING_INTERVAL |
Time between DNS propagation check in seconds (Default: 3). |
EXEC_PROPAGATION_TIMEOUT |
Maximum waiting time for DNS propagation in seconds (Default: 60). |
EXEC_SEQUENCE_INTERVAL |
Time between sequential requests in seconds (Default: 60). |
Description
The file name of the external program is specified in the environment variable EXEC_PATH.
When it is run by lego, three command-line parameters are passed to it: The action (“present” or “cleanup”), the fully-qualified domain name and the value for the record.
For example, requesting a certificate for the domain ‘my.example.org’ can be achieved by calling lego as follows:
EXEC_PATH=./update-dns.sh \
lego --email you@example.com --dns exec --d my.example.org runIt will then call the program ‘./update-dns.sh’ with like this:
./update-dns.sh "present" "_acme-challenge.my.example.org." "MsijOYZxqyjGnFGwhjrhfg-Xgbl5r68WPda0J9EgqqI"The program then needs to make sure the record is inserted. When it returns an error via a non-zero exit code, lego aborts.
When the record is to be removed again,
the program is called with the first command-line parameter set to cleanup instead of present.
If you want to use the raw domain, token, and keyAuth values with your program, you can set EXEC_MODE=RAW:
EXEC_MODE=RAW \
EXEC_PATH=./update-dns.sh \
lego --email you@example.com --dns exec -d my.example.org runIt will then call the program ./update-dns.sh like this:
./update-dns.sh "present" "--" "my.example.org." "some-token" "KxAy-J3NwUmg9ZQuM-gP_Mq1nStaYSaP9tYQs5_-YsE.ksT-qywTd8058G-SHHWA3RAN72Pr0yWtPYmmY5UBpQ8"Commands
The -- is because the token MAY start with a -, and the called program may try and interpret a - as indicating a flag.
In the case of urfave, which is commonly used,
you can use the -- delimiter to specify the start of positional arguments, and handle such a string safely.
Present
| Mode | Command |
|---|---|
| default | myprogram present <FQDN> <record> |
RAW |
myprogram present -- <domain> <token> <key_auth> |
Cleanup
| Mode | Command |
|---|---|
| default | myprogram cleanup <FQDN> <record> |
RAW |
myprogram cleanup -- <domain> <token> <key_auth> |