HTTP validation

HTTP validation works as follows:

  • 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 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.
  • The ACME server does follow 301/302 redirects.
  • There may be more than one validation request for the same token, e.g. from different geographic locations or different protocols (IPv4/IPv6).
  • Let’s Encrypt does not disclose the source locations of these requests, which effectively means that the domain has to be accessible for the public, at least for the duration of the validation. IF you need to temporarly open a firewall for this purpose, check out the settings below.
Filesystem Save verification files on (network) path
FTP(S) Upload verification files via FTP(S)
REST request Send verification files to the server by issuing an http(s) request
Self-hosting Let simple-acme answer HTTP validation request
SFTP Upload verification files via SSH-FTP
WebDav Upload verification files via WebDav

Warmup

Before allowing the ACME server to validate, the program will attempt to request the validation file itself and note the result of that request in the log. A side effect of this is that it forces the application to start in case it’s application pool or equivalent went to sleep, warming up the caches etc. This reduces the chance of time-outs during validation.

Settings

Execution.DefaultPreExecutionScript Path to a script that is executed before renewing a certificate.

This may be useful to temporarely relax security measures, e.g. opening port 80 on the firewall.

Paths should be JSON-encoded, e.g. "C:\\" (note the double backslash).

Type: string
Default: undefined
Execution.DefaultPostExecutionScript Path to a script that is called after renewing a certificate, this may be useful to undo any actions taken by the script configured as the DefaultPreExecutionScript. Not to be confused with the script installation plugin. The difference is that the installation plugin can be configured separately for each renewal and has access to a lot more context about the new and previous certificates. Also when the installation script fails, the renewal will be retried later. That is not the case for the pre/post execution scripts. Any errors there are logged but otherwise ignored.

Paths should be JSON-encoded, e.g. "C:\\" (note the double backslash).

Type: string
Default: undefined

Looking for win-acme?

simple-acme is a backwards compatible, drop-in replacement built by the same person. Project history.