Quick Start¶

The fastest path from a fresh install to live NDJSON output. This assumes the sniffer is already installed — if not, follow Installation first (about five minutes with the RPM).

1. Set Your Identity and Interface¶

The install writes a starter configuration to /etc/pqc-sniffer/config.yaml. For file-based (offline) output, replace its contents with the minimal configuration below, then set your identity and capture interface:

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

sniffer:
  customer_id: "your-customer-id"
  sniffer_id: "sniffer-01"
  mode: "offline"            # write NDJSON to file (not to a database)

capture:
  interface: "eth0"          # run `ip link` to list interfaces
  mode: "local"
  bpf_filter: "tcp or udp"
  promiscuous: true

offline_output:
  output_file: "/var/log/pqc-sniffer/"
  append_mode: true
  buffer_size_kb: 64
  rotation_enabled: true
  max_size_mb: 100
  max_files: 10

logging:
  level: "info"
  file:
    path: "/var/log/pqc-sniffer/pqc-sniffer.log"
    rotation_enabled: true
    max_size_mb: 100
    max_files: 10
  database:
    enabled: false           # required for file-only output

monitoring:
  heartbeat_interval_seconds: 60
  metrics:
    enabled: false

Important

sniffer.mode must be offline for file output. If it is left unset, the sniffer defaults to connected mode and expects a PostgreSQL database instead of writing connections.ndjson. See the YAML Reference for every setting.

2. Validate the Configuration¶

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

Fix any reported errors before continuing.

3. See It Work (Foreground)¶

Run in the foreground for a quick look at live capture. This runs until you press Ctrl+C:

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

4. Confirm Output¶

In another terminal, watch records land:

With rotation_enabled: true, the sniffer writes indexed files such as connections.0.ndjson, connections.1.ndjson, and so on. With rotation_enabled: false, it writes the base file connections.ndjson.

latest_output=$(ls -t /var/log/pqc-sniffer/connections*.ndjson | head -n 1)
tail -5 "$latest_output"

Each line is one self-contained NDJSON record. If the file is empty, see Troubleshooting.

5. Run It as a Service¶

Once you are happy with the output, run it under systemd so it starts on boot and restarts on failure:

sudo systemctl enable --now pqc-sniffer
systemctl status pqc-sniffer

First-Run Notes¶

Tip

capture.interface must match a real interface (ip link), the output path must be absolute, and live capture requires elevated privileges. The RPM already grants the binary packet-capture capability, so the systemd service does not run unconfined.

Warning

Do not use --dry-run when you expect output files — it suppresses NDJSON writes.

Process a PCAP Instead¶

To analyze a capture file instead of a live interface, point capture.interface at the file:

Path Inputfile:// Input

capture:
  interface: "/data/captures/sample.pcap"
  mode: "local"
  bpf_filter: "tcp or udp"

capture:
  interface: "file:///data/captures/sample.pcapng"
  mode: "local"
  bpf_filter: "tcp or udp"

Then run it in the foreground as in step 3. See PCAP Processing for details.

Checklist¶

Install the sniffer.
Set identity and interface in /etc/pqc-sniffer/config.yaml.
Validate with --validate-config.
Run in the foreground and confirm a connections*.ndjson file is written.
Enable the service with systemctl enable --now pqc-sniffer.