Proxy¶

The ByteFreezer Proxy is a lightweight data collection agent that receives data from various sources (syslog, sFlow, IPFIX, eBPF, HTTP webhooks) and forwards it to the ByteFreezer Receiver.

Key Features¶

• Multi-protocol support: UDP, TCP, HTTP, message queues
• Dynamic configuration: Polls Control for dataset configurations
• Automatic plugin management: Starts/stops listeners based on assigned datasets
• Local spooling: Buffers data during network outages
• Compression: Batches and compresses data before forwarding

Deployment Options¶

Configuration Modes¶

Control-Only Mode (Recommended)¶

Proxy polls Control for configuration. Datasets assigned to the proxy automatically create listeners.

config_mode: "control-only"
account_id: "your-account-id"
bearer_token: "your-api-key"
control_url: "https://api.bytefreezer.com"

Local-Only Mode¶

Configuration defined in local YAML file. No Control connectivity required.

config_mode: "local-only"
inputs:
  - type: syslog
    name: local-syslog
    config:
      port: 514
      host: "0.0.0.0"

Hybrid Mode¶

Local inputs merged with Control configuration. Local takes precedence on port conflicts.

config_mode: "hybrid"
account_id: "your-account-id"
bearer_token: "your-api-key"
control_url: "https://api.bytefreezer.com"
inputs:
  - type: syslog
    name: local-override
    config:
      port: 514

Dataset Assignment¶

Each dataset can be assigned to a specific proxy. When the proxy polls for configuration, it only receives datasets assigned to it.

1. Create dataset in UI with source type and port
2. Assign dataset to proxy via UI or API
3. Proxy automatically starts listener on configured port

This allows multiple proxies to handle different data types without port conflicts.

Spooling & Dead Letter Queue¶

The proxy spools data locally when the receiver is unreachable, then retries delivery automatically.

Data Flow¶

Incoming Data → Queue → Upload to Receiver
                          ├─ Success → file removed
                          ├─ Transient error (5xx, 429) → Retry (up to retry_attempts)
                          └─ Permanent error (4xx) or retries exhausted → DLQ

DLQ Hard Limit¶

The Dead Letter Queue (DLQ) preserves batches that could not be delivered. To prevent unbounded disk growth, a configurable hard limit enforces FIFO eviction — when total DLQ size exceeds the limit, the oldest files are removed first.

DLQ API¶