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. 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?
No. DNS-01 only. HTTP-01 requires port 80 reachability to every host on the order, which doesn't fit a distribution-oriented platform. See DNS providers.
My DNS provider isn't in the list. What are my options?
Use manual DNS — CertAutoPilot emits the TXT record you need, you publish it on any system, the backend validates. Slower but works with any provider.
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?
Eight: SSH, Kubernetes, IIS (via WinRM), F5 BIG-IP, Citrix NetScaler, HashiCorp Vault, Webhook, Huawei Cloud. See Distribution overview.
Which modules support rollback?
SSH (full), Kubernetes (opt-in), Vault (KV v2 version restore). Webhook, NetScaler, F5, IIS, Huawei Cloud are non-reversible — they leave the old cert alone and point bindings at the new one.
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 with exponential backoff (1m → 5m → 15m → 1h → 4h → 12h, up to 7 days). Every attempt writes a cert.renewal_failed event so notification rules alert you. After all retries are exhausted the cert enters a terminal renewal_failed state — fix the root cause and click Renew manually to reset.
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.