Skip to main content
Video tutorial · 2:23

Post-distribution validation

Per-target validation endpoints that verify the deployed certificate is actually being served: TLS fingerprint checks with SNI, configurable retries, SSRF protection, and automatic status downgrade to partial on failure.

How it works​

Each distribution target can carry a list of validation endpoints. After the module's Execute finishes with success or partial, the worker runs every endpoint of every resolved target. An endpoint check opens a TLS connection to the configured address and compares the served leaf certificate's SHA-256 fingerprint against the certificate that was just distributed.

  • Validation runs for both success and partial execution results (targets that did succeed still get verified).
  • If any endpoint fails after its retries, the distribution status is downgraded to partial — except in the one case below, where it becomes unverified first.
  • Targets with no endpoints configured pass implicitly — validation is opt-in.
  • Validation endpoints also run after a rollback — they validate against the rolled-back-to version's fingerprint, so a rollback gets the same is-it-actually-served confirmation as a deploy.

Validation methods​

MethodBehavior
tls_fingerprintTCP dial → TLS handshake (certificate chain trust is not checked — the match is by fingerprint) → compare the leaf certificate's SHA-256 fingerprint to the distributed certificate. Optional SNI. The handshake also accepts the TLS 1.2 RSA key-exchange ciphers, so a virtual server limited to them (older NetScaler / F5 SSL profiles) can still be checked.
noneSkip — always succeeds. Useful to park an endpoint without deleting it.

After a restart​

When the deploy restarted or recycled something that serves TLS on a target — an IIS application pool, Exchange's web services (W3SVC/WAS), or an SSH / WinRM post-deploy action — the service usually needs a little while before it answers with the new certificate. For such a target the check:

  • waits until 30 seconds after the restart before its first attempt (measured from the restart itself, so a long target list does not add up the wait), and
  • uses a more patient profile — 6 attempts, 10 seconds apart — for every endpoint field left at its default (retries / retry_delay_ms = 0). A value you set on the endpoint always wins.

Targets whose deploy restarted nothing keep the fast defaults below.

Unverified, and the automatic re-check​

If every target deployed successfully and only the validation failed, the distribution is marked unverified instead of partial: the certificate is on the targets; what could not be confirmed yet is that it is being served. Five minutes later one automatic job (distribution_revalidate) re-runs only the validation of the targets that failed it — nothing is deployed and nothing is restarted again:

  • every re-checked endpoint passes ⇒ the distribution becomes success (and sends what a success sends);
  • any still fails ⇒ it becomes partial, exactly as a failed validation always ended (the job is shown as partial too);
  • the targets it should re-check were deleted meanwhile ⇒ partial (nothing could be confirmed).

If the re-check itself cannot run (a database or lookup failure), it is retried up to three times; after the last attempt the distribution is recorded as partial with the reason. A distribution still unverified an hour later — its re-check was cancelled or lost — is closed as partial by the scheduler (without a notification). Run the distribution again to re-check it.

The run's own distribution_execute job completes without a partial result and no Distribution Failed notification is sent at that point; the re-check sends it (with the number of targets still failing validation) if it ends partial. Scripts that poll the execute job should read the distribution's last_status instead.

While a distribution is unverified nothing else acts on it: no auto-retry, no automatic rollback, and the renewal sweep does not deploy that version again. The re-check does nothing if a newer run or a new certificate version has replaced the one it was checking. Runs where a target itself failed, fan-out batches and rollbacks keep today's partial verdict.

Endpoint fields​

An endpoint addresses the server by hostname and/or IP — at least one is required, and both may be set. When both are given the check dials the ip and uses the hostname as the TLS SNI.

FieldDefaultBoundsNotes
method—tls_fingerprint | none
hostname / ip—at least one required; both allowedrequired for tls_fingerprint
port4430–65535
sni(empty)—ServerName sent in the TLS handshake — required when the server picks the certificate by SNI
timeout_ms50000–120000per-attempt dial + handshake deadline
retries3 (6 after a restart)0–20total attempts
retry_delay_ms2000 (10000 after a restart)0–60000pause between attempts
SNI matters more than you think

An empty sni is not empty on the wire: it falls back to the endpoint's own hostname. The failure mode is the IP-only endpoint — with no hostname there is no SNI, so an SNI-vhosted server (load balancer, CDN) returns its default certificate and the check fails even though the deployment succeeded. Give the endpoint a hostname, or set sni explicitly.

SSRF protection​

Validation dials through the outbound network policy (netpolicy): link-local addresses, cloud metadata endpoints (169.254.169.254 and friends), and DNS-rebinding tricks are blocked. Private/RFC-1918 networks are allowed — validation targets are typically internal.

Configuring endpoints​

  1. Settings → Distribution → Targets → create or edit a target.
  2. Expand Validation Endpoints (optional) → Add Validation Endpoint.
  3. Method defaults to tls_fingerprint; fill hostname and/or IP (both together = dial the IP, hostname becomes the SNI), port, and optional SNI (the SNI field appears only for tls_fingerprint).
  4. Adjust timeout / retries / retry delay if the defaults (5 s / 3 / 2 s) don't fit the platform.

A target can have several endpoints — e.g. one per IP the server answers on. All must pass for the target to count as validated.

Where results appear​

Per-endpoint results (endpoint, method, address, success, duration, and — on failure — up to 20 log lines) are stored on the target's result inside the distribution record and shown on the certificate's Distribution tab: expand a target row to see its validation results. Failure logs are also streamed into the job log.

Slow-propagating platforms (CloudFront and friends)​

Some platforms deploy asynchronously: an AWS ACM re-import propagates to CloudFront over several minutes, a MerlinCDN re-bind propagates across its edge network, and similar delays apply to other CDN/cloud targets. A default 3-attempt / 2-second-delay check will time out long before the new certificate is live.

For such targets widen the window, but stay under the 5-minute ceiling the worker enforces across all of one target's endpoints combined — e.g. retries: 8, retry_delay_ms: 30000, timeout_ms: 10000 (about four minutes). Point the endpoint at the public domain with the correct SNI.

Troubleshooting​

"fingerprint mismatch" but the file on the target is correct​

The server hasn't reloaded, or SNI routed you to a different certificate. Check the reload step of your action set and set sni explicitly.

"TCP dial failed" from the backend only​

The endpoint address must be reachable from the CertAutoPilot worker, not from your workstation. Also note link-local and cloud-metadata addresses are blocked by policy.

"expected fingerprint missing; cannot validate"​

The certificate record has no SHA-256 fingerprint — validation cannot run. This should not happen for certificates issued by CertAutoPilot; re-issue or renew to repopulate it.

See also​

Limits​

  • A target may carry at most 50 validation endpoints.
  • The worker bounds a single target's entire validation phase — every endpoint, every retry — at 5 minutes. A retry policy whose worst case exceeds that is cut short.

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Deploy a Certificate to a Linux Server over SSHYouTube ↗