Collector configuration

A Nexus Telemetry Fleet collector reads its settings at startup from a configuration file and from environment variables. Where a file key and an environment variable set the same thing, the environment variable wins.

Configuration file

The collector reads one configuration file. It uses the first of these that exists, in this order: a path given as the first argument, the path given with --config, and the packaged path for the platform.

Platform Packaged path
Debian, Ubuntu, RHEL and Fedora /etc/nexus-fleet/collector.toml
macOS /Library/Application Support/NexusFleet/collector.toml
Windows C:\ProgramData\NexusFleet\collector.toml
Docker none by default. Mount one and pass its path

With no file, the collector starts on the defaults in the table below. The packaged installers write a file that sets poll_interval_secs, db_path, data_dir and sources, and on Linux setup_page = "off", so on a packaged install those keys have the values the installer wrote. In particular the installers set sources to ["starlink", "connection", "ping"] where the default is ["host"].

Key Type Default Environment variable
poll_interval_secs integer seconds 10 NF_POLL_INTERVAL
db_path path collector.db inside data_dir none
data_dir path ./data NF_DATA_DIR
local_status string, the values under NF_LOCAL_STATUS below absent, and the onboard status page is off NF_LOCAL_STATUS
site_name string the name the fleet server holds for the collector, else the hostname NF_SITE_NAME
setup_page string 1, on at 127.0.0.1:41700. The deb and rpm write off NF_SETUP_PAGE
sources list of strings ["host"] NF_SOURCES
starlink_addr string http://192.168.100.1:9200 NF_STARLINK_ADDR
location_source string, the values under NF_LOCATION_SOURCE below dish, the Starlink terminal NF_LOCATION_SOURCE
location_lat decimal none NF_LOCATION_LAT
location_lon decimal none NF_LOCATION_LON
location_host string none NF_LOCATION_HOST
location_port integer none NF_LOCATION_PORT
location_device path none, auto-detect NF_LOCATION_DEVICE
location_baud integer 9600 NF_LOCATION_BAUD
location_lock boolean false NF_LOCATION_LOCK

poll_interval_secs in the file, or NF_POLL_INTERVAL in the environment, overrides the interval the fleet server gave the collector at enrolment. With neither set, the collector uses the fleet server’s interval.

Note: an [api] block from an earlier version is read and ignored. The collector connects out to the fleet server and listens on no port for it, so there is no listen address to set.

Environment variables

Variable Sets Default
NF_DATA_DIR Where certificates, enrolment state, the local database and the log are stored. Overrides the file key the file’s data_dir, else ./data
NF_SERVER The fleet server address to enrol against. First run only, and on a re-enrolment none
NF_TOKEN The enrolment token. First run only, and on a re-enrolment none
NF_DEVICE_NAME The name the terminal shows on the dashboard. Used at enrolment only. --name wins over it the hostname
NF_REENROL 1 or true enrols the collector again, with the token in NF_TOKEN, keeping the same record. Nothing happens unless NF_TOKEN is a new token, so it can be left set off
NF_STREAM_URL The address the collector connects to, in place of the one the fleet server gave at enrolment. A blank value means the address from enrolment the address from enrolment, else https://localhost:9443
NF_STREAM_GZIP 0 stops the collector compressing what it sends compression on
NF_POLL_INTERVAL The interval between readings, in whole seconds. Must be greater than 0. Overrides the fleet server’s interval 10, or the fleet server’s interval
NF_SUMMARY_INTERVAL Seconds between the summaries the collector sends. Limited to 5 to 300 30
NF_LIVE_POLL_MS The interval between readings, in milliseconds, while a user has the terminal’s Live view open. Limited to 250 to 10000 1000
NF_HEARTBEAT_SECS Seconds between the heartbeat lines in the log. Limited to 60 to 31536000. A value outside that is logged and limited 3600
NF_SETUP_PAGE The port of the setup page on 127.0.0.1. off, 0 or false turns the page off. A value that is not a number means 41700 the file’s setup_page, else 41700
NF_LOCAL_STATUS The onboard status page: 1, true, on or yes for 0.0.0.0:9210, 0, false or off for none, or an address:port. Overrides the file key and the dashboard switch. An unrecognised value serves no page the file’s local_status, else off
NF_SITE_NAME The site name shown on the onboard status page. Overrides the file key the name the fleet server holds for the collector, else the hostname
NF_SOURCES The sources this collector reads, comma-separated. Checked before enrolment, so a mistyped name stops the collector without using the token the file’s sources, else host

Sources

A source is one of the 4 things a collector can read. NF_SOURCES names one or more. An unknown name is refused with Unknown NF_SOURCES entry '<name>' (known: host, starlink, connection, ping).

Source Reads
host The host the collector runs on: CPU, memory, disk and load
starlink The terminal, over its local interface: status, position and history
connection Which connection traffic is going over, found by connecting to known addresses. The backup connection state comes from this. link, the name before 16 September 2026, is still accepted
ping Reachability from the site: the site’s router, the terminal, then 2 public DNS resolvers
Variable Sets Default
NF_STARLINK_ADDR The terminal’s local address. The starlink_addr file key, the setup page’s Advanced field and nf-collector enrol --starlink-addr all set the same thing. A bare host, or host:port, is completed with http:// and port 9200. The ping source tests this address as one of its built-in targets. An address that cannot be parsed turns the starlink source off, and the log says why http://192.168.100.1:9200
NF_STARLINK_BIND_INTERFACE The network interface the collector uses to reach the terminal. Also used to reach the router the operating system’s choice
NF_CONNECTION_TARGETS The host:port addresses the connection source connects to, comma-separated 1.1.1.1:443, 8.8.8.8:443, 9.9.9.9:443
NF_CONNECTION_PRIMARY_ASN The network that counts as the primary connection, as an AS number. With no primary, the backup connection state is never reported AS14593, Starlink, when this collector also reads starlink. Otherwise none
NF_CONNECTION_ASN_MODE off stops the lookup of which network traffic is going over external, the lookup runs
NF_CONNECTION_ASN_URLS The addresses asked which network traffic is going over, comma-separated. All over HTTPS 1 built-in public lookup service
NF_CONNECTION_IP_URLS The addresses asked for the site’s public address, comma-separated 2 built-in public lookup services
NF_CONNECTION_ASN_INTERVAL_SECS The longest interval between lookups. Must be greater than 0. A lookup also runs when the connection changes 300
NF_CONNECTION_UPLINK_INTERFACE The physical interface under a VPN, read only while a VPN holds the default route read from the route table

Each NF_CONNECTION_ variable is also read under its name before 16 September 2026, NF_LINK_ with the same suffix.

Location

The collector reports a position from one of 7 sources. See Collector GPS for the sources and which takes precedence.

Variable Sets Default
NF_LOCATION_SOURCE One of dish, fixed, off or none, serial, nmea_tcp, nmea_udp, gpsd, in any case. Overrides the file key dish
NF_LOCATION_LAT Latitude, for fixed. A value that cannot be parsed is noted in the log at startup, and the collector runs none
NF_LOCATION_LON Longitude, for fixed. As above none
NF_LOCATION_HOST The host, for nmea_tcp and gpsd none for nmea_tcp. localhost for gpsd
NF_LOCATION_PORT The port, for nmea_tcp, nmea_udp and gpsd. A value that cannot be parsed is noted in the log at startup none for nmea_tcp and nmea_udp. 2947 for gpsd
NF_LOCATION_DEVICE The serial port, for serial none, which means auto-detect
NF_LOCATION_BAUD The serial speed, for serial. A value that cannot be parsed is noted in the log at startup 9600
NF_LOCATION_LOCK 1, true, yes or on gives the collector’s own configuration precedence over the dashboard. The fleet server still records a source set from the dashboard, and the collector does not apply it off

Reachability

The ping source tests a list of targets. The collector has a built-in list: the site’s router, the terminal and 2 public DNS resolvers. The dashboard’s Connectivity checks setting adds to the built-in list, and replaces anything NF_PING_TARGETS added. NF_PING_TARGETS adds to the built-in list, or replaces it with the only: prefix. At most 12 targets are tested in one sweep.

Variable Sets Default
NF_PING_TARGETS Extra targets, comma-separated: host for a ping, or tcp://host:port for a TCP connect. A list that starts with only:, for example only:tcp://10.0.0.1:443, replaces the built-in list instead of adding to it none
NF_PING_LOCK 1 ignores the target list set on the dashboard off, the dashboard’s list is used
NF_PING_ROUTER 1 adds the Starlink router to the targets. A terminal in bypass mode has no router off
NF_ROUTER_ADDR The Starlink router’s local address. Used for the router target and for the speed test http://192.168.1.1:9000

Updates

See Release channels for how a collector updates.

Variable Sets Default
NF_MANAGED_UPDATES 0 refuses updates triggered from the dashboard. Read on Windows only today. On Linux, disable the updater service instead. See Release channels updates accepted
NF_UPDATE_MANIFEST_URL The address of the release manifest, which names the installer to download. An empty value turns updates off. Read on macOS and Windows only https://fleet-downloads.nexustelemetry.com/fleet/stable/latest.json
NF_UPDATE_APPLY_CMD A shell command to run in place of the built-in installer. The version is passed to it in NF_UPDATE_VERSION none
NF_UPDATE_VERSION The version being applied. Set by the collector for NF_UPDATE_APPLY_CMD. Never read from the environment not read

Logging and retention

The collector writes its log to standard error and to a rolling JSON file of bounded size under the data directory. The retention settings below prune the collector’s local store, which holds readings until the fleet server has received them. How long the fleet server keeps readings is set on the dashboard’s Settings page.

Variable Sets Default
NF_LOG The log level: error, warn, info, debug or trace, or a per-module filter in the RUST_LOG syntax. RUST_LOG is read when this is unset. An invalid value means info, with a warning info
NF_LOG_FORMAT json or pretty. An unrecognised value keeps the default, with a warning pretty when writing to a terminal window, json otherwise
NF_LOG_DIR Where the rolling log file is written. A directory that cannot be written means the log goes to standard error only <data_dir>/logs
NF_RAW_RETENTION_DAYS Days of readings kept in the local store. NF_LOCAL_RETENTION_DAYS, the older name, is read when this is unset 7
NF_LOCAL_RETENTION_DAYS The older name of the line above. Read only when NF_RAW_RETENTION_DAYS is unset 7
NF_FINE_RETENTION_DAYS Days of five-minute summaries kept in the local store 90
NF_COARSE_RETENTION_DAYS Days of hourly summaries kept in the local store 365

A retention value that is not a positive whole number is ignored and the default applies, so 0 cannot delete readings before they are sent.

See Server configuration for the fleet server’s variables, and Files and repositories for where each file is on disk.

← Licensing Server configuration →