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 or proto 47 or ip6 proto 0 or ip6 proto 43 or ip6 proto 44 or ip6 proto 51 or ip6 proto 60 or ip6 proto 135"
  promiscuous: true

offline_output:
  output_file: "/var/log/pqc-sniffer/"
  append_mode: true
  buffer_size_kb: 512
  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 defaults to offline, and offline is the only supported mode in this release. Connected (PostgreSQL) mode is not available — setting sniffer.mode: connected causes the sniffer to refuse to start. 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 or proto 47 or ip6 proto 0 or ip6 proto 43 or ip6 proto 44 or ip6 proto 51 or ip6 proto 60 or ip6 proto 135"

capture:
  interface: "file:///data/captures/sample.pcapng"
  mode: "local"
  bpf_filter: "tcp or udp or proto 47 or ip6 proto 0 or ip6 proto 43 or ip6 proto 44 or ip6 proto 51 or ip6 proto 60 or ip6 proto 135"

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.