Collector command line

nf-collector is the command line program on each collector’s host. It takes a command as the first argument, nf-collector status for example. It answers --version with the program name and version, and --help with a usage summary. A flag’s value is the next argument, --flag value, except where this page says otherwise.

nf-collector

With no command, nf-collector runs the collector. At its first run it enrols using NF_SERVER and NF_TOKEN, then reads its sources and sends readings.

Command Flags Effect
enrol --server <url> and --token <token>, or the command prompts for them; --name <display name>, --starlink-addr <host[:port]>, --config <path>, --force Enrols the collector. --starlink-addr writes the terminal’s address into the config file first. With --force, enrols again a collector that already has an identity
status --json, --config <path> Prints the collector’s own status. Connects to nothing and opens no port
diagnose --out <dir> default the working directory, --max-log-mb <n> default 10, --config <path> Writes the support bundle, with secrets left out
reset --force, --keep-data=false, --config <path> Deletes the enrolment, keeping the readings and the identity, so the collector can enrol again. With --keep-data=false, deletes the readings and the identity too. It also deletes parked.json. It changes files only and does not stop or start the service
--help, -h, help none Prints the usage summary
service-run none The entry point of the Windows service. Not for running by hand

Stop the collector’s service before reset, and start it after the new enrolment:

Platform Start the service
Linux sudo systemctl restart nf-collector
macOS sudo launchctl kickstart -k system/com.nexustelemetry.nf-collector
Windows, in an administrator PowerShell Start-Service NexusFleetCollector

In PowerShell, a command that starts with a quoted path is run with & in front: & "C:\Program Files\NexusFleet\nf-collector.exe" reset --force.

--config <path> works with every command, and a bare path as the first argument does the same. --keep-data is the one flag that requires a joined =: --keep-data=false works, and --keep-data false is not understood. A --max-log-mb value that is not a positive number is treated as 10. An unknown flag on status or diagnose is ignored.

The built-in help leaves out --max-log-mb, --keep-data=false, --force on reset, and service-run.

Enrolment prompts

enrol prompts for what is missing when it is run at a terminal window and --server or --token is not given. Run from a script, it prints the usage error instead.

bash
sudo nf-collector enrol

The command prompts for the fleet server address, the token and an optional name. The token is echoed as it is typed, and it stays out of the shell history.

reset lists what it will delete, then asks Continue? [y/N] , unless --force is given. It accepts y, Y or yes. Anything else prints Aborted. and stops.

Exit codes

Command 0 1 2 3
nf-collector status Enrolled Not enrolled Could not produce a status, printed after status: Parked, because the fleet server refused the collector’s certificate
nf-collector diagnose Bundle written The config file could not be read Could not collect or write the bundle not used
nf-collector enrol Enrolled Any failure, printed after Error: not used not used
nf-collector reset Reset done, or the confirmation was declined Unknown flag, an unreadable config file, or a confirmation that could not be read not used not used
nf-collector, no command Stopped by the service manager, or stopped itself after being decommissioned from the dashboard A startup or runtime failure not used

status exits 2 when it cannot read the data directory for lack of permission, and says so, rather than reporting the collector as not enrolled.

Output

Status report

The report has 5 sections, in this order.

Section Contains
Enrolment state reading enrolled, or NOT ENROLLED, set NF_SERVER + NF_TOKEN and start it. Then collector id when enrolled, and device id, stream and via token when each is known. A parked collector adds a PARKED line reading The fleet server refused this collector's certificate. Enrol again or remove this collector., then the time it parked and the number of refusals
Sources One line, the sources the collector reads, comma-separated
Local store Only when enrolled: the database size, then one line per source giving the number of readings and the period they cover, with the latest reading’s values under it
Certificate Only when both a serial and an expiry could be read: serial, cut to 16 characters, and expires with the date, the days left and valid or EXPIRED
Shipping Whether readings are reaching the fleet server. (no snapshot, the daemon has not run since enrolment) when the collector service has not run. daemon reading not running? when the collector’s status file is over 30 seconds old. Otherwise stream reading connected or disconnected, then last ack, when the fleet server last confirmed receipt, backlog, the readings not yet confirmed, and reconnects

--json prints the same report as one JSON object: enrolled, collector_id, device_id, server_url, stream_url, enrolled_via_token, sources, db_size_bytes, domains, cert_serial, cert_not_after_ms, ship, ship_snapshot_age_secs, parked and now_ms. server_url is always null: the address given at enrolment is not kept, and stream_url, the address the collector connects to, is what is used.

Diagnose bundle

diagnose writes one plain text file, nf-diagnose-<YYYYMMDD>-<HHMMSS>.txt, in the working directory, or in the directory given with --out. It is not an archive.

Section Contains
what this bundle contains The list of what is included and what is left out. The command prints the same list to the screen
nf-collector diagnose bundle The time it was written, the version, and one line per built-in source with its schema version and column count
config (redacted) The data directory, the interval, the sources, then set or unset for NF_SERVER, NF_TOKEN, NF_STREAM_URL, NF_LOG, NF_LOG_FORMAT, NF_LOG_DIR, NF_HEARTBEAT_SECS, NF_POLL_INTERVAL and NF_SUMMARY_INTERVAL. Never a value
enrolment enrolled: yes with the collector id, the stream address and the interval, or enrolled: no
status.json The running collector’s status file, as it is
rolling logs The newest log files up to --max-log-mb, oldest first

The enrolment token is never on disk. Private keys, certificates, the local store of readings and any position are not read. The command finishes with Bundle written: and the path, then Attach this file to your support ticket. If no log files were found it says so on standard error and asks for a re-run with the same NF_LOG_DIR the service uses.

See Collector configuration and Private deployment for every variable named here.

← Collector configuration Timings →