Server configuration

A Nexus Telemetry Fleet server has 2 kinds of setting. Environment variables are read when it starts. The fields on the dashboard’s Settings page are stored in its database. No setting is in both. Variables used only in development and testing are left out of this page.

Environment variables

A variable is read at startup unless its notes say otherwise, so a change takes effect at the next restart. A packaged fleet server reads its variables from /etc/nexus-fleet/server.env. A container reads them from the environment: block of its compose file.

Listening and names

Variable Sets Default
NF_LISTEN The address and port the dashboard listens on. An address other than loopback, with no TLS, is warned about at startup 127.0.0.1:3000
NF_DATA_DIR Where the databases, the certificate authority and the keys are stored. The packages set /var/lib/nexus-fleet. The command line reads it too ./data
NF_STREAM_LISTEN The address and port collectors connect to. A value that cannot be parsed stops the fleet server at startup 0.0.0.0:9443
NF_STREAM_SAN The name written into the fleet server’s certificate at the first run, and given to collectors at enrolment as the address to connect to. localhost and 127.0.0.1 are always included as well. Read again whenever the certificate is issued localhost
NF_SERVER_URL The fleet server address written into the enrolment commands the dashboard generates. When set, it is used instead of the address the browser reached the dashboard at. The command line prints http://<fleet-server>:3000 when it is unset http:// followed by NF_LISTEN
NF_ORG_BASE_DOMAIN The domain that organisations’ web addresses are under, so that the Organisations page can show each organisation’s full address. Read on every load of the Organisations page none
NF_PLATFORM_ORG_SLUG The platform organisation’s short name, at the first run. First run only. It does not rename. A value that is not a bare short name is refused with a warning, and default is used default
NF_PLATFORM_ORG_NAME The platform organisation’s display name, at the first run. First run only Default Organisation
NF_PROBE_TOKEN The bearer token that opens the full /healthz body, with the uptime, the stream count, the enrolled count, the rollup lag and the version, and /metrics, to a monitoring system. Without it /metrics is refused. Without it, or with a wrong one, /healthz answers with the status alone unset, and the full body is never served

TLS and proxy

Variable Sets Default
NF_DASHBOARD_TLS_CERT The path of the dashboard’s certificate chain, a PEM file. Both this and the key must be set for HTTPS none, plain HTTP
NF_DASHBOARD_TLS_KEY The path of that certificate’s private key, a PEM file. With only one of the two set, the dashboard stays on plain HTTP. Nothing warns about the half-set pair, and a non-loopback NF_LISTEN still warns about plain HTTP none
NF_TRUST_FORWARDED_PROTO 1, true or on trusts the X-Forwarded-Proto header from a proxy, so that the session cookie is marked Secure. Never set it where the dashboard port is reachable directly off
NF_STREAM_MAX_CONNS The most collector connections open at the same time. Must be greater than 0 8192
NF_STREAM_HANDSHAKE_MAX The most TLS handshakes in progress at the same time. A collector arriving above it is refused and retries. Must be greater than 0 32

Licensing

Variable Sets Default
NF_LICENCE_CHECK off, 0 or false stops the daily online check of the licence key. Startup only the check runs
NF_LICENCE_URL The address the licence key is checked against. Startup only https://licensing.nexustelemetry.com
NF_LICENCE_GRANT A licence key to apply at startup. Applied only while no key is stored. A key that is refused is logged and ignored, and the fleet server starts none

Updates

Variable Sets Default
NF_UPDATE_CHECK off, 0 or false stops the check for a newer fleet server version. Startup only the check runs
NF_UPDATE_CHECK_URL The download host used by the update check and by the enrolment commands the dashboard generates. Read each time Add telemetry collector opens https://fleet-downloads.nexustelemetry.com
NF_UPDATE_CHANNEL The release channel the fleet server compares its version against. Read once at startup for the version check, and again each time the enrolment commands or About are rendered. The value is used as typed, without checking that the channel exists the channel in the apt repository file, else stable
NF_UPDATE_MANIFEST_URL The address of the collector release manifest, which the dashboard reads to know which collectors are behind their channel. An empty value turns updates from the dashboard off. A value beginning / is read as a local file <download host>/fleet/<channel>/latest.json

Alerts and email

Variable Sets Default
NF_SENDGRID_API_KEY The SendGrid key that alert email is sent with. Read at every send, so it can be set without a restart none, and no email is sent
NF_SENDGRID_API_KEY_FILE A file containing that key. Read only when the variable above is unset or empty, so the key in the file can change without a restart none
NF_ALERT_FROM The address alert email comes from. Read at every send [email protected]
NF_ACCOUNT_FROM The address account email, the verification code, comes from. Read at every send [email protected]
NF_AUTH_EMAIL_ECHO 1, true or on writes each sign-in verification code to the log instead of sending it. A fleet server with no SendGrid key writes them to the log whatever this is set to. For a test fleet server only. Never set on a production fleet server unset
NF_ALLOW_PRIVATE_WEBHOOKS Allows a webhook address on a loopback or private network address. Setting the variable to anything, an empty value included, allows them. Link-local, metadata, unspecified and broadcast addresses are refused whatever it is set to such addresses are refused when saved

State timings

The 4 NF_STATUS_ variables exist for test runs that need faults confirmed faster. A production fleet server leaves them unset.

Variable Sets Default
NF_STATUS_CONFIRM_SECS How long a fault must last before the state changes. Must be greater than 0. The value is fixed per organisation at the first pass after a restart 180
NF_STATUS_HOLD_SECS How long a recovery must last before the state returns to healthy. As above 300
NF_STATUS_COALESCE_SECS How close together two faults must be to count as one incident. As above 600
NF_STATUS_SWEEP_SECS Seconds between the passes that re-check every terminal’s state. Must be greater than 0. Startup only 30
NF_SETTLE_SECS Seconds after a fleet server restart during which terminals that have not yet reconnected show as Planned outage rather than Outage on the dashboard. 0 turns this off. Startup only 3600

Tiles and weather

Variable Sets Default
NF_TILES_URL The map tile server the Map fetches its background from, through the fleet server. A fleet server with no internet access uses a local tile server here. Read whenever a tile is not already cached https://tiles.nexustelemetry.com/basemap
NF_TILES_TOKEN The value sent to the tile server in the X-Nexus-Tiles header. An empty value sends no header nf-server-selfhost-v1
NF_WEATHER on or 1 turns the weather panels on. Startup only off
NF_WEATHER_API_KEY A key for the paid weather service. With a key set, the 2 addresses below default to the paid service’s hosts none
NF_WEATHER_URL The forecast address https://api.open-meteo.com/v1/forecast, or the paid host with a key
NF_WEATHER_MARINE_URL The marine forecast address https://marine-api.open-meteo.com/v1/marine, or the paid host with a key
NF_WEATHER_DAILY_CAP The most weather requests made in a day. 0 is accepted and stops every request 8000
NF_WEATHER_REFRESH_SECS How old a forecast may be before the background pass fetches it again. The pass runs every 300 seconds 3600
NF_WEATHER_CLICK_MIN_SECS How old a forecast may be before opening its panel fetches it again 900
NF_WEATHER_SWEEP off or 0 stops the background pass, so forecasts are fetched only when a panel is opened. Startup only the pass runs

Backups

Variable Sets Default
NF_BACKUP_MAX_AGE_HOURS How old the newest successful backup may be before the Backups check on Server health reads Problem. Must be greater than 0. Read on every load of the page 26

The scheduled backup’s own settings are in /etc/nexus-fleet/backup.env, not in the fleet server’s environment. See Backup and restore.

Custody and keys at rest

Variable Sets Default
NF_CUSTODY_PUBLIC_KEY An X25519 public key. A new organisation’s root key is encrypted to it and kept off the host. Base64, exactly 32 bytes. A value that cannot be decoded fails the creation of a new organisation, and the custody commands, with an error. It never falls back to keeping the key on the host none, and root keys stay on the host
NF_CUSTODY_P256_PUBLIC_KEY A second public key, held in a hardware security module. Base64, exactly 65 bytes beginning 04. With both set, a new root key is encrypted to both none
NF_STOCK_WINDOWS_ON_BOX How many of the prepared CA certificates, the signing cover, are kept on the host. The rest are encrypted and kept elsewhere. See Certificates. Must be 1 or more. Read on every top-up and by the custody commands 2
NF_DEK_KEYSTORE 1, true or yes keeps the data encryption key in the operating system’s keystore as well as in dek.key. shred then deletes dek.key once the keystore is confirmed to have the key the key is in dek.key only

Microsoft sign-in

The three registration variables are read once at startup. All three are required for Microsoft sign-in to be available, and it is then turned on per organisation in Settings. See Sign-in.

Variable Sets Default
NF_OIDC_CLIENT_ID The application id of the Microsoft Entra app registration. A value that is not a GUID is refused at load, logged as oidc.client_invalid, and Microsoft sign-in stays off unset, and Microsoft sign-in is off
NF_OIDC_KEY_FILE The private key the fleet server signs its requests to Microsoft with, a PKCS#8 PEM file. Its certificate is uploaded to the app registration unset
NF_OIDC_CERT_FILE That certificate, a PEM file unset
NF_OIDC_ISSUER_BASE The issuer address, with {tenant} standing for the organisation’s tenant id https://login.microsoftonline.com/{tenant}/v2.0
NF_OIDC_REDIRECT_BASE One fixed address the sign-in returns to, for a deployment of many fleet servers behind one app registration. The sign-in is then sent on to the fleet server it started at unset, and the sign-in returns to the fleet server’s own address

Enrolment and first run

Variable Sets Default
NF_ENROL_MAX_PER_IP Enrolment attempts allowed from one source address in a minute. Must be 1 or more. Read at the first enrolment attempt and not again. The other enrolment limits, 20 failures per token and 100 per fleet server in a minute, are fixed 30
NF_INITIAL_ADMIN_PASSWORD Creates the first user, admin with the Owner role, at the first start, with this password. Applied only while no user exists. Otherwise it is logged as ignored. The value is never logged none, and the first user is created at the command line

Data and logging

Variable Sets Default
NF_LIVE_RING_MINUTES Minutes of live readings kept in memory, per terminal and per source. Must be greater than 0, and at most 240. Read at first use 30
NF_POLL_INTERVAL The interval between readings, in seconds, given to collectors at enrolment. A connected collector that has sent nothing for 3 intervals plus 30 seconds, and at least 120 seconds, is marked offline. With the default, that is 120 seconds 30
NF_LOG The log level, as a RUST_LOG filter. RUST_LOG is read when this is unset. An invalid filter means info, with a warning info
NF_LOG_FORMAT json or pretty. An unrecognised value keeps the default, with a warning json
NF_HEARTBEAT_SECS Seconds between the heartbeat lines in the log. Limited to 60 to 31536000, and a limited value is logged 3600
NF_PLAUSIBLE_DOMAIN The site name for page view analytics on the dashboard. Unset on every customer fleet server, so no analytics script is served. Set only on the public demo unset
NF_PLAUSIBLE_ORIGIN The analytics server the script reports to. Read only when NF_PLAUSIBLE_DOMAIN is set https://pl.nexustelemetry.com
NF_DEMO Marks the fleet server as the public demo, with the watermark and the shared sign-in hint. Never set on a customer fleet server unset

The fleet server writes no log file. Its log goes to standard output. NF_LOG_DIR is a collector setting only.

Settings page

The dashboard’s Settings page holds the settings stored in the fleet server’s database. Fields under Terminals and Data save when changed. Connectivity checks and Maintenance notice save on their own button. See Settings for using the page.

Appearance

Appearance is stored in the browser, not on the fleet server.

Field Sets Default Range Takes effect
Theme The colour scheme Dark System, Dark, Light On change, in this browser
Display scale The size of everything on screen, as a percentage Normal, 100 Extra Small 80, Small 90, Normal 100, Large 110, Extra Large 120, Maximum 150 On change, in this browser

Terminals

Field Sets Default Range Takes effect
Stale threshold How long a terminal may be silent before it is marked stale 1 day 1 minute to 1 year Within 30 seconds
Decommission timeout How long a decommission waits for an offline collector to connect and confirm, before completing without it 10 minutes 1 minute to 1 day Within 30 seconds, for decommissions already waiting as well

Stale threshold takes Minutes, Hours, Days or Years. Decommission timeout takes Minutes, Hours or Days.

Data

Every field here takes Days or Years, and is stored as whole days.

Field Sets Default Range Takes effect
Raw readings How long every reading is kept 7 days 1 to 3650 days Within 30 seconds
5-minute summaries How long 5-minute summaries are kept. The percentiles inside each summary are kept for 30 days, the averages for the whole period 90 days 1 to 3650 days Within 30 seconds
Hourly summaries How long hourly summaries are kept. The percentiles inside each summary are kept for 90 days, the averages for the whole period 2 years 1 to 3650 days, and never less than 5-minute summaries Within 30 seconds
Audit log How long audit entries are kept 90 days 1 to 3650 days Within 30 seconds

Daily summaries are kept forever. Audit entries for revoked certificates are kept forever, whatever Audit log is set to. A setting that cannot be read is skipped on that pass rather than replaced by a default, so a bad value never deletes anything.

Connectivity checks

Connectivity checks is one form, saved with Save targets. At most 12 targets are tested in one sweep.

Field Sets Default Range Takes effect
Address The target’s host name or IP address empty No comma and no equals sign On Save targets
Label The name shown for the target empty, shown as - Up to 20 characters, no comma or equals sign On Save targets
Test Ping or TCP connect Ping the two On Save targets
Port The port, for TCP connect 443 1 to 65535 On Save targets
Also test the built-in targets Adds the terminal, the site’s router, and Cloudflare’s and Google’s public resolvers on on or off On Save targets

The fleet server sends the saved list to every collector each time it connects, and to connected collectors when the list is saved. Test now tests from the fleet server and stores nothing. It waits up to 3 seconds, allows 20 tests a minute per user, and answers Reachable, No answer, Name not found, Invalid address or Try again in a minute.

Maintenance notice

Maintenance notice is one form, saved with Post notice.

Field Sets Default Range Takes effect
Start (UTC) When the maintenance starts empty, and no notice is shown A date and time. Clearing it withdraws the notice Within 60 seconds
Expected minutes How long the maintenance lasts empty, read as 0 0 to 1440. 0 shows no banner Within 60 seconds
Note (optional) Text shown with the notice empty Up to 200 characters Within 60 seconds

The notice is shown as a banner from 7 days before the start, is red once the start has passed, and clears when the expected minutes have passed.

Email

Email is read-only. Every row shows the environment as it is at the next send, with no restart.

Field Shows From
Email delivery Configured or Not configured NF_SENDGRID_API_KEY, else NF_SENDGRID_API_KEY_FILE
Sender address, alerts The address alert email comes from NF_ALERT_FROM
Sender address, account codes The address account email comes from NF_ACCOUNT_FROM

Licence

Licence has read-only rows and the field that applies or removes a licence key.

Field Shows Takes effect
Status, Licence type, Licensed to, Expires, Collectors, Last validated The stored licence key Read on each load
Organisation root fingerprint The fingerprint the licence key is tied to. It is the same after a backup and restore Fixed
Licence key with Apply key Applies a pasted key On press, without a restart
Remove key Removes the key After a confirmation, without a restart

About

About is read-only. It shows the version and its release channel, Edition, Platform, whether an update is published, and links to the documentation, the release notes, the privacy policy, the terms and support.

Settings versus environment

Everything under Terminals, Data, Connectivity checks and Maintenance notice is stored in the fleet server’s database only. No environment variable overrides it, and a change takes effect within 30 seconds for Terminals and Data, within 60 seconds for Maintenance notice, and on save for Connectivity checks, without a restart.

4 things on the page come from the environment. Email reads the 3 sending variables at every send. Microsoft sign-in under Authentication is available only with the NF_OIDC_* variables set. The release channel on About is NF_UPDATE_CHANNEL if set, else the one in the apt repository file. Licence applies NF_LICENCE_GRANT only while no key is stored, and the stored key takes precedence from then on.

Certificate lifetimes have no field on the page. They are set when the fleet server is deployed, and their defaults are in Timings.

See Collector configuration for the collector’s variables.

← Collector configuration Command line →