Running the Sniffer¶

This page covers running the sniffer as a standalone sensor that writes NDJSON to local files, rather than to a database. Commands assume the RPM install, where pqc-sniffer is on the PATH and the configuration lives at /etc/pqc-sniffer/config.yaml.

Live Interface Capture¶

Run in the foreground during setup and validation so logs stay visible in the terminal:

sudo pqc-sniffer --config /etc/pqc-sniffer/config.yaml --foreground

For normal operation, run it under systemd instead — see Deployment & Management.

Interactive Configuration¶

The setup wizard can create a configuration interactively:

sudo pqc-sniffer --setup --config /etc/pqc-sniffer/config.yaml

Override Settings from the CLI¶

You can override selected values at runtime without editing the file:

sudo pqc-sniffer \
  --config /etc/pqc-sniffer/config.yaml \
  --foreground \
  --interface eth1 \
  --customer-id customer-12345 \
  --sniffer-id lab-01

Important Runtime Note¶

Warning

Do not use --dry-run if you expect NDJSON files to be written.

--dry-run is useful for parser and flow validation, but it suppresses actual persistence.

Use this:

sudo pqc-sniffer --config /etc/pqc-sniffer/config.yaml --foreground

Not this:

sudo pqc-sniffer --config /etc/pqc-sniffer/config.yaml --foreground --dry-run

Output Path Behavior¶

If offline_output.output_file ends with /, the runtime uses connections.ndjson as the base output name.

Example:

offline_output:
  output_file: "/var/log/pqc-sniffer/"

Base output path:

/var/log/pqc-sniffer/connections.ndjson

When rotation is enabled, the writer uses indexed files derived from that base path:

/var/log/pqc-sniffer/connections.0.ndjson
/var/log/pqc-sniffer/connections.1.ndjson

If rotation is disabled, the base path is used directly. If you provide a full file path, that file path becomes the base path.

Validation Rules That Matter Most¶

offline_output.output_file cannot be empty
offline_output.output_file must be an absolute path
offline_output.output_file cannot contain ..
offline_output.buffer_size_kb must be between 1 and 1024
if rotation is enabled, max_size_mb and max_files must stay within allowed ranges

Recommended Bring-Up Flow¶

Validate the configuration with --validate-config.
Run in the foreground for first use.
Confirm that log output and NDJSON output both look correct.
Only then enable the systemd service for long-running operation.