Skip to content

Architecture ​

Components ​

  1. Collector — listens on UDP and TCP port 514, verifies the sender against the registered device list, parses each vendor format and batches normalized rows into ClickHouse. If ClickHouse is unavailable, batches are spooled to disk and retried.
  2. API — provides JWT authentication, device management, log search and CSV/PDF exports. Searches use ClickHouse, while users, devices and audit records live in SQLite.
  3. Frontend — provides NAT-device management, filtered log search and exports.

The collector and API run together as one Go service. On Linux, the service can bind to port 514 without root through systemd CAP_NET_BIND_SERVICE capability.

Data stores ​

  • ClickHouse: nat.translations stores normalized NAT events, with daily partitions and a 13-month retention period.
  • SQLite: stores users, registered devices and the audit log.

Reliability and security ​

  • Registered-device validation drops traffic from unknown sources and records sightings for operator review.
  • TCP is recommended where available to avoid silent packet loss; the collector also uses a large UDP receive buffer.
  • The disk spool prevents data loss during ClickHouse outages.
  • Searches and exports require authentication and are recorded in the audit log.
  • Keep port 514 restricted to registered device IPs and bind ClickHouse and SQLite locally.

Dream Radius ISP CRM