Skip to content

Commit 8d6e81c

Browse files
WouterTinusWouterTinus
committed
doc updates
1 parent 01236b5 commit 8d6e81c

File tree

5 files changed

+122
-78
lines changed

5 files changed

+122
-78
lines changed

‎reference/plugins/installation/iis.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,16 @@
22
layout: plugin
33
plugin: ea6a5be3-f8de-4d27-a6bd-750b619b2ee2
44
compatibility: Windows (admin only)
5+
settings:
6+
- Installation.IIS.BindingFlags
57
examples:
68
-
79
name: Typical
810
cmd: '[‑‑installationsiteid 14] [‑‑sslport 8443] [‑‑sslipaddress 192.168.0.1]'
911
---
1012

13+
This plugins manages bindings in the Microsoft IIS web server.
14+
1115
### HTTP binding update algorithm
1216
- Existing HTTPS bindings in *any* web site linked to the previous certificate are updated to use the new certificate.
1317
- Hosts names which are determined to not yet have been covered by any existing binding, will be processed further.

‎reference/plugins/store/certificatestore.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,8 @@ Saves certificates to the Windows Certificate store. This will always import to
1616
## Compatibility
1717
For best compatibility with legacy applications, the program attempts to store certificates with RSA keys using the `Microsoft RSA SChannel Cryptographic Provider`. If you require a more modern approach to key storage, refer to the setting listed below.
1818

19+
# Private key permissions
20+
By default the `administrators` group (or local equivalent) will be granted full control access to the private key, to prevent inconsistent access levels between certificates created by adminstrators (either interactive or unattended) and certificates renewed by the scheduled task (which runs as `SYSTEM`). If you intend to not have administrators able to access the private key, then you must specifically set the permissions to an empty string, e.g. `‑‑acl-fullcontrol ""`.
21+
1922
## Private key export
2023
By default the private keys *not* exportable. This can be changed globally via the settings, but generally we recommend not doing this, because 99% of use cases should be manageable by using another (additional) store step. If you're looking to move the certificate to another server, read more about [migration to another server](/manual/migration).

‎reference/plugins/validation/dns/script.md‎

Lines changed: 3 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,4 @@
11
---
2-
layout: plugin
3-
plugin: 8f1da72e-f727-49f0-8546-ef69e5ecec32
4-
settings:
5-
- Script.PowershellExecutablePath
6-
- Script.Timeout
7-
- Validation.DisableMultiThreading
8-
compatibility: All platforms
9-
examples:
10-
-
11-
name: Create script only
12-
cmd: ‑‑dnscreatescript c:\create.ps1 [‑‑dnscreatescriptarguments {args}]
13-
-
14-
name: Separate create and delete scripts
15-
cmd: ‑‑dnscreatescript c:\create.ps1 ‑‑dnsdeletescript c:\delete.ps1 [‑‑dnscreatescriptarguments {args}] [‑‑dnsdeletescriptarguments {args}]
16-
-
17-
name: Combined script
18-
cmd: ‑‑dnsscript c:\create-and-delete.ps1 [‑‑dnscreatescriptarguments {args}] [‑‑dnsdeletescriptarguments {args}]
19-
---
20-
Run an external script or program to create or update the validation records.
21-
22-
## Create
23-
A script that creates a DNS TXT record at your provider must be provided. The argument template
24-
passed to the script will be `create {Identifier} {RecordName} {Token}` by default, with the following
25-
replacements made by simple-acme:
26-
27-
<div class="table-responsive my-4 me-5 pe-5">
28-
<table class="table table-striped">
29-
<thead>
30-
<tr><th>Value</th><th>Replaced with</th></tr>
31-
</thead>
32-
<tbody>
33-
<tr><td><code>{Identifier}</code></td><td>Host name that's being validated, e.g. <code>sub.example.com</code></td></tr>
34-
<tr><td><code>{RecordName}</code></td><td>Full name of the TXT record that will be queried, e.g. <code>_acme-challenge.sub.example.com</code></td></tr>
35-
<tr><td><code>{ZoneName}</code></td><td>Registerable domain, e.g. <code>example.com</code></td></tr>
36-
<tr><td><code>{NodeName}</code></td><td>Relative record name, e.g. <code>_acme-challenge.sub</code></td></tr>
37-
<tr><td><code>{Token}</code></td><td>Content of the TXT record, e.g. <code>DGyRejmCefe7v4NfDGDKfA</code></td></tr>
38-
<tr><td><code>{vault://json/mysecret}</code></td><td>Secret from the <a href="/manual/advanced-use/secret-management">secret vault</a></td></tr>
39-
</tbody></table></div>
40-
41-
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}`
42-
43-
## Delete
44-
Optionally, another script may be provided to delete the record after validation. The arguments template for that
45-
script is `delete {Identifier} {RecordName} {Token}` by default. The order and format of arguments may be
46-
customized by providing a diffent argument template, just like for the create script.
47-
48-
## Combined
49-
You can also choose to use the same script for create and delete, with each their own argument string.
50-
51-
## Parallelism
52-
You can use `‑‑dnsscriptparallelism` to specify if your script supports parallelism. You may use the following values:
53-
54-
<div class="table-responsive my-4 me-5 pe-5">
55-
<table class="table table-striped">
56-
<thead>
57-
<tr><th>Value</th><th>Meaning</th></tr>
58-
</thead>
59-
<tbody>
60-
<tr><td>0</td><td>Serial, default serial behaviour</td></tr>
61-
<tr><td>1</td><td>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.</td></tr>
62-
<tr><td>2</td><td>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</td></tr>
63-
<tr><td>3</td><td>Combination of 1 and 2</td></tr>
64-
</tbody></table></div>
65-
66-
<div class="callout-block callout-block-warning pb-1 mt-3">
67-
<div class="content">
68-
<p>This only has any effect when <code>DisableParallelism</code> is set to <code>false</code></p>
69-
</div>
70-
</div>
71-
72-
## Reference scripts
73-
Some reference scripts are available on [GitHub](https://github.com/simple-acme/reference-scripts/tree/main/Validation), including ones for EasyDNS, ZoneEdit, deSEC and Windows DNS.
74-
75-
## External esources
76-
A lot of good reference scripts are available from the
77-
[POSH-ACME](https://github.com/rmbolger/Posh-ACME/tree/master/Posh-ACME/DnsPlugins)
78-
project. Note that these scripts are **not compatible** with simple-acme. You will have
79-
to make changes (e.g. in terms of accepted parameters and such) in order to use them.
2+
layout: redirect
3+
target: /reference/plugins/validation/script
4+
---

‎reference/plugins/validation/dns/webnames.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
layout: plugin
3+
plugin: 86c8d86b-2069-4048-9bf1-fadb07e84d61
4+
compatibility: All platforms
5+
examples:
6+
-
7+
name: Default
8+
cmd: ‑‑apiusername johndoe ‑‑apikey *****
9+
---
10+
Create the record at [Webnames](/https://www.webnames.ca/).

‎reference/plugins/validation/script.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
layout: plugin
3+
plugin: 8f1da72e-f727-49f0-8546-ef69e5ecec32
4+
arguments:
5+
- validationmode
6+
settings:
7+
- Script.PowershellExecutablePath
8+
- Script.Timeout
9+
- Validation.DisableMultiThreading
10+
compatibility: All platforms
11+
examples:
12+
-
13+
name: Prepare script only
14+
cmd: ‑‑validationpreparescript c:\create.ps1 [‑‑validationpreparescriptarguments {args}]
15+
-
16+
name: Separate prepare and cleanup scripts
17+
cmd: ‑‑validationpreparescript c:\create.ps1 ‑‑validationcleanupscript c:\delete.ps1 [‑‑validationpreparescriptarguments {args}] [‑‑validationcleanupscriptarguments {args}]
18+
-
19+
name: Combined script
20+
cmd: ‑‑validationscript c:\create-and-delete.ps1 [‑‑validationpreparescriptarguments {args}] [‑‑validationcleanupscriptarguments {args}]
21+
---
22+
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.)
23+
24+
## General
25+
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.
26+
27+
## Challenge type selection
28+
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.
29+
30+
## Argument customization
31+
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}`
32+
33+
## DNS challenge arguments
34+
For DNS challenges following replacements are made to the arguments:
35+
36+
<div class="table-responsive my-4 me-5 pe-5">
37+
<table class="table table-striped">
38+
<thead>
39+
<tr><th>Value</th><th>Replaced with</th></tr>
40+
</thead>
41+
<tbody>
42+
<tr><td><code>{Identifier}</code></td><td>Host name that's being validated, e.g. <code>sub.example.com</code></td></tr>
43+
<tr><td><code>{RecordName}</code></td><td>Full name of the TXT record that will be queried, e.g. <code>_acme-challenge.sub.example.com</code></td></tr>
44+
<tr><td><code>{ZoneName}</code></td><td>Registerable domain, e.g. <code>example.com</code></td></tr>
45+
<tr><td><code>{NodeName}</code></td><td>Relative record name, e.g. <code>_acme-challenge.sub</code></td></tr>
46+
<tr><td><code>{Token}</code></td><td>Content of the TXT record, e.g. <code>DGyRejmCefe7v4NfDGDKfA</code></td></tr>
47+
<tr><td><code>{vault://json/mysecret}</code></td><td>Secret from the <a href="/manual/advanced-use/secret-management">secret vault</a></td></tr>
48+
</tbody></table></div>
49+
50+
Default for preparation: `create {Identifier} {RecordName} {Token}`
51+
52+
Default for cleanup: `delete {Identifier} {RecordName} {Token}`
53+
54+
## HTTP challenge arguments
55+
For HTTP challenges following replacements are made to the arguments:
56+
57+
<div class="table-responsive my-4 me-5 pe-5">
58+
<table class="table table-striped">
59+
<thead>
60+
<tr><th>Value</th><th>Replaced with</th></tr>
61+
</thead>
62+
<tbody>
63+
<tr><td><code>{Identifier}</code></td><td>Identifier that is being validated, e.g. <code>sub.example.com</code></td></tr>
64+
<tr><td><code>{Path}</code></td><td>Relative URI that will be requested (e.g. <code>/.well-known/acme-challenge/2fsdf2</code>)</td></tr>
65+
<tr><td><code>{FileName}</code></td><td>Name of the file that will be requested, e.g. <code>2fsdf2</code></td></tr>
66+
<tr><td><code>{Token}</code></td><td>Expected response content</td></tr>
67+
<tr><td><code>{vault://json/mysecret}</code></td><td>Secret from the <a href="/manual/advanced-use/secret-management">secret vault</a></td></tr>
68+
</tbody></table></div>
69+
70+
Default for preparation: `prepare {Identifier} {Path} {Token}`
71+
72+
Default for cleanup: `cleanup {Identifier} {Path} {Token}`
73+
74+
## Parallelism
75+
You can use `‑‑validationscriptparallelism` to specify if your script supports parallelism. You may use the following values:
76+
77+
<div class="table-responsive my-4 me-5 pe-5">
78+
<table class="table table-striped">
79+
<thead>
80+
<tr><th>Value</th><th>Meaning</th></tr>
81+
</thead>
82+
<tbody>
83+
<tr><td><code>0</code></td><td>Serial, default serial behaviour</td></tr>
84+
<tr><td><code>1</code></td><td>Allow multiple validations to be prepared at the same time. Only do this when you are sure multiple instances of "prepare" running at the same time will not interfere with eachother. Typically difficult to achieve and therefor not recommended.</td></tr>
85+
<tr><td><code>2</code></td><td>Allow multiple validations to run at the same time. This is possible in theory with every method, but you must be sure that your script is non-destructive, e.g. it should not overwrite pre-existing records or files, nor delete more than what is specifically asked for</td></tr>
86+
<tr><td><code>3</code></td><td>Combination of 1 and 2</td></tr>
87+
</tbody></table></div>
88+
89+
<div class="callout-block callout-block-warning pb-1 mt-3">
90+
<div class="content">
91+
<p>This only has any effect when <code>DisableParallelism</code> is set to <code>false</code></p>
92+
</div>
93+
</div>
94+
95+
## Reference scripts
96+
Some reference scripts are available on [GitHub](https://github.com/simple-acme/reference-scripts/tree/main/Validation), including ones for EasyDNS, ZoneEdit, deSEC and Windows DNS.
97+
98+
## External resources
99+
A lot of good reference scripts are available from the
100+
[POSH-ACME](https://github.com/rmbolger/Posh-ACME/tree/master/Posh-ACME/DnsPlugins)
101+
project. Note that these scripts are **not compatible** with simple-acme. You will have
102+
to make changes (e.g. in terms of accepted parameters and such) in order to use them.

0 commit comments

Comments
 (0)