Skip to content

Deployment & Management

For anything beyond a quick foreground test, run the sniffer as a managed systemd service. The RPM installs the service unit for you; this page covers starting, enabling, monitoring, and upgrading it.

Bring-Up Pattern

Bring a new sensor up in this order — it makes the first failure easy to spot:

  1. Install the sniffer (see Installation).
  2. Set identity, interface, and offline output in /etc/pqc-sniffer/config.yaml.
  3. Validate the configuration with --validate-config.
  4. Run once in the foreground and confirm NDJSON output.
  5. Enable the systemd service for long-running operation.

Managing the Service

The RPM installs and registers pqc-sniffer.service.

# Start now, and start automatically on boot
sudo systemctl enable --now pqc-sniffer

# Status and health
systemctl status pqc-sniffer

# Follow logs
sudo journalctl -u pqc-sniffer -f

# Apply a configuration change
sudo systemctl restart pqc-sniffer

# Stop, and stop starting on boot
sudo systemctl disable --now pqc-sniffer

The service is configured to restart automatically on failure.

It also reports its own liveness. The sniffer tells systemd it is still working once every 30 seconds, and if the main loop stops making progress for a full minute the sniffer stops reporting and systemd restarts it. A hang that would previously have left the unit sitting at active (running) while capturing nothing is now recovered without anyone having to notice it.

Worst case, a wedged sniffer is restarted about two minutes after it stops working. A slow or unreachable database does not cause this — see Service Restarted by the Watchdog for what it looks like in the journal.

Applying Configuration Changes

  1. Edit /etc/pqc-sniffer/config.yaml.
  2. Validate before restarting: 
    sudo pqc-sniffer --config /etc/pqc-sniffer/config.yaml --validate-config
  3. Restart to apply: 
    sudo systemctl restart pqc-sniffer

What the Service Runs As

The packaged unit runs the sniffer under a dedicated, unprivileged pqc-sniffer service account — not root. Packet capture works because the unit grants the single capability it needs (CAP_NET_RAW) as an ambient capability, on top of a hardened systemd profile (PrivateTmp, ProtectSystem=strict, NoNewPrivileges, and restricted address families).

The RPM creates the pqc-sniffer user/group on install. The service:

  • reads /etc/pqc-sniffer/config.yaml (mode 0600, owner pqc-sniffer:pqc-sniffer, so only the service account can read it; root can still edit it),
  • writes NDJSON output and logs under /var/log/pqc-sniffer/, and
  • uses /var/lib/pqc-sniffer/ for service state.

Both directories are owned by the pqc-sniffer account (mode 0750). If you run the binary manually instead of via systemd, use sudo. The RPM deliberately applies no file capability to the binary — CAP_NET_RAW is granted ambiently by the unit, so it reaches the service and nothing else. Applying setcap yourself would give packet capture to every local account able to execute the file, so avoid it on any host running the service.

Upgrading

Install the newer RPM; dnf upgrades in place and preserves your configuration:

sudo dnf install ./pqc-sniffer-<new-version>.x86_64.rpm
sudo systemctl restart pqc-sniffer

Your /etc/pqc-sniffer/config.yaml is kept across upgrades; the latest reference defaults are written to config.yaml.example for comparison.

Manual Installs

If you installed without the RPM, install the systemd unit yourself:

sudo cp pqc-sniffer.service /usr/lib/systemd/system/pqc-sniffer.service
sudo systemctl daemon-reload
sudo systemctl enable --now pqc-sniffer

Operational Checklist

  • Keep logging.database.enabled: false for file-only (offline) deployments.
  • Confirm the output and log paths under /var/log/pqc-sniffer/ are writable.
  • Set rotation (max_size_mb, max_files) so retention matches your disk budget — see Rotation and Retention.
  • Validate the configuration after every change, before restarting the service.