English · 한국어

Environment variable reference¶

Every environment variable that pqcota's programs read, in one place. Names, accepted values and defaults come from the code. How to use each command is in the command reference of its stage; this page links there instead of repeating it. For the overview of the documents, see the developer documentation.

Read when the program starts. Changing a variable does not affect a program that is already running.
Keep the database and the organization the same for the commands that share a store. pqcota-ingest, pqcota-cbom-ingest, pqcota-inventory, pqcota-prune, pqcota-provision, pqcota-records, pqcota-hosts and pqcota-profile read PQCOTA_ORG, so set it the same way for all of them. pqcota-hosts and pqcota-profile take the database from --dsn, not from PQCOTA_DSN, so point the flag at the same database yourself.
Earlier releases ignored the organization in two commands. In v0.10.0 and earlier, pqcota-hosts and pqcota-profile wrote endpoints and profiles to the default organization whatever PQCOTA_ORG said, and PQCOTA_REQUIRE_ORG=1 made them fail even when an organization was named. Rows they wrote that way stay in the default organization: pqcota cannot tell which organization they belonged to, so it does not move them. To have them under an organization, decide that yourself and run the command again with PQCOTA_ORG set; that writes new rows under the organization and leaves the old ones where they are.
Private keys are secrets. PQCOTA_SIGN_KEY and PQCOTA_APPROVAL_KEY hold private keys. Treat the environment they are set in accordingly; the public keys (PQCOTA_VERIFY_KEY, PQCOTA_APPROVAL_KEYS) are not secret.

Store and organization¶

Variable	Read by	Value	When unset
`PQCOTA_DSN`	`pqcota-ingest`, `pqcota-cbom-ingest` (optional); `pqcota-inventory`, `pqcota-prune`, `pqcota-records` (required)	A Postgres connection string, as a URL (`postgres://user:password@host:5432/db`) or as `key=value` pairs. See the format in the discovery command reference (`pqcota-hosts`)	The two ingest commands use an in-memory store, which prints a summary and keeps nothing after the process ends. The other three exit with an error (status 2), because their view needs a store that another process wrote
`PQCOTA_ORG`	The eight commands listed above	An organization name: 2 to 64 characters of lowercase letters, digits and hyphens, not starting with a hyphen. A value that does not fit is always an error and is never replaced by the default	Records belong to the organization `default`
`PQCOTA_REQUIRE_ORG`	Every command that opens the store	`1`	With `1`, opening the store without an organization is an error, and so is naming `default` explicitly (it is the name for records written with no organization), so nothing is written to `default` by mistake. Any other value, or unset, allows both
`PQCOTA_AUTO_DDL`	The inventory history store only	`0`	Unless it is exactly `0`, the history schema is created when that store is opened. With `0` it is not created, and opening fails if the schema is missing. It does not cover the other tables: the machine metadata store (`pqcota-hosts`, `pqcota-profile`) and the provisioning record store (`pqcota-provision`) create their tables whatever this variable says

Why these exist: when several organizations share one database, records that were written under the wrong organization cannot be separated afterwards, and an automatic CREATE TABLE against a wrong connection string quietly creates and writes to an empty table. PQCOTA_REQUIRE_ORG=1 turns the first into an error where it applies, and PQCOTA_AUTO_DDL=0 does the same for the history schema only. Details are in the inventory command reference.

pqcota-hosts, pqcota-profile and pqcota-provision take the database as a --dsn flag, not from PQCOTA_DSN.

Signing and verifying observations¶

Variable	Read by	Value	When unset
`PQCOTA_SIGN_KEY`	`pqcota-nodescan`, `pqcota-cngscan`	A base64 ed25519 private key, made by `pqcota-keygen`	The result is not signed. If signing fails, the program prints a warning and still emits the result, unsigned
`PQCOTA_VERIFY_KEY`	`pqcota-ingest`	One or more base64 public keys, separated by commas	Signatures are not verified, and the load summary counts those results as unchecked. A mismatch with the keys given is refused
`PQCOTA_REQUIRE_SIGNATURE`	`pqcota-ingest`	`1`	With `1`, loading does not start when there is no key to verify with. Any other value, or unset, lets it proceed unverified

PQCOTA_VERIFY_KEY is a list of keys. It shows that someone holding one of them signed the result, not which collector did; binding a key to a collector is not wired yet. The key pair is generated by pqcota-keygen, which lives in pqcota-common because plan approval uses the same kind of key.

Plan approval¶

Variable	Read by	Value	When unset
`PQCOTA_APPROVAL_KEY`	`pqcota-approve`	A base64 ed25519 private key	The command exits with an error (status 2): there is no key to approve with
`PQCOTA_APPROVAL_KEYS`	`pqcota-provision`	Comma-separated `<approver>=<base64 public key>` pairs. A pair that is not in that form is an error	By default the generator refuses to run, because an approval it cannot check shows nothing about who took responsibility. The `--allow-unverified-approvals` flag continues without checking, with a warning

PQCOTA_REQUIRE_APPROVAL=1 is an older name that the code no longer reads. Refusing an unverifiable approval is now the default, so setting it has no effect.

How approval works and what the exit codes mean: the provisioning command reference and the reporting guide.

Observation programs¶

Variable	Read by	Value	Default and notes
`NETCAP_IFACE`	`pqcota-netcap`	A network interface name	`eth0`. The interface argument on the command line overrides it
`NETCAP_WINDOW_SEC`	`pqcota-netcap`	Observation window in whole seconds, greater than zero	`8`. The window argument on the command line overrides it. A value that is not a whole number is ignored without a message and the default is used. Zero or a negative number is accepted, but the capture then runs for 3 seconds, while the start-up message prints the value you gave
`PQCOTA_JVM_AGENT`	`pqcota-jvmscan`	Path to `collector.jar`	Unset: no attach. With it, and at least one JVM found, each is attached. Without it, see the note below
`JAVA_BIN`	`pqcota-jvmscan`	Path to a Java launcher	Used by the probe path only. If unset: the launcher of a JVM that was found, otherwise `java` on the `PATH`
`JVMSCAN_CP`	`pqcota-jvmscan`	A class path	Passed to the probe path's Java launcher as `--class-path`. Unset: none
`PQCOTA_CLOUD_INSTANCE_ID`	`pqcota-nodescan`, `pqcota-cngscan` (through the machine identity fingerprint)	A cloud instance identifier, supplied by the operator	Unset: no cloud instance identifier is part of the fingerprint. Surrounding whitespace is trimmed. When set, it is the first input used to derive a node's self-assigned identifier, ahead of the machine id, the hardware UUID and the host name

The probe path. Without PQCOTA_JVM_AGENT and without --pid, pqcota-jvmscan starts a Java launcher of its own to read the default provider chain and marks the result degraded, even if JVMs are running. With --pid and no agent it reads that JVM's static configuration. See the FAQ and the discovery command reference for privileges and the other collectors.

Tests and the demo¶

These are not for production use.

Variable	Where	Meaning
`PQCOTA_TEST_DSN`	The Postgres test cases	A connection string for a disposable database. Without it those cases are skipped. See Check your work
`DEMO_REAL_PROVIDER`	`demo/scripts/demo.sh`	`1` enables the optional stage that builds and applies a real post-quantum provider. See the demo
`PQCOTA_PROVIDERS`, `PQC_SERVER`	The demo's workload containers	Set by the demo's topology generator to give each container its providers. Do not set them yourself

Not environment variables¶

These look similar and are not read from the environment.

Command-line flags, such as --dsn, --level, --allow-unverified-approvals, --allow-incomplete, --strict and --pid. They are in the command references.
Ansible variables in the generated playbooks, such as pqcota_module_sha256 and pqcota_module_sha256_<provider>. They are passed when you run the playbook; see the provisioning command reference.

Keeping this page right¶

The authority is the code, but one search does not give a complete list. When you add or change a variable, check each place a variable can come from: the non-test Go code of the five repositories (names read with os.Getenv, or held in constants such as org.Env), the demo shell scripts, the test code, and the comments, which may still mention a name that no code reads, as PQCOTA_REQUIRE_APPROVAL is. Then follow the call path to see which commands reach it, as the exceptions under "Store and organization" show. Update this page in the same change.