Frequently asked questions
The questions we answer most often. If yours is not here, check the relevant topic page or see Troubleshooting.
Deployment
Which operating systems are supported?
64-bit Linux: RHEL / Oracle / Rocky / AlmaLinux 9+, Debian 12+, Ubuntu 22.04+. The binary is statically linked (CGO enabled for PKCS#11 builds, see below). Kubernetes deployments work on any CNCF-conformant distribution.
Why is CGO required for PKCS#11?
The crypto11 library dlopens the vendor's libpkcs11.so at runtime, which needs libdl. Builds with PKCS#11 support are based on Debian bookworm; the pure env provider still ships a musl-linked static binary. Operators needing a pure-static build without HSM support should contact support — the released tarball ships both flavours side by side.
What MongoDB version do I need?
MongoDB 6.0 or newer. CertAutoPilot uses $expr/$switch inside update pipelines for atomic state transitions; these require 6.0+. 7.0 is our recommended version for standalone installs.
Can I run everything on one host?
Yes. Standalone installs run --mode=all out of the box (API + worker + scheduler in one process). For high-availability, split each mode across separate pods/hosts with MongoDB replica sets. See Three runtime modes.
Can it run air-gapped?
Yes. For certificate issuance use Microsoft AD CS (MSCA) instead of public ACME. Pull container images / tarballs once and push to your internal registry; the standalone installer supports pinned-tarball mode with no outbound network.
Security & encryption
How are private keys stored?
Envelope encryption. Each private key is sealed with a random AES-256-GCM DEK; the DEK is wrapped by the active KEK. The envelope carries a kek_version and a provider tag so rotation and HSM migration are safe. See Envelope encryption.
Does CertAutoPilot support HSMs?
Yes, via PKCS#11. Tested backends: SoftHSM2 (dev/CI), AWS CloudHSM, Thales Luna Network HSM; Fortanix DSM is community-validated. The KEK never leaves the HSM — only wrap/unwrap operations cross the boundary. YubiHSM 2 is not supported (it lacks CKM_AES_GCM).
What is KEK rotation and why should I care?
Rotating the Key Encryption Key periodically is a SOC 2 / ISO 27001 expectation. CertAutoPilot supports multi-version KEKs: you load the new one alongside the old, verify the fleet, re-wrap every envelope, then retire the old. Zero downtime; old envelopes stay readable until explicitly retired. See the full runbook.
What do I do if the KEK is compromised?
Rotate it — follow the runbook with a sense of urgency. Once the new KEK is active and all envelopes are re-wrapped, retire the compromised version immediately (you do not need to wait the normal 7-30 day window). Rotate dependent secrets (JWT) too, and revoke any certificates whose private keys were potentially exposed.
Can I switch from env to pkcs11 after install?
Not directly. The provider choice is install-locked in MongoDB. The supported path is a fresh install with the new provider and a scripted re-import of your data. See Provider migration.
ACME & MSCA
Which CA should I start with?
Start with Let's Encrypt Staging to prove the flow without spending your production rate-limit budget. Once issuance + distribution works end-to-end, switch to Let's Encrypt Production (or whichever CA you are paying for) by creating a new ACME account and repointing the cert.
Do you support HTTP-01?
Yes. Route the ACME challenge path (/.well-known/acme-challenge/*) on each domain to CertAutoPilot at your edge (gateway / ingress / reverse proxy — CertAutoPilot can stay internal) and the CA validates over port 80, with no DNS provider access and no propagation wait. Wildcards still require DNS-01. See HTTP validation.
My DNS provider isn't in the list. What are my options?
Two options: HTTP validation — usually the better choice: route the ACME challenge path to CertAutoPilot at your edge, fully automatic issuance and renewal, no DNS access needed (not for wildcards); or manual DNS — CertAutoPilot emits the TXT record, you publish it anywhere, the backend validates (works for wildcards, but no auto-renew).
Which Windows Server versions are supported for MSCA?
Windows Server 2019+ with CES and CEP roles installed. 2022 is what we test against. Earlier versions may work but we do not accommodate WCF quirks older than that.
Distribution
Do I need an agent on the target?
No. CertAutoPilot is agentless. The backend pushes via SSH, vendor REST APIs, or WinRM.
Which distribution modules are built in?
Fourteen: SSH, Kubernetes, Webhook, Citrix NetScaler, Huawei Cloud, F5 BIG-IP, HashiCorp Vault, IIS, Email (SMTP), Windows (WinRM), AWS ACM, Cloudflare, MerlinCDN, and Microsoft Exchange. See Distribution overview.
Which modules support rollback?
SSH (full), Kubernetes (opt-in via store_content), Vault (KV v2 version restore), MerlinCDN and Exchange (conditional — only when delete_old_cert is off). Webhook, NetScaler, F5, IIS, SMTP, WinRM, AWS ACM, Cloudflare, Huawei Cloud are non-reversible — they leave the old cert alone and point bindings at the new one. See the rollback matrix.
Can I write a custom distribution module?
Yes, in Go by implementing the Module interface in pkg/modules/module.go. Registration is via the module registry. A plugin architecture with externally-loaded modules is on the roadmap; for now a custom module requires a rebuild.
Renewal & scheduler
When does CertAutoPilot renew a cert?
30 days before expiry by default, earlier if an ACME Renewal Info (ARI) hint suggests so. See Renewal.
What happens if renewal fails?
Retries on an escalating backoff ladder (15m → 1h → 6h → 12h → 24h, 5 attempts by default). Failure notifications are de-duplicated to one per certificate per day. After the ladder is exhausted the cert enters renewal_failed — but that is no longer a dead end: a scheduler safety net picks it back up roughly every 2 days and re-runs the ladder until the certificate renews or actually expires. You can still intervene immediately with Renew, or stop the retries by disabling auto-renew. See Renewal failure.
Can I renew many certs at once?
Yes. Select rows in the certificate list → Bulk renew. Job-based fan-out with SHA-256 idempotency (the same set can't be double-started). See Bulk renew.
Access & RBAC
What roles exist?
Owner > Admin > Operator > Viewer, at both the organization and the project level. See RBAC.
Does it support LDAP / AD?
Yes, for user authentication. Configure in Settings → LDAP. See LDAP / AD.
Does it support 2FA?
Yes, TOTP. Users set it up from their profile page; org policy can require it for admin-tier roles. See 2FA.
How does CI/automation authenticate?
As a regular user over JWT — there is no separate API-key credential. Create a dedicated service-account user with a minimal role, log it in via POST /api/v1/auth/login, then send the returned access_token as Authorization: Bearer (it bypasses CSRF). See Programmatic access.
Operations
What do I need to back up?
Two things, always together: MongoDB and the secret store (/etc/certautopilot/secrets.env on standalone, or the Kubernetes Secret). Losing either one makes encrypted data unrecoverable. See Backup & restore.
How do I monitor it?
Prometheus on /metrics plus OpenTelemetry tracing. The Helm chart can create a ServiceMonitor and a default PrometheusRule. See Observability.
Where are audit logs?
Settings → Audit logs. HMAC-chained for tamper evidence; exportable to CSV or forwarded to your SIEM via syslog forwarding.
What happens when the license expires?
The backend enters a read-only grace mode: existing certs keep renewing (so your infrastructure doesn't break) but no new issuances are accepted. Contact your license issuer before the expiry date.