Frequently asked questions

Short answers, with a link to the page that has the detail.

What it does

Does CertiStack change my backups or my production VMs?

No. The PBS snapshot is mapped read-only. The sandbox VM is a new VM whose writes go to a disposable copy-on-write overlay (a UEFI VM's small firmware disks are restored as temporary raw copies). Source VMs and the production network are never touched, every resource the run created is removed, and the signed report records the proof. See the architecture.

Does it install anything on my Proxmox host?

No permanent software. A run uploads a temporary worker to a private directory under /var/lib/certistack/workers/<uuid> on the node and removes it when the run ends. The node must already have the tools the worker calls (qemu-img, proxmox-backup-client, nft and, for Linux network recovery, libguestfs-tools). See the deployment model.

Which Proxmox, PBS and guest versions are supported?

Proxmox VE 9.x with PBS 4.x on amd64, with a Linux amd64 controller: the pair the release evidence covers. Any other pair is unsupported until it has its own evidence, even if the tools install. Linux guests have their network adapted on the disposable overlay; Windows guests keep their own network and are checked with wire or guest-agent probes. The full contract is in release readiness.

Can it validate encrypted backups?

Yes, when you give the controller the PBS encryption key (CERTISTACK_PBS_KEYFILE, plus PBS_ENCRYPTION_PASSWORD if the key has a passphrase). Without it, a run stops before restoring anything and names the missing setting. See the configuration reference.

Can I test an older backup instead of the newest one?

Yes. snapshot: latest resolves the newest backup when the run starts and records the exact snapshot in the report. To replay a historical restore point, pin it in the plan. See snapshot selection.

How long does a run take?

Minutes for a small VM. Before each VM boots, the run reads every byte of its mapped disks to verify them, so disk size dominates, and a cold Windows boot is slow. The report's phase_timings shows where the time went.

Does a pass mean my application works?

It means the probes you wrote passed in an isolated sandbox. A tcp probe proves a listener and an http probe proves a status code; the report records each probe and where it ran. Choose probes for what each VM exists to do, as in the example plans. A pass is evidence of one run, not a compliance certification.

Is there a dashboard or a web UI?

Not in the Community Edition, which is a command-line tool. The dashboard, HTTP API, notifications and HTML or PDF reports belong to the Enterprise Edition.

Reports and evidence

How do I get an HTML or PDF report?

The Community Edition produces and verifies signed JSON only. Rendering it as an HTML binder or a PDF certificate is an Enterprise Edition feature that works from the same JSON. See Reports and verification.

Does verify-report tell me whether the recovery passed?

No. It tells you that the signature is valid and the signer is one you trust. A correctly signed report of a failed recovery verifies too, so read all_passed and all_cleaned. See Verify a report.

Can an auditor verify a report without CertiStack?

Yes. The signature is a standard Ed25519 signature over RFC 8785 canonical JSON. Verify without CertiStack has a complete script.

Where are reports kept, and for how long?

On the controller, under /var/lib/certistack/reports/<plan_id>/ unless you choose another directory. CertiStack never deletes them; retention and backup of the reports and the public keys are yours to manage. See Reports and verification.

Running it

Can I run validations on a schedule?

Yes, with cron, a systemd timer or your CI system. See Automation and scheduling, which includes a tested wrapper script and timer units.

Can two validations run at once?

Not on the same node: each node allows one CertiStack operation at a time, and a second run is refused. Runs on different nodes can overlap if their plans use different sandbox VM IDs, zone_id and vnet_id. See Rules for scheduled runs.

What if a run is interrupted, or the controller crashes?

The node keeps a durable journal of every resource the run created. The next run on that node reconciles it before it changes anything, and certistack recover does the same on demand. Do not delete a retained worker workspace first. See Recover from an interrupted run.

Do I need root?

Not on the controller: it holds plans, credentials, keys and reports as an unprivileged user or container. On the node, the temporary worker runs as root (through a root SSH account or passwordless sudo), so that SSH identity is root-equivalent. Evaluate on a dedicated lab or staging node first. See the deployment model.

Does CertiStack send data anywhere?

No telemetry, no webhooks, no vendor account and no internet connection are required. Its only connections are to the PVE, PBS and SSH endpoints you configure and to the guests in the isolated sandbox. The details are in the security policy.

How do I upgrade or roll back?

Verify the new release, install it beside the old one, repoint the symlink, and run a known-safe plan. Finish or recover every active run first. See Verify, install, upgrade, and roll back a release.

What does CertiStack leave on my node, and how do I remove it?

No service, package, cron job or kernel module is installed on a node. Between runs it holds only the state directory, /var/lib/certistack by default: the run journal, the worker supervisor logs and the scratch directory. Nothing in it is needed once no run is active and the journal is in the cleaned phase (certistack inspect shows it), and only then is it safe to delete. The PVE role, API token and overlay storage you created for CertiStack stay until you remove them. To retire it completely, delete the certistack binary or container image on the controller, revoke the PVE token and PBS credential, and remove the controller's key from the node's authorized_keys. Keep the reports and the public keys for as long as your retention policy requires.

Something failed. Where do I start?

Run the command again with --debug, read the error, and look it up in troubleshooting. For a failed validation, verify the signed report and read its failed probes; for a refused run, certistack doctor on the node shows which prerequisite is missing.

Licensing and support

What license is it under?

The Community Edition is open source under the GNU Affero General Public License v3.0, with no capacity cap and no restriction on commercial use. If the AGPL's network-copyleft condition does not suit you, commercial licenses are available. See editions and the licensing FAQ.

Where do I get help?

Community support is best effort, through GitHub Discussions for questions and issues for reproducible bugs. Report a security vulnerability privately, as the security policy describes, never in a public issue. Before you post, run the failing command with --debug, note the output of certistack version and your Proxmox VE and PBS versions, and remove credentials and anything from a real customer environment.