Configuration

JSON configurations reject unknown fields. Paths resolve relative to the configuration file. Main configuration, endpoint configuration, and plugin manifests are different formats.

Generate a starting point

For first installation, run sudo netflowscout init --lang en; see the installation wizard. Use configure below for scripted or reference generation.

netflowscout configure --mode endpoint --service billing \
  --executable /opt/billing/server --verification \
  --out ./netflowscout.json --endpoint-out ./billing.json
netflowscout check --config ./netflowscout.json

Generation refuses to overwrite files and defaults to installed paths. Source development can use --plugins /absolute/path/build/plugins. For existing installations, the TUI Config page validates, previews diffs, and coordinates activation.

Common main fields

This table distinguishes loader defaults from settings that require local values. Packaged and generated deployment configurations explicitly use absolute paths.

Field	Default / behavior
sensor_id / service	local / unknown; set stable meaningful names
capture.application_source	Loader: network; packaged/endpoint-generated configuration: endpoint
capture.interface / filter	Actual interface and supported userspace expression
socket / stream_socket	Rule input / plaintext Unix sockets; process wiring must agree
metrics	127.0.0.1:9710; keep loopback
rules / plugins	Rule files / plugin packages or parent directories; validate the complete set
queue.path / max_bytes	var/events.wal / 256 MiB logical event capacity
file.enabled/path/max_bytes/keep	true / var/events.ndjson / 16 MiB / 8 including current
dataway.enabled/url/token_env	Disabled; base URL; credential environment variable name
recording.enabled/directory/protocols	Disabled; dedicated local folder; explicit protocols; see Raw data recording
recording.retention_hours/event_retention_hours	Loader defaults: 0 / 0; age expiry / event protection, 0..8760 hours. Generator recording defaults: 24 / 168
privacy.raw_fields	Empty; service-specific input field allowlists
verification.enabled	false; enabling requires main/analyzer restarts
business.enabled/max_series/window_seconds	true / 256 / 300; bounded cardinality and recent Top N
grpc.descriptors	At most eight FileDescriptorSets, 1 MiB each

HTTP and business settings

{
  "http": {"request_events":true,"query_keys":["action"],"headers":["x-request-id","x-business-action"]},
  "business": {"enabled":true,"max_series":256,"window_seconds":300,
    "routes":[{"pattern":"^/orders/[0-9]+$","name":"/orders/{id}"}]}
}

Merge this fragment into the full configuration. Query/header selection still filters credentials; raw output still needs privacy authorization. Business route names are public administrator-defined templates and must not contain sensitive values. Untemplated paths and SQL use bounded normalization and hashes.

Resource limits

limits field	Default
groups_per_rule	10000
distinct_per_aggregate	4096
input_buffer	2048 records
input_bytes	32 MiB
max_connections	16 rule-input clients
state_bytes	64 MiB

These are not whole-process RSS limits; systemd/Helm impose additional limits. Queue and rule-state budgets differ. Increasing input buffering cannot solve sustained overload.

Apply changes

Reload the main service for rule files and the analyzer for compatible Wasm updates. Main and endpoint configuration changes need relevant restarts. Schema/sensitivity changes require coordinated activation. Drain/migrate offline before changing WAL paths or disabling sinks. Check first, then verify runtime digests, readiness, and actual events.