diff options
Diffstat (limited to 'docs/reference')
| -rw-r--r-- | docs/reference/plugins/index.md | 2 | ||||
| -rw-r--r-- | docs/reference/plugins/installation/iisftp.md | 2 | ||||
| -rw-r--r-- | docs/reference/plugins/installation/iisweb.md | 14 | ||||
| -rw-r--r-- | docs/reference/plugins/installation/script.md | 24 | ||||
| -rw-r--r-- | docs/reference/plugins/target/iis-site.md | 2 | ||||
| -rw-r--r-- | docs/reference/plugins/target/iis-sites.md | 2 | ||||
| -rw-r--r-- | docs/reference/plugins/target/manual.md | 3 | ||||
| -rw-r--r-- | docs/reference/plugins/validation/dns/acme-dns.md | 3 | ||||
| -rw-r--r-- | docs/reference/plugins/validation/dns/index.md | 4 | ||||
| -rw-r--r-- | docs/reference/plugins/validation/dns/script.md | 22 | ||||
| -rw-r--r-- | docs/reference/plugins/validation/http/index.md | 11 | ||||
| -rw-r--r-- | docs/reference/plugins/validation/http/sftp.md | 2 | ||||
| -rw-r--r-- | docs/reference/plugins/validation/index.md | 2 | ||||
| -rw-r--r-- | docs/reference/settings.md | 226 |
14 files changed, 169 insertions, 150 deletions
diff --git a/docs/reference/plugins/index.md b/docs/reference/plugins/index.md index 7880fc7..1b0e617 100644 --- a/docs/reference/plugins/index.md +++ b/docs/reference/plugins/index.md @@ -7,7 +7,7 @@ sidebar: reference Conceptually win-acme works by chaining together five components also known as plugins, which can be mixed and matched to support many use cases. - A [target plugin](/win-acme/reference/plugins/target/) provides information about (potential) certificates to create. -- A [validation plugin](/win-acme/reference/plugins/validation/) provides the ACME server with proof that you own the domains(s). +- A [validation plugin](/win-acme/reference/plugins/validation/) provides the ACME server with proof that you own the domain(s). - A [CSR plugin](/win-acme/reference/plugins/csr/) determines the (type of) private key and extensions to use for the certificate. - One or more [store plugins](/win-acme/reference/plugins/store/) place the certificate in a specific location and format. - One or more [installation plugins](/win-acme/reference/plugins/installation/) make changes to your application(s) configuration.
\ No newline at end of file diff --git a/docs/reference/plugins/installation/iisftp.md b/docs/reference/plugins/installation/iisftp.md index 416e5fb..393179c 100644 --- a/docs/reference/plugins/installation/iisftp.md +++ b/docs/reference/plugins/installation/iisftp.md @@ -9,4 +9,4 @@ Create or update FTP site bindings in IIS, according to the following logic: - The target FTP site will be updated to use the new certificate. ## Unattended -``--installation iisftp [--installationsiteid x]`
\ No newline at end of file +`--installation iisftp [--ftpsiteid x]`
\ No newline at end of file diff --git a/docs/reference/plugins/installation/iisweb.md b/docs/reference/plugins/installation/iisweb.md index 2a04dc1..c9d2cef 100644 --- a/docs/reference/plugins/installation/iisweb.md +++ b/docs/reference/plugins/installation/iisweb.md @@ -16,14 +16,14 @@ Create or update website bindings in IIS, according to the following logic: `--sslipaddress` switches. - New bindings will be created or updated for matching host headers with the most specific match. E.g. if you generate a certificate for `a.b.c.com`, the order of preference for the binding creation/change will be: - 1. a.b.c.com - 2. *.b.c.com - 3. *.c.com - 4. *.com - 5. Default (emtpy) binding + 1. `a.b.c.com` + 2. `*.b.c.com` + 3. `*.c.com` + 4. `*.com` + 5. `*` (Default/empty binding) - If the certificate contains a wildcard domain, the order of preference will be: - 1. *.a.b.c.com - 2. x.a.b.c.com + 1. `*.a.b.c.com` + 2. `x.a.b.c.com` - In both cases, the first preferred option will be created from scratch if none of the later options are available. - In some cases the plugin will not be able to (safely) add a new binding on older versions of IIS, e.g. due to diff --git a/docs/reference/plugins/installation/script.md b/docs/reference/plugins/installation/script.md index 3274ca8..70a895a 100644 --- a/docs/reference/plugins/installation/script.md +++ b/docs/reference/plugins/installation/script.md @@ -9,17 +9,17 @@ You provide the program with the path to the script and it will run automaticall ## Parameters The following variables can be provided from the program to the script as command line arguments. -``` -{0} or {CertCommonName} - Common name (primary domain name) -{1} or {CachePassword} - The .pfx password (generated randomly for each renewal) -{2} or {CacheFile} - Full path of the cached.pfx file -{4} or {CertFriendlyName} - Friendly name of the generated certificate -{5} or {CertThumbprint} - Thumbprint of the generated certificate -{7} or {RenewalId} - Id of the renewal - -{3} or {6} or {StorePath} - Path or store name used by the store plugin -{StoreType} - Name of the plugin (CentralSsl, CertificateStore or PemFiles) -``` +| Value | Replaced with | +|----------------|----------------| +| `{0}` or `{CertCommonName}` | Common name (primary domain name) | +| `{1}` or `{CachePassword}` | The .pfx password (generated randomly for each renewal) | +| `{2}` or `{CacheFile}` | Full path of the cached.pfx file | +| `{4}` or `{CertFriendlyName}` | Friendly name of the generated certificate | +| `{5}` or `{CertThumbprint}` | Thumbprint of the generated certificate | +| `{7}` or `{RenewalId}` | Id of the renewal | +| `{3}` or `{6}` or `{StorePath}` | Path or store name used by the (first) store plugin | +| `{StoreType}` | Name of the plugin (CentralSsl, CertificateStore or PemFiles) | + ## Example If you need your scripts parameters to look something like this: @@ -40,4 +40,4 @@ If you need to put double quotes around your parameters from the command line, y For **Powershell** scripts, string parameters can also be delimited with single quotes, for example: -`--scriptparameters "action=import file='{CacheFile}' password='{CachePassword}'"` +`--scriptparameters "action=import file='{CacheFile}' password='{CachePassword}'"`
\ No newline at end of file diff --git a/docs/reference/plugins/target/iis-site.md b/docs/reference/plugins/target/iis-site.md index efe5d78..8b4aeec 100644 --- a/docs/reference/plugins/target/iis-site.md +++ b/docs/reference/plugins/target/iis-site.md @@ -8,4 +8,4 @@ Create target based on all bindings of an IIS site. - Automatically adds/removes host names based on bindings ## Unattended -`--target iissite --siteid 1 [--excludebindings exclude.example.com]`
\ No newline at end of file +`--target iissite --siteid 1 [--commonname common.example.com] [--excludebindings exclude.example.com]`
\ No newline at end of file diff --git a/docs/reference/plugins/target/iis-sites.md b/docs/reference/plugins/target/iis-sites.md index 9d8d685..573b148 100644 --- a/docs/reference/plugins/target/iis-sites.md +++ b/docs/reference/plugins/target/iis-sites.md @@ -8,4 +8,4 @@ Create target based on all bindings of multiple IIS sites. - Automatically adds/removes host names based on bindings ## Unattended -`--target iissites --siteid 1,2,3 [--excludebindings exclude.example.com]`
\ No newline at end of file +`--target iissites --siteid 1,2,3 [--commonname common.example.com] [--excludebindings exclude.example.com]`
\ No newline at end of file diff --git a/docs/reference/plugins/target/manual.md b/docs/reference/plugins/target/manual.md index f5ce220..4422c40 100644 --- a/docs/reference/plugins/target/manual.md +++ b/docs/reference/plugins/target/manual.md @@ -3,8 +3,7 @@ sidebar: reference --- # Manual -Manually input host names -- The first name will be the common name of the certificate +Manually input host names. The first name will be the common name of the certificate, the other will only be in the SAN list. ## Unattended `--target manual --host a.example.com,b.example.com`
\ No newline at end of file diff --git a/docs/reference/plugins/validation/dns/acme-dns.md b/docs/reference/plugins/validation/dns/acme-dns.md index 9688fe7..8856cda 100644 --- a/docs/reference/plugins/validation/dns/acme-dns.md +++ b/docs/reference/plugins/validation/dns/acme-dns.md @@ -6,7 +6,8 @@ sidebar: reference Use an [acme-dns](https://github.com/joohoi/acme-dns) server to handle the validation records. The plugin will ask you to choose an endpoint to use. For testing the `https://auth.acme-dns.io/` endpoint is useful, but it is a security concern. As the readme of that project clearly states: -"You are encouraged to run your own acme-dns instance." + +> "You are encouraged to run your own acme-dns instance." ## Unattended Not supported, unless there is a pre-existing acme-dns registration for all the domains. diff --git a/docs/reference/plugins/validation/dns/index.md b/docs/reference/plugins/validation/dns/index.md index 16403f8..84251f5 100644 --- a/docs/reference/plugins/validation/dns/index.md +++ b/docs/reference/plugins/validation/dns/index.md @@ -5,8 +5,8 @@ sidebar: reference # DNS validation DNS validation works as follows: - For each domain, e.g. `sub.example.com`, the ACME server provides a -challenge consisting of an `x` and `y` value (it's a little more complicated than that, -but for the sake of this explanation it will suffice). +challenge consisting of an `x` and `y` value. The truth is actually a little +more complicated than that, but for the sake of this explanation it will suffice. - The client has to make sure that when the ACME server requests the TXT records for `_acme-challenge.sub.example.com`, there should be at least one record called `x` with content `"y"`. diff --git a/docs/reference/plugins/validation/dns/script.md b/docs/reference/plugins/validation/dns/script.md index f241d32..8e85f1f 100644 --- a/docs/reference/plugins/validation/dns/script.md +++ b/docs/reference/plugins/validation/dns/script.md @@ -7,19 +7,21 @@ Run an external script or program to create or update the validation records. ## Create A script to create the DNS record must be provided. The arguments passed to the -script will be `create {Identifier} {RecordName} {Token}` by default, with: +script will be `create {Identifier} {RecordName} {Token}` by default, where the +following replacements are made by win-acme: -- `create` - fixed value -- `{Identifier}` - host name that's being validated, e.g. `sub.example.com` -- `{RecordName}` - full name of the TXT record that is being expected, e.g. `_acme-challenge.sub.example.com` -- `{Token}` - content of the TXT record, e.g. `DGyRejmCefe7v4NfDGDKfA` +| Value | Replaced with | +|----------------|----------------| +| `{Identifier}` | host name that's being validated, e.g. `sub.example.com` | +| `{RecordName}` | full name of the TXT record that is being expected, e.g. `_acme-challenge.sub.example.com` | +| `{Token}` | content of the TXT record, e.g. `DGyRejmCefe7v4NfDGDKfA` | The order and format of arguments may be customized by providing a diffent argument string. -For example if your script needs arguments like... +For example if your script needs arguments like: `--host _acme-challenge.example.com --token DGyRejmCefe7v4NfDGDKfA` -...your argument string should be +...your argument string should like like this: `--host {RecordName} --token {Token}` @@ -35,9 +37,9 @@ A lot of good example scripts are available from the project. ## Unattended -- Create script only: +- ### Create script only `-validationmode dns-01 --validation dnsscript --dnscreatescript c:\create.ps1 [--dnscreatescriptarguments {args}]` -- Create and delete scripts seperate: +- ### Create and delete scripts seperate `-validationmode dns-01 --validation dnsscript --dnscreatescript c:\create.ps1 --dnsdeletescript c:\delete.ps1 [--dnscreatescriptarguments {args}] [--dnsdeletescriptarguments {args}]` -- Create and delete script (integrated): +- ### Create-delete script (integrated) `-validationmode dns-01 --validation dnsscript --dnsscript c:\create-and-delete.ps1 [--dnscreatescriptarguments {args}] [--dnsdeletescriptarguments {args}]`
\ No newline at end of file diff --git a/docs/reference/plugins/validation/http/index.md b/docs/reference/plugins/validation/http/index.md index 41a4f3d..25c8164 100644 --- a/docs/reference/plugins/validation/http/index.md +++ b/docs/reference/plugins/validation/http/index.md @@ -4,13 +4,14 @@ sidebar: reference # HTTP validation HTTP validation works as follows: -- For each domain, e.g. `sub.example.com`, the ACME server provides a -challenge consisting of an `x` and `y` value (it's a little more complicated than that, -but for the sake of this explanation it will suffice). +- For each domain (e.g. `sub.example.com`), the ACME server sends a +challenge consisting of an `x` and `y` value. The truth is actually a little +more complicated than that, but for the sake of this explanation it will suffice. - The client has to make sure that when the ACME server makes a request -to `http://sub.example.com/.well-known/acme-challenge/x`, the answer will be exactly `y`. +to `http://sub.example.com/.well-known/acme-challenge/x`, the content of the HTTP +response will be `y` with some specific headers set as well. - The validation request is *always* made to port 80, that cannot be changed. -- Let's Encrypt **does** follow 301/302 redirects +- The ACME server **does** follow 301/302 redirects. - There may be more than one validation request for the same token, e.g. from different locations or different protocols (IPv4/IPv6). - Let's Encrypt does **not** disclose the source locations of these requests, which diff --git a/docs/reference/plugins/validation/http/sftp.md b/docs/reference/plugins/validation/http/sftp.md index ab565fe..62d59cc 100644 --- a/docs/reference/plugins/validation/http/sftp.md +++ b/docs/reference/plugins/validation/http/sftp.md @@ -3,7 +3,7 @@ sidebar: reference --- # SFTP -This plugin uploads the validation challenge to a SSH FTP / SFTP server. +This plugin uploads the validation challenge to a SSH FTP, also known as SFTP, server. {% include validation-http-common.md %} diff --git a/docs/reference/plugins/validation/index.md b/docs/reference/plugins/validation/index.md index f5b8f0d..56e4254 100644 --- a/docs/reference/plugins/validation/index.md +++ b/docs/reference/plugins/validation/index.md @@ -7,7 +7,7 @@ sidebar: reference A validation plugin is responsible for providing the ACME server with proof that you own the identifiers (host names) that you want to create a certificate for. The [ACMEv2 protocol](https://tools.ietf.org/html/draft-ietf-acme-acme-18) defines different challenge types, -two whom are supported by Let's Encrypt and win-acme, namely [HTTP-0](/win-acme/reference/plugins/validation/http/) and +two whom are supported by Let's Encrypt and win-acme, namely [HTTP-01](/win-acme/reference/plugins/validation/http/) and [DNS-01](/win-acme/reference/plugins/validation/dns/). For wildcard identifiers, only DNS validation is accepted by Let's Encrypt. diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 7712029..714086e 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -9,6 +9,8 @@ created on first run, copied from `settings_default.config`. This allows you to xcopy new releases without worrying about overwriting your previously customized settings. +## UI + ### `FileDateFormat` Default: `'yyyy/M/d H:mm:ss'` @@ -16,88 +18,46 @@ A string that is used to format the date of the pfx file friendly name. [Documentation](https://msdn.microsoft.com/en-us/library/8kb3ddd4(v=vs.110).aspx) for possibilities is available from Microsoft. -### `RSAKeyBits` -Default: `3072` - -The key size to sign the certificate with. Minimum is 1024. - ### `HostsPerPage` Default: `50` The number of hosts to display per page. -### `ClientName` -Default: `win-acme` - -The name of the client, which comes back in the scheduled task and the `ConfigurationPath`. - -### `ConfigurationPath` -Default: `''` (empty) - -Change the location where the program stores its (temporary) files. If not specified -this resolves to `%programdata%\[ClientName]\[BaseUri]` - -### `CertificatePath` -Default: `''` (empty) - -The path where certificates and request files are stored. If not specified or invalid, -this defaults to `(ConfigurationPath)\Certificates`. All directories and subdirectories -in the specified path are created unless they already exist. If you are using a -[[Central SSL Store|Store-Plugins#centralssl]], this can **not** be set to the same path. - -### `RenewalDays` -Default: `55` - -The number of days to renew a certificate after. Let's Encrypt certificates are -currently for a max of 90 days so it is advised to not increase the days much. -If you increase the days, please note that you will have less time to fix any -issues if the certificate doesn't renew correctly. - -### `DefaultCertificateStore` -Default: `''` (empty) - -The certificate store to save the certificates in. If left empty, certificates will -be installed either in the `WebHosting` store, or if that is not available, -the `My` store (better known as `Personal`). +## ACME settings -### `DefaultCentralSslStore` -Default: `''` (empty) +### `DefaultBaseUri` +Default: `https://acme-v02.api.letsencrypt.org/` -When using `--store centralssl` this path is used by default, saving you the -effort from providing it manually. Filling this out makes the `--centralsslstore` -parameter unnecessary in most cases. Renewals created with the default path will -automatically change to any future default value, meaning this is also a good -practice for maintainability. +Default ACMEv2 endpoint to use when none is specified with +the command line. -### `DefaultCentralSslPfxPassword` -Default: `''` (empty) +### `DefaultBaseUriTest` +Default: `https://acme-staging-v02.api.letsencrypt.org/` -When using `--store centralssl` this password is used by default for the pfx -files, saving you the effort from providing it manually. Filling this out makes -the `--pfxpassword` parameter unnecessary in most cases. Renewals created with -the default password will automatically change to any future default value, -meaning this is also a good practice for maintainability. +Default ACMEv2 endpoint to use when none is specified with +the command line and the `--test` switch is activated. -### `DefaultPemFilesPath` -Default: `''` (empty) +### `DefaultBaseUriImport` +Default: `https://acme-v01.api.letsencrypt.org/` -When using `--store pemfiles` this path is used by default, saving you the effort -from providing it manually. Filling this out makes the `--pemfilespath` parameter -unnecessary in most cases. Renewals created with the default path will automatically -change to any future default value, meaning this is also a good practice for -maintainability. +Default ACMEv1 endpoint to import renewal settings from. -### `CleanupFolders` -Default: `True` +### `CertificateCacheDays` +Default: `1` (empty) -If set to `True`, it will cleanup the folder structure and files it creates -under the site for authorization. +When renewing or re-creating a previously requested certificate that +has the exact same set of domain names, the program will used a cached +version for this many days, to prevent users from running into +[rate limits](https://letsencrypt.org/docs/rate-limits/) while experimenting. +Set this to a high value if you regularly re-request the same certificates, +e.g. for a Continuous Deployment scenario. -### `PrivateKeyExportable` +### `DeleteStaleCacheFiles` Default: `False` -If set to `True`, it will be possible to export the generated certificates from -the certificate store, for example to move them to another server. +Automatically delete files older than 120 days from the `CertificatePath` +folder. Running with default settings, these should only be long-expired +certificates, generated for abandoned renewals. However we do advise caution. ### `Proxy` Default: `[System]` @@ -116,6 +76,16 @@ Default: `''` (empty) Password used to access the proxy server. +## Scheduled task + +### `RenewalDays` +Default: `55` + +The number of days to renew a certificate after. Let's Encrypt certificates are +currently for a max of 90 days so it is advised to not increase the days much. +If you increase the days, please note that you will have less time to fix any +issues if the certificate doesn't renew correctly. + ### `ScheduledTaskStartBoundary` Default: `09:00:00` (9:00 am) @@ -132,29 +102,7 @@ Default: `00:00:00` Configures random time to wait for starting the scheduled task. -### `EncryptConfig` -Default: `True` - -Uses Microsoft Data Protection API to encrypt sensitive parts of -the configuration, e.g. passwords. This may be disabled to share -the configuration across a cluster of machines. - -### `DefaultBaseUri` -Default: `https://acme-v02.api.letsencrypt.org/` - -Default ACMEv2 endpoint to use when none is specified with -the command line. - -### `DefaultBaseUriTest` -Default: `https://acme-staging-v02.api.letsencrypt.org/` - -Default ACMEv2 endpoint to use when none is specified with -the command line and the `--test` switch is activated. - -### `DefaultBaseUriImport` -Default: `https://acme-v01.api.letsencrypt.org/` - -Default ACMEv1 endpoint to import renewal settings from. +## Notifications ### `SmtpServer` Default: `''` (empty) @@ -208,12 +156,60 @@ as opposed to the default behavior that only send failure notifications. Only works if at least `SmtpServer`, `SmtpSenderAddress`and `SmtpReceiverAddress` have been configured. -### `DeleteStaleCacheFiles` +## Security + +### `RSAKeyBits` +Default: `3072` + +The key size to sign the certificate with. Minimum is 1024. + +### `PrivateKeyExportable` Default: `False` -Automatically delete files older than 120 days from the `CertificatePath` -folder. Running with default settings, these should only be long-expired -certificates, generated for abandoned renewals. However we do advise caution. +If set to `True`, it will be possible to export the generated certificates from +the certificate store, for example to move them to another server. + +### `EncryptConfig` +Default: `True` + +Uses Microsoft Data Protection API to encrypt sensitive parts of +the configuration, e.g. passwords. This may be disabled to share +the configuration across a cluster of machines. + +## Disk paths + +### `ClientName` +Default: `win-acme` + +The name of the client, which comes back in the scheduled task and the `ConfigurationPath`. + +### `ConfigurationPath` +Default: `''` (empty) + +Change the location where the program stores its (temporary) files. If not specified +this resolves to `%programdata%\[ClientName]\[BaseUri]` + +### `CertificatePath` +Default: `''` (empty) + +The path where certificates and request files are stored. If not specified or invalid, +this defaults to `(ConfigurationPath)\Certificates`. All directories and subdirectories +in the specified path are created unless they already exist. If you are using a +[[Central SSL Store|Store-Plugins#centralssl]], this can **not** be set to the same path. + +### `LogPath` +Default: `''` (empty) + +The path where log files for the past 31 days are stored. If not +specified or invalid, this defaults to `(ConfigurationPath)\Log`. + +## Validation + +### `CleanupFolders` +Default: `True` + +If set to `True`, it will cleanup the folder structure and files it creates +under the site for authorization. ### `DnsServer` Default: `'8.8.8.8,1.1.1.1,8.8.4.4'` @@ -226,18 +222,38 @@ string `[System]` to have the program query your servers default, but note that this can lead to prevalidation failures when your Active Directory is hosting a private version of the DNS zone for internal use. -### `CertificateCacheDays` -Default: `1` (empty) +## Store -When renewing or re-creating a previously requested certificate that -has the exact same set of domain names, the program will used a cached -version for this many days, to prevent users from running into -[rate limits](https://letsencrypt.org/docs/rate-limits/) while experimenting. -Set this to a high value if you regularly re-request the same certificates, -e.g. for a Continuous Deployment scenario. +### `DefaultCertificateStore` +Default: `''` (empty) -### `LogPath` -Default: `` (empty) +The certificate store to save the certificates in. If left empty, certificates will +be installed either in the `WebHosting` store, or if that is not available, +the `My` store (better known as `Personal`). -The path where log files for the past 31 days are stored. If not -specified or invalid, this defaults to `(ConfigurationPath)\Log`.
\ No newline at end of file +### `DefaultCentralSslStore` +Default: `''` (empty) + +When using `--store centralssl` this path is used by default, saving you the +effort from providing it manually. Filling this out makes the `--centralsslstore` +parameter unnecessary in most cases. Renewals created with the default path will +automatically change to any future default value, meaning this is also a good +practice for maintainability. + +### `DefaultCentralSslPfxPassword` +Default: `''` (empty) + +When using `--store centralssl` this password is used by default for the pfx +files, saving you the effort from providing it manually. Filling this out makes +the `--pfxpassword` parameter unnecessary in most cases. Renewals created with +the default password will automatically change to any future default value, +meaning this is also a good practice for maintainability. + +### `DefaultPemFilesPath` +Default: `''` (empty) + +When using `--store pemfiles` this path is used by default, saving you the effort +from providing it manually. Filling this out makes the `--pemfilespath` parameter +unnecessary in most cases. Renewals created with the default path will automatically +change to any future default value, meaning this is also a good practice for +maintainability.
\ No newline at end of file |