Skip to main content

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.
  • 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.
noneSkip — 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.

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
retries30–20total attempts
retry_delay_ms20000–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.