certctl/docs/connector-nginx.md

NGINX Connector — Operator Deep-Dive

Per Phase 14 of the deploy-hardening II master bundle. Operator- grade documentation for the NGINX target connector.

Overview

The NGINX connector (internal/connector/target/nginx/) is the canonical implementation of the deploy-hardening I atomic + verify

• rollback contract (Bundle I Phase 4). Every other file-based connector models on this one.

Vendor versions tested

• NGINX 1.25 LTS (current LTS branch)
• NGINX 1.27 stable (current stable branch)

Older versions (1.18 EOL'd 2021, 1.20 EOL'd 2022) are explicitly out of scope per frozen decision 0.1.

Deploy contract

Every cert deploy follows the Bundle I deploy.Apply(ctx, plan) flow:

1. Idempotency check — SHA-256 over cert+chain+key bytes; skip if all match destination.
2. Pre-deploy backup — copy existing files to <path>.certctl-bak.<unix-nanos>.
3. Atomic write — temp-file + chown + atomic rename per destination.
4. PreCommit (validate) — runs nginx -t per the operator's validate_command. Failure aborts; no live cert touched.
5. Atomic rename — temp → final for every File entry.
6. PostCommit (reload) — runs nginx -s reload per the operator's reload_command.
7. Post-deploy TLS verify — dials the configured endpoint; pulls leaf cert SHA-256; compares against deployed bytes. Mismatch triggers automatic rollback.

Per-quirk operator guidance

SSL session cache holds old cert

TestVendorEdge_NGINX_SSLSessionCacheHoldsOldCert_E2E

NGINX's ssl_session_cache (default shared:SSL:10m) keeps TLS session IDs valid for ssl_session_timeout (default 5min). Clients that resume via session ID see the OLD cert until their session expires.

Operator action: this is documented behavior, not a bug. Tune via ssl_session_timeout 5m; (default) or shorter if your cert rotation cadence demands. Post-deploy verify in certctl will return the NEW cert from a fresh handshake (no session resumption); warm clients see the OLD cert until session-cache eviction.

SNI multi-server-name binding

TestVendorEdge_NGINX_SNIMultiServerName_DeployBindsCorrectVhost_E2E

When NGINX has multiple server { server_name a.example b.example; } blocks, the operator deploys with metadata pointing at the specific vhost. Connector binds to that vhost only; other vhosts remain unchanged.

IPv6 dual-stack

TestVendorEdge_NGINX_IPv6DualStackBindsBoth_E2E

NGINX listening on 0.0.0.0:443 + [::]:443 serves the new cert on both stacks after a single deploy.

Operator action: if your post-deploy verify endpoint resolves to IPv6 only on some networks but IPv4 only on others, configure PostDeployVerifyAttempts: 5 to cover both paths.

Reload vs restart

TestVendorEdge_NGINX_ReloadVsRestart_NoConnectionDrop_E2E

nginx -s reload (graceful) preserves in-flight TLS connections via worker handoff. nginx -s stop && nginx drops them.

Operator action: never use restart for cert rotation. The connector's default reload_command: nginx -s reload is correct.

Binary upgrade

TestVendorEdge_NGINX_UpgradeBinaryHotReload_E2E

nginx -s upgrade rolls out a new binary without dropping connections. Not commonly used; documented for ops teams that do rolling NGINX binary upgrades.

Config syntax error → rollback

TestVendorEdge_NGINX_ConfigSyntaxError_RollbackRestoresPreviousCert_E2E

If nginx -t rejects the staged config, the deploy package's PreCommit gate fires before the atomic rename — no live file is touched. The cert directory is exactly as it was.

Missing intermediate

TestVendorEdge_NGINX_MissingIntermediate_DeployedButValidationCatchesAtPostVerify_E2E

If the operator deploys a leaf-only cert (no intermediate), NGINX will start serving it but downstream clients fail chain validation. The connector's post-deploy TLS verify catches this via cert chain walk; rollback fires automatically.

Access log privacy

TestVendorEdge_NGINX_AccessLogPrivacy_NoCertBytesLeakInLogs_E2E

NGINX's default access_log and error_log formats do NOT include SSL key bytes. The connector does not modify NGINX's logging config.

Operator action: if you've customized log_format to include $ssl_* variables, audit the format string for sensitive fields.

Per-version reload-command compat

TestVendorEdge_NGINX_NGINX125_vs_127_ReloadCommandCompatible_E2E

nginx -s reload semantics are identical between 1.25 LTS and 1.27 stable. No per-version branch needed in operator config.

High-concurrency deploy under load

TestVendorEdge_NGINX_HighConcurrencyDeployUnderLoad_E2E

NGINX's worker handoff during reload is graceful; concurrent TLS handshakes during a deploy succeed without 5xx errors.

Troubleshooting matrix

Symptom	Test name	Root cause	Operator action
Old cert returned 5min after deploy	SSLSessionCacheHoldsOldCert_E2E	session cache TTL	tune ssl_session_timeout
Wrong vhost serves new cert	SNIMultiServerName_E2E	misconfigured server_name selector	verify vhost metadata
Post-verify fails on IPv6	IPv6DualStackBindsBoth_E2E	flaky DNS resolution	PostDeployVerifyAttempts: 5
Connection drops on cert change	n/a	using restart instead of reload	use nginx -s reload
Deploy aborts with nginx -t error	ConfigSyntaxError_RollbackRestoresPreviousCert_E2E	bad config (not deploy's fault)	fix config; redeploy
Chain-validation failure post-deploy	MissingIntermediate_E2E	leaf-only cert	include full chain in deploy

V3-Pro deferrals

• Pin NGINX ssl_session_ticket_key rotation interaction with cert rotation (rare; documented but not tested).
• NGINX Plus dyn_pem API integration (commercial; not V2 scope).

Related docs

• Atomic deploy + post-verify + rollback — the Bundle I primitive every connector consumes.
• Vendor compatibility matrix
• Connectors reference