Skip to main content

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-seal the stored secrets, then retire the old. Zero downtime; old envelopes stay readable until explicitly retired. One small category is not rotated — a secret value carried inside an open approval request — and kek remove tells you if any is still outstanding; it clears when the request is executed, rejected, or expires after 7 days. 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 & CA connectors​

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).

My CA is a commercial reseller with its own API, not ACME. Can CertAutoPilot use it?​

Yes, through a CA connector: add a connection with the vendor's API credential, and CertAutoPilot validates the domain (writing the vendor's DNS validation record into your zone through the zone's DNS credential when it is needed), places the order, polls until the certificate is issued and removes the record. The shipped vendor is GlobalSign Atlas. The contract and the certificate quota stay with the vendor — CertAutoPilot does not track them.

Which Windows Server versions are supported for MSCA?​

Windows Server 2019+. A connection direct to the CA (RPC) needs only the Certification Authority role; a CES/CEP connection also needs the CES and CEP roles. 2022 is what we test against. Earlier versions may work but we do not accommodate WCF quirks older than that (CES/CEP).

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?​

Twenty-one: SSH, Kubernetes, Webhook, Citrix NetScaler, A10 Thunder, Huawei Cloud, F5 BIG-IP, HashiCorp Vault, IIS, Email (SMTP), Windows (WinRM), AWS ACM, Azure Key Vault, Cloudflare, cPanel/WHM, MerlinCDN, Microsoft Exchange, Palo Alto PAN-OS, Fortinet FortiWeb, Fortinet FortiGate, and Elchi. See Distribution overview.

Which modules support rollback?​

All twenty-one support manual rollback. Rollback is one uniform mechanism — re-deploying a previous retained certificate version through the module's normal deploy path — so any module that can deploy can roll back, including the push modules (Webhook re-POSTs the previous version, SMTP re-emails it; they cannot recall the one already sent). Auto-rollback (the auto_rollback_on_failure toggle) is limited to the nineteen stateful modules — the push modules are manual-only, since auto re-sending an old cert on a transient failure would be a surprise. 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 → Sign-in → LDAP. See LDAP / AD. Single sign-on with OIDC, SAML 2.0 and GitHub is set up on the same page — see Sign-in methods.

Does it support 2FA?​

Yes, TOTP. Users set it up from their profile page; the org-wide OTP policy (optional or must) can make it mandatory — with must, every user without 2FA is walked through enrolment at their next login. 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 syslog forwarding of the audit trail. The Helm chart can create a ServiceMonitor and a default PrometheusRule. See Observability.

Where are audit logs?​

Audit Logs in the main navigation. 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 7-day grace period during which the licensed certificate cap stays in effect. After grace the installation falls back to the Free tier's caps of 1 certificate and 1 distribution target: existing certificates keep renewing and existing targets keep receiving them (so your infrastructure doesn't break), but new issuance and new targets are blocked while you are over the caps. No feature is ever switched off. Upload a renewed license to lift the cap again — see License.

See also​