Configuration reference
CertiStack reads configuration from four places, each with one job:
| Source | What it holds | Example |
|---|---|---|
| A plan (YAML) | What to validate: VMs, probes, the sandbox network, admission limits | my-first-plan.yaml; see the test-plan reference |
| The controller environment | How to connect, and where things live on the controller: PVE and PBS credentials, SSH settings, key paths | an --env-file, or exported variables |
| Command-line flags | A per-invocation override of anything in the environment | --node pve-node-01; see the CLI reference |
| Key files | The report signing key on the controller; the trusted public keys a verifier holds | see Reports and verification |
Credentials never belong in a plan. A plan is retained as signed evidence and
may be shared, and the parser rejects credential keys such as pbs_password.
Precedence
For every setting that can come from more than one place, the first match wins:
- The command-line flag.
- The controller environment: the
--env-fileif you pass one, otherwise the process environment. - The plan, where it has a counterpart (
storage.scratch_dir,storage.overlay_storage,storage.pbs_namespace,compliance.sign_key_path, and the discouragedstorage.pbs_repositoryandstorage.pbs_fingerprint). - The built-in default.
An environment file replaces the process environment
When you pass --env-file, every supported variable is cleared from the
process environment first, and only the file's values are used. A variable
you exported in the shell is discarded for the names in the tables below,
not merged with the file. A file that fails to parse changes nothing.
The environment file
An environment file is a plain KEY=VALUE list that keeps the controller's
secrets out of plans, command lines and shell history. Pass it with
--env-file to run, plan, init or doctor. recover --env-file accepts
only the worker's subset of the variables.
# /secure/certistack/controller.env (mode 0600)
PVE_URL=https://pve-node-01.example.com:8006
PVE_TOKEN_ID=certistack-svc@pve!automation
PVE_TOKEN_SECRET=your-generated-token-secret
PBS_REPOSITORY=certistack-ro@[email protected]:8007:datastore
PBS_PASSWORD=your-pbs-token-secret
CERTISTACK_NODE=pve-node-01
CERTISTACK_SSH_HOST=pve-node-01.example.com
CERTISTACK_SSH_USER=certistack
CERTISTACK_SSH_IDENTITY=/secure/certistack/id_ed25519
CERTISTACK_SSH_KNOWN_HOSTS=/secure/certistack/known_hosts
CERTISTACK_SIGN_KEY=/secure/certistack/controller-signing.ed25519
The rules, all enforced when the file is read:
- The file must be a regular file of at most 256 KiB. On Linux and macOS it
must not be readable by group or other users (use mode
0600or0400); a file with wider permissions is refused. - Blank lines and lines that start with
#are ignored. A#later in a line is part of the value. - Each other line is
NAME=value. A line without=, a duplicate name or a name that is not in the tables below is an error. Arbitrary variables such asPATHare refused. - A value may be wrapped in one pair of matching single or double quotes; the
quotes are removed. Nothing else is interpreted:
$VAR,${VAR},$(command)and backticks stay literal, because the file is never shell-sourced. A value may not contain a newline, carriage return or NUL. - Relative paths in
CERTISTACK_PVE_CA_SOURCE,CERTISTACK_PBS_KEYFILE,CERTISTACK_SSH_IDENTITY,CERTISTACK_SSH_KNOWN_HOSTS,CERTISTACK_OUTPUT_DIRandCERTISTACK_SIGN_KEYare resolved from the file's own directory, so a portable lab directory works from any working directory.
doctor --env-file also accepts the runtime.env the controller wrote for a
worker, which is how you diagnose a blocked run on the node itself.
Variables
Proxmox VE connection
| Variable | Required | Meaning |
|---|---|---|
PVE_URL |
yes | Base URL of the PVE API, for example https://pve-node-01.example.com:8006. It must be HTTPS (plain HTTP is accepted only for a loopback address) and must not carry credentials, a path, a query or a fragment. |
PVE_TOKEN_ID |
yes | The API token ID, user@realm!tokenname. The token needs the privileges in the IaC prerequisites. |
PVE_TOKEN_SECRET |
yes | The token's secret. |
CERTISTACK_PVE_CA_SOURCE |
no | Controller path (absolute, after resolution) to a PEM file of CA certificates to trust in addition to the system roots. Use it when PVE has a private CA. The controller copies it into the run's private worker workspace. |
PVE_TLS_INSECURE |
lab only | 1 or true turns off PVE certificate verification. It is refused unless CERTISTACK_ALLOW_INSECURE_TLS_FOR_LAB is also set, and it must not be used against a production node. |
CERTISTACK_ALLOW_INSECURE_TLS_FOR_LAB |
lab only | 1 or true acknowledges that verification is off in a disposable lab. |
Proxmox Backup Server connection
| Variable | Required | Meaning |
|---|---|---|
PBS_REPOSITORY |
yes | The repository, user@realm!token@host:port:datastore. It can carry a token identity, so keep it in the protected file. The credential must be read-only. |
PBS_PASSWORD |
yes | The PBS password or token secret. |
PBS_FINGERPRINT |
no | The PBS certificate's SHA-256 fingerprint, copied exactly as the PBS dashboard shows it (Dashboard, Show Fingerprint). The PBS client uses it only when the system CA store cannot validate the certificate, for example a self-signed one. |
PBS_NAMESPACE |
no | The PBS namespace to read. It overrides storage.pbs_namespace in the plan and is the default for init --namespace. A VM's source_pbs.namespace must match it. |
CERTISTACK_PBS_KEYFILE |
no | Controller path to the PBS encryption key, needed only for encrypted backups. It must be an absolute path to a regular file (not a symbolic link) of at most 64 KiB, readable by its owner only, and a valid PBS key file. The controller copies it into the worker workspace, which is removed after the run. |
PBS_ENCRYPTION_PASSWORD |
no | The passphrase of that key, when it has one (at least 5 characters). A key that needs a passphrase is refused without it. |
Controller to node (SSH)
| Variable | Required | Default | Meaning |
|---|---|---|---|
CERTISTACK_NODE |
run, plan, init |
The PVE node name that hosts the temporary worker. | |
CERTISTACK_SSH_HOST |
run; selects remote mode for plan and init |
The node's SSH host name or address. | |
CERTISTACK_SSH_USER |
no | certistack |
The SSH account. |
CERTISTACK_SSH_PORT |
no | 22 |
The SSH port, a whole number from 1 to 65535. An invalid value is ignored and the default is used. |
CERTISTACK_SSH_IDENTITY |
no | Absolute path to the SSH private key. | |
CERTISTACK_SSH_KNOWN_HOSTS |
no | ~/.ssh/known_hosts |
Absolute path to a known_hosts file that already holds the node's approved host key. Strict checking is always on. |
CERTISTACK_SSH_SUDO |
no | off | Run the worker through passwordless sudo. On: 1, true, TRUE, yes, YES. Off: 0, false, FALSE, no, NO. Any other value (including True) is ignored and the default is used. |
Paths and defaults
| Variable | Default | Meaning |
|---|---|---|
CERTISTACK_SIGN_KEY |
the plan's compliance.sign_key_path |
Controller path to the Ed25519 private key that signs reports. run and init use it. |
CERTISTACK_OUTPUT_DIR |
/var/lib/certistack/reports |
Controller directory for signed reports. run only. A clean absolute path. |
CERTISTACK_STATE_DIR |
/var/lib/certistack |
Node directory for the recovery journal, worker workspaces and logs. run, plan and init. |
CERTISTACK_SCRATCH_DIR |
the plan's storage.scratch_dir, else /var/lib/certistack/scratch |
Node-local private work directory. run, plan and init. |
CERTISTACK_OVERLAY_STORAGE |
the plan's storage.overlay_storage |
PVE storage ID for the COW overlays. run, plan and init. |
Lab-only and internal
| Variable | Meaning |
|---|---|
CERTISTACK_ALLOW_TEST_MODE |
Only the value 1 counts. It permits the test-only --skip-integrity mode, which skips the full mapped-image integrity scan. A report made that way is labelled test_skip_integrity, cannot serve as production evidence, and is rejected by verify-report unless you pass --allow-test-mode. See lab campaigns. |
CERTISTACK_PROGRESS_EVENTS |
Set by the controller, never by you, in the worker's environment to turn on the worker's progress event stream. |
CERTISTACK_API_TOKEN |
Reserved for the Enterprise Edition daemon. The Community CLI accepts it in an environment file, so one file can serve both, and does not use it. |
Files and directories
On the controller
| Path | Purpose | Notes |
|---|---|---|
/var/lib/certistack/reports/<plan_id>/<report_id>.json |
Signed reports | --output changes the base. Files are mode 0600, and directories CertiStack creates are 0700. CertiStack never deletes or rotates reports; compliance.retention_days is only recorded inside them. |
| Your signing key | The Ed25519 private key | Must be a regular file that group and other users cannot read; a symbolic link is refused. |
| Your keyring or public key | What verify-report trusts |
Not secret. Keep it where an auditor can get it, and apart from the reports. |
controller.env |
The environment file | Mode 0600. |
SSH identity, known_hosts, PVE CA, PBS key |
Connection material | Owner-only. The unprivileged container image runs as UID/GID 65532, so mounted secrets must be owned by that ID. |
| Plans directory | Your plans | Not secret, but they name your VMs. Keep site-specific plans out of public repositories. |
On the PVE node, while an operation runs
| Path | Purpose | Notes |
|---|---|---|
/var/lib/certistack/ (--state-dir) |
State directory | Created by the worker. |
/var/lib/certistack/active.json |
The run journal | Every resource a run creates is recorded here so an interrupted run can be reconciled. A clean run leaves it in the cleaned phase. certistack inspect prints it. |
/var/lib/certistack/workers/<uuid>/ |
The run's private workspace (mode 0700) |
Holds the uploaded certistack-node binary, plan.yaml (without your signing-key path), runtime.env, and the PVE CA and PBS key when you configured them. Removed at the end of a run. Kept only when cleanup could not be verified, so recover has what it needs. |
/var/lib/certistack/logs/<uuid>.log |
The worker supervisor's log | No credentials. Kept after the workspace is gone. |
/var/lib/certistack/scratch/ (--scratch) |
Private scratch space (mode 0700) |
Guest network recovery work and screenshots. Overlays also go here when no overlay_storage is set. It must be a clean absolute path owned by the running user, not a shared directory such as /tmp. |
<overlay storage>/images/<vmid>/certistack-delta-*.qcow2 |
The COW overlays | Removed at teardown. |
/run/certistack.lock |
The node's operation lock | One CertiStack operation at a time per node. |
Nothing else is installed or left on the node. A credentials-bearing workspace that a controller retained for recovery has its credentials removed by the node's next clean run once its controller has been silent for 15 minutes; its logs are kept. See the deployment model.