Configuration

nfsen-ng is configured through environment variables (NFSEN_*) — the recommended path for both Docker and bare-metal. Every variable has one default and one validator, defined once in backend/common/EnvRegistry.php.

A legacy settings.php file is still supported for custom filter presets or unusual bare-metal layouts, but is deprecated. When present it acts as an overlay on top of the environment: any key it defines wins, and any key it omits falls back to the matching environment variable (then the built-in default). An active settings.php is flagged on the Settings → Health page.

Invalid values, deprecated variable names, and unknown NFSEN_* variables (typos) never fail the boot — a bad value falls back to its default and is called out on the Health page, so misconfiguration is visible instead of silent.

A third layer sits on top: preferences.json, the user settings saved from the web UI. It overlays the deployment config and wins for the fields the Preferences tab owns (UI defaults, filter presets, display timezone, and log level). See Preferences — notably, a saved logPriority overrides NFSEN_LOG_LEVEL.

Environment variables

Sources & data

A settings.php that defines general.sources, ports, filters, or processor overrides the matching variable; where the file omits a key, the environment variable is used.

Core

nfdump / nfcapd paths

Import

Changing NFSEN_IMPORT_YEARS after the first import only affects the RRD daily-archive depth, which is fixed at creation time. To resize it, run Force Rescan from the Settings → Import panel to recreate the RRD files. Rebuilding is a UI action — there is no import-trigger environment variable.

RRD storage

VictoriaMetrics

See VictoriaMetrics for the full setup.

NetBox IP lookup

nfsen-ng can enrich private/reserved IPs in the Flows view with metadata from a NetBox IPAM instance. When configured, clicking such an address opens a modal with its NetBox description, tenant, VRF, role, and status. Only private/reserved ranges are looked up; public IPs fall through to the geo lookup.

Both are also settable as general.netbox_url / general.netbox_token in settings.php. The integration is disabled while either value is empty.

Alert email

OpenSwoole server

The comments in the shipped compose files quote different Swoole defaults (4 / 10000); the values above are what the code actually defaults to.

State & persistence

All of nfsen-ng’s own persistent data lives under one directory, /var/lib/nfsen-ng, in two subdirectories:

This is deliberately separate from the nfcapd capture tree (/data/nfsen-ng), which the collector owns and which is usually managed on its own retention schedule.

In Docker this must live on a volume, or a container recreation (every image upgrade) wipes your RRD graphs, preferences, and alerts:

• The image defaults NFSEN_RRD_PATH and NFSEN_STATE_DIR into /var/lib/nfsen-ng and declares it a VOLUME, so even a bare docker run persists in an anonymous volume.
• The shipped compose files map a named volume there (nfsen-data), which also survives docker compose down and is easy to back up. Unraid mounts /mnt/user/appdata/nfsen-ng-data.
• Dev (bind-mounted source) and bare-metal keep the built-in defaults (backend/datasources/data and backend/settings), next to the code.

To back up or migrate an instance, copy /var/lib/nfsen-ng — that single directory holds both your graphs and your configuration.

Settings file (deprecated)

Deprecated. File-based config predates the environment-variable model and is kept only for backward compatibility. New installs should use NFSEN_* variables; an active settings.php is flagged on the Health page and may be removed in a future major release.

For custom filter presets or a bare-metal path layout, copy the template and edit it:

cp backend/settings/settings.php.dist backend/settings/settings.php

The file must assign the global $nfsen_config array — nfsen-ng includes it and reads that global. A file that returns an array (or defines any other variable) is silently ignored and you get empty settings. The file is an overlay on the environment: any key you set wins, and any key you omit falls back to the matching NFSEN_* variable, then the built-in default.

<?php
$nfsen_config = [
    'general' => [
        'sources' => ['gw1', 'router'],   // nfcapd source names
        'ports'   => [80, 443, 22],        // ports to track in RRD
        'filters' => ['proto tcp', 'dst port 80'], // nfdump filter presets
        'db'      => 'RRD',                // 'RRD' or 'VictoriaMetrics'
        'processor' => 'NfDump',
        'max_stats_window' => 0,           // seconds; 0 = unlimited
        'netbox_url'   => '',
        'netbox_token' => '',
    ],
    'nfdump' => [
        'binary'        => '/usr/local/nfdump/bin/nfdump',
        'profiles-data' => '/var/nfdump/profiles-data',
        'profile'       => 'live',
        'max-processes' => 1,
    ],
    'db' => [
        'RRD'            => ['data_path' => null, 'import_years' => 3],
        'VictoriaMetrics'=> ['host' => 'victoriametrics', 'port' => 8428, 'import_years' => 3],
    ],
    'log' => ['priority' => \LOG_INFO],
];

Key reference (the template ships more, including frontend.defaults.* UI defaults):

Note the key spelling: nfdump.profiles-data and nfdump.max-processes use dashes; general.max_stats_window, general.netbox_url, and general.netbox_token use underscores. import_years is read from under the sub-key that matches general.db (e.g. db.RRD.import_years).

Timezones

nfcapd names files using the local time of the host running it. nfsen-ng parses those filenames back to epochs to place data on the timeline. If the two run in different timezones (classic case: bare-metal nfcapd in CEST, nfsen-ng in a TZ=UTC container), set NFCAPD_TZ to the capture host’s IANA timezone. When unset, nfsen-ng falls back to PHP’s effective timezone. Getting this wrong shifts every RRD timestamp and chart label by the UTC offset.

RRD data retention

RRD files are independent of nfcapd files. Deleting old capture files does not touch RRD graphs, and vice versa. See Data Sources for the conceptual split.

nfsen-ng creates one fixed-size .rrd file per source (and per tracked port). The size is set at creation and never grows. Each file holds four resolutions (each stored as both an AVERAGE and a MAX archive):

Only the daily archive’s depth changes with NFSEN_IMPORT_YEARS; the finer three are fixed.

Disk space

Because the fine-resolution archives dominate and are fixed, every .rrd file is roughly the same size — about 5 MiB — whether it’s an aggregate or a per-port file, and almost independent of NFSEN_IMPORT_YEARS (the daily archive is a small fraction of the total). Budget accordingly:

• ~5 MiB per source (aggregate)
• ~5 MiB per tracked port, per source

So 10 sources × 5 tracked ports ≈ 60 files ≈ ~300 MB total. This is a flat, predictable cost — RRD files are circular buffers that never grow with traffic volume.

Changing retention depth

To store more (or fewer) years of daily data, set NFSEN_IMPORT_YEARS and then recreate the RRD structure with Settings → Import → Force Rescan (the server also logs a warning on start if it detects a size mismatch):

# docker-compose.yml
environment:
  - NFSEN_IMPORT_YEARS=5   # 5 years of daily graph data
  # then run Force Rescan once from the web UI to rebuild the RRD files

RRD vs nfcapd files