Command line

Nexus Telemetry Fleet has 2 command line programs, nf-server on the fleet server and nf-collector on each collector’s host. Both take a command as the first argument, nf-server create-token for example. Both answer --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-server

The nf-server commands run on the fleet server’s host, as the account the fleet server runs as. Every command opens the data directory named by NF_DATA_DIR first. On a fleet server installed from the deb or rpm package, that is /var/lib/nexus-fleet, and the command is run as in the example on Install.

Command Flags Effect
create-token --name <name> required; --org <id|slug>, --fleet <name|id>, --max-uses <n> default 1, --expires <n>m|h|d default 24h, --no-expire Generates an enrolment token and prints it once
list-tokens --all Lists the tokens that are not revoked: ID, NAME, USES, EXPIRES, STATUS, the status active, exhausted or expired. --all includes revoked tokens
revoke-token <TOKEN_ID> required Revokes a token
update-collector <ID> required; then at least one of --name "<new name>", --fleet <name|id>, --no-fleet Renames the collector’s terminal, or moves it to another group or out of its group
create-org --name "<name>" required; --slug <slug>, --parent <id|slug>, --demo Creates an organisation with its own certificate authority
list-orgs none Lists every organisation: ID, SLUG, STATUS, PARENT
suspend-org <id|slug> required, or --org <id|slug> Suspends the organisation and every organisation beneath it: their collectors are disconnected, and enrolment and sign-in are refused
resume-org the same Ends a suspension
cancel-org the same Cancels the organisation. Its data is deleted after 7 days
move-org <id|slug> required; --parent <id|slug|none> required Moves an organisation under another parent. A move that would make a loop is refused
purge-org <id|slug> required, or --org <id|slug> Deletes a cancelled organisation’s data without waiting the 7 days. Refused unless the organisation is cancelled
create-fleet --org <id|slug> and --name "<name>", both required Creates a group
list-fleets <id|slug> required, or --org <id|slug> Lists an organisation’s groups
create-operator --username <name> required; --org <id|slug>, --role owner|admin|operator|viewer default owner, --password <pw>, --email <address> Creates a user
list-operators --org <id|slug> Lists users: USERNAME, ROLE, KIND, LAST LOGIN, TWO-FACTOR
reset-password <username> required, or --username <name>; --org <id|slug>, --password <pw> Resets a user’s password
reset-two-factor <username> required, or --username <name>; --org <id|slug> Removes two-factor sign-in from a user and ends their sessions. Their next sign-in is the password alone. For the case where no administrator can remove it from the dashboard
delete-operator <username> required; --org <id|slug> Deletes a user and ends their sessions
backup --out <dir>, --no-verify, --registry-only, --org <id|slug> Writes a checked backup while the fleet server is running. See Backup and restore
check-invariants --ledger <path> Checks every organisation’s stored summaries for inconsistencies, and exits non-zero on any
db-stats none. Any flag is ignored Prints the row count of each table and the size on disk, per organisation
root-key an action, then --org <id|slug>, --out <file>, --file <file>, --depth <n>, --current, --fingerprint <hex> Root key ceremonies. The actions are status, runway, deliver-window, rebirth, trim-stock, export, verify, remove, import, sign-queue, revoke-intermediate and rollover
routes --json Lists every dashboard route with the permission it requires

--registry-only and --org cannot both be given to backup. revoke-intermediate requires at least one of --current and --fingerprint, and --fingerprint can be repeated. Every root-key action acts on an organisation’s root key with --org, and on the fleet server’s own root key without it. rollover acts on the fleet server’s own root key only, and refuses --org. See Best practice for the everyday actions.

Note: the command line says fleet where the dashboard says group, and operator where the dashboard says user. create-fleet, list-fleets, --fleet and --no-fleet name a group. create-operator, list-operators and delete-operator act on a user.

Passphrase prompts

The 3 root-key actions that open or write a passphrase-protected bundle ask for the passphrase at a prompt, without echoing it. There is no flag for it.

Action Prompt
export New bundle passphrase: , then Confirm passphrase: . An empty or mismatched pair is refused
verify Bundle passphrase:
import Bundle passphrase:

No other nf-server command prompts. create-operator and reset-password generate a password when --password is not given, and print it once under (Shown once - store it now.). create-token prints the token once, under This token will not be shown again. A password given as a flag is visible in the shell history and in the process list.

purge-org, cancel-org and delete-operator ask for no confirmation. Each refuses to run unless the organisation or user is in the right state.

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
--help, -h, help none Prints the usage summary
service-run none The entry point of the Windows service. Not for running by hand

--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
nf-collector status Enrolled Not enrolled Could not produce a status, printed after status:
nf-collector diagnose Bundle written The config file could not be read Could not collect or write the bundle
nf-collector enrol Enrolled Any failure, printed after Error: 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
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
nf-server, every command Success Any failure, including check-invariants finding an anomaly 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
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 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, the data key 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 Server configuration for every variable named here.

← Server configuration Timings →