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
successandpartialexecution results (targets that did succeed still get verified). - If any endpoint fails after its retries, the distribution status is downgraded to
partial. - Targets with no endpoints configured pass implicitly — validation is opt-in.
- Rollback runs intentionally skip validation (targets then hold the previous certificate, so a fingerprint check against the new one would always fail).
Validation methods
| Method | Behavior |
|---|---|
tls_fingerprint | TCP 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. |
none | Skip — always succeeds. Useful to park an endpoint without deleting it. |
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.
| Field | Default | Bounds | Notes |
|---|---|---|---|
method | — | tls_fingerprint | none | |
hostname / ip | — | at least one required; both allowed | required for tls_fingerprint |
port | 443 | 0–65535 | |
sni | (empty) | — | ServerName sent in the TLS handshake — required when the server picks the certificate by SNI |
timeout_ms | 5000 | 0–120000 | per-attempt dial + handshake deadline |
retries | 3 | 0–20 | total attempts |
retry_delay_ms | 2000 | 0–60000 | pause between attempts |
If the target serves multiple certificates on one IP (SNI vhosting, load balancer, CDN), an empty SNI usually returns the default certificate — and the check fails even though the deployment succeeded. Set sni to the domain the certificate covers.
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
- Settings → Distribution → Targets → create or edit a target.
- Expand Validation Endpoints (optional) → Add Validation Endpoint.
- 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 fortls_fingerprint). - 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 give validation a generous window, e.g. retries: 20, retry_delay_ms: 30000, timeout_ms: 10000 — up to 10 minutes of patience — and 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.