N|Solid Console Configuration

Command Line Arguments

These are the supported command line arguments if N|Solid Console is started explicitly.

Parameter	Description
--config=config.toml	The configuration file for Console. The default config will be used if none is specified
--relay	Run Console in Relay mode. This allows you to place an instance in a segment of your network that can aid connectivity and uptime

See Relay Mode for more information.

Configuration File and Environment Variables

N|Solid Console can be configured via a configuration file if the --config argument is specified. This file is formatted as TOML (similar to ini file format). A sample file is available in the file config-sample.toml in the root directory of the nsolid-console server. The contents of the file are also listed below.

To run with a customized configuration, copy the file and edit it so that it contains your customized values. You can omit keys from any section which you don't want to override, and omit entire sections if no keys in that section are overridden.

Alternatively, or in addition, you can set environment variables for every configuration key and value. The names of the environment variables are listed with the configuration keys and values below.

For more information on the TOML language used here, please see the TOML repo.

# config-sample.toml

#-------------------------------------------------------------------------------
# This is a sample configuration file for nsolid-console.  It shows the
# configuration keys and default values for those keys.
#
# To run with a customized configuration, copy this file and edit it so that it
# contains your customized values.  You can omit keys from any section which
# you don't want to override, and omit entire sections if no keys in that
# section are overridden.
#
# Then invoke nsolid-console with the -c or --config command line parameter
# and the name of the customized file.
#
# For example:
#    nsolid-console --config <your-config-file.toml>
#
# Alternatively, or in addition, you can set environment variables for
# every configuration key and value.  The names of the environment variables
# are listed with the configuration keys and values below.
#-------------------------------------------------------------------------------
# For more information on N|Solid, please see:
#    https://docs.nodesource.com/docs/
#
# For more information on the TOML language used here, please see:
#    https://github.com/toml-lang/toml
#-------------------------------------------------------------------------------

#-------------------------------------------------------------------------------
# Properties that are file or directory names can be absolute or relative file
# names. When relative, the names are considered relative to the configuration
# file they were specified in.  When using relative file names as environment
# variables, they will be considered relative to the current working directory.
#-------------------------------------------------------------------------------

#-------------------------------------------------------------------------------
# set the logging level - "info" or "debug" - debug is more verbose
#-------------------------------------------------------------------------------

# environment variable NSOLID_CONSOLE_LOG_LEVEL

logLevel = "info"

#-------------------------------------------------------------------------------
# settings for licensing
#
# key = "the-license-key"
#-------------------------------------------------------------------------------

[license]

# environment variable NSOLID_CONSOLE_LICENSE_KEY

key = ""

#-------------------------------------------------------------------------------
# settings for authentication
#
# requireLogin - If the console should require users to authenticate. This
#                is only enforced with accounts-generated license keys
# adminToken   - A random token that can be used by nsolid-cli for auth
#-------------------------------------------------------------------------------

# environment variable NSOLID_CONSOLE_AUTH_REQUIRE_LOGIN
# environment variable NSOLID_CONSOLE_AUTH_ADMIN_TOKEN

[auth]

requireLogin = true
adminToken = ""

#-------------------------------------------------------------------------------
# settings for the API HTTP server
#
# proto  - "http" or "https"
# server - "<ip addr | hostname>:<port>"
#
# If the environment variable PORT is set, that value, prefixed with ':', will
# be set to the server property. Eg, using PORT=42 will set web.server to ':42'.
#
# httpProxy and httpsProxy are used to set an explicit HTTP/S proxy for HTTP/S
# requests that console makes to the public internet.  You can also set the
# environment variables HTTP_PROXY or http_proxy, and HTTPS_PROXY or https_proxy
# as the value to use.
#-------------------------------------------------------------------------------

[web]

# environment variable NSOLID_CONSOLE_WEB_PROTO
# environment variable NSOLID_CONSOLE_WEB_SERVER
# environment variable NSOLID_CONSOLE_WEB_HTTP_PROXY
# environment variable NSOLID_CONSOLE_WEB_HTTPS_PROXY

proto      = "http"
server     = "0.0.0.0:6753" # 0.0.0.0 allows access on all network interfaces
httpProxy  = ""
httpsProxy = ""

#-------------------------------------------------------------------------------
# settings for running the API HTTP server in https mode
#
# key and cert are file names, as from Node.js https.createServer() options
#
# when set to blank, the files inside the nsolid-console/etc folder will be used:
#   key:  nsolid-self-signed.key
#   cert: nsolid-self-signed.crt
#
# See note above concerning relative paths.
#
# note: generate new default credentials with ./gen-https-creds.sh
# note: default credentials files shipped with nsolid-console expire in 08/2026
#-------------------------------------------------------------------------------

[web.https]

# If set, secureOptions is a bitmask-formatted string of any crypto constants
# documented at https://nodejs.org/api/crypto.html#crypto_openssl_options, eg:
#    "SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1"
# ciphers should be an OpenSSL cipher list formatted string, see
# https://www.openssl.org/docs/man1.0.2/apps/ciphers.html#CIPHER-LIST-FORMAT

# environment variable NSOLID_CONSOLE_WEB_HTTPS_KEY
# environment variable NSOLID_CONSOLE_WEB_HTTPS_CERT
# environment variable NSOLID_CONSOLE_WEB_HTTPS_SECURE_OPTIONS
# environment variable NSOLID_CONSOLE_WEB_HTTPS_CIPHERS

key           = ""
cert          = ""
secureOptions = ""
ciphers       = ""


#-------------------------------------------------------------------------------
# zmq sockets for access by N|Solid processes
#
# commandBindAddr, dataBindAddr, bulkBindAddr are the zmq port addresses
# that will be bound by the server.
#
# publicKey, privateKey are the keys used to encrypt the messages sent over
# zmq.  For more information see:
# https://github.com/msealand/zmq-zap.node/blob/master/examples/curve.js
#
# HWM, bulkHWM are used to set the high water mark for zmq's internal buffering.
# The value indicates the number of messages to buffer, and 0 indicates no limit.
#
# The N|Solid agent will use environment variables that correspond to these
# settings.  For the sockets, the following N|Solid agent environment variable
# should use an address that it can use to connect to the socket the server has
# bound.
#
#    N|Solid agent env vars    server configuration values
#    ----------------------    ---------------------------
#    NSOLID_COMMAND            sockets.commandBindAddr
#    NSOLID_DATA               sockets.dataBindAddr
#    NSOLID_BULK               sockets.bulkBindAddr
#    NSOLID_PUBKEY             sockets.publicKey
#    NSOLID_SAAS               sockets.saas
#
# If running the console server in server mode AND relay mode on the same host,
# the configuration values for the sockets.xxxBindAddr above must be different
# for the server mode and relay configurations.
#-------------------------------------------------------------------------------

[sockets]

# For commandBindAddr, dataBindAddr, and bulkBindAddr, the format should be:
#    tcp://[ipAddress]:[port]
# [ipAddress] should be an ip address - host names cannot be used; use
# "*" to addresses on any available network interface.

# environment variable NSOLID_CONSOLE_SOCKETS_COMMAND_BIND_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_DATA_BIND_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_BULK_BIND_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_PUBLIC_KEY
# environment variable NSOLID_CONSOLE_SOCKETS_PRIVATE_KEY
# environment variable NSOLID_CONSOLE_SOCKETS_HWM
# environment variable NSOLID_CONSOLE_SOCKETS_BULK_HWM
# environment variable NSOLID_CONSOLE_SOCKETS_SAAS

commandBindAddr = "tcp://*:9001"
dataBindAddr    = "tcp://*:9002"
bulkBindAddr    = "tcp://*:9003"
publicKey       = "^kvy<i^qI<r{=ZDrfK4K<#NtqY+zaH:ksm/YGE6I"
privateKey      = "2).NRO5d[JbEFli7F@hdvE1(Fv?B6iIAn>NcLLDx"
HWM             = 0
bulkHWM         = 0
saas            = ""

# The following socket address values are only relevant when running in --relay
# mode. They are analogs of their similiarly named 'xxxBindAddr' values, but
# used as the zmq sockets of the console server to connect to.  These should
# be formatted as "tcp://host:port"
#
# If you want to use a different keypair on the remote endpoint, you may
# specify a remotePublicKey matching that endpoint.  This can be used to
# perform a rolling update to keys without losing data from agents with the old
# encryption key (by using multiple relays)

# environment variable NSOLID_CONSOLE_SOCKETS_COMMAND_REMOTE_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_DATA_REMOTE_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_BULK_REMOTE_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_REMOTE_PUBLIC_KEY

commandRemoteAddr = ""
dataRemoteAddr    = ""
bulkRemoteAddr    = ""
remotePublicKey   = ""

#-------------------------------------------------------------------------------
# Relay mode settings
#
# These settings are specific to running in relay mode.
#
# maxBufferSizeMb is the max buffering "hwm" values shared between the
# "pull/push" sockets in megabytes.
#
# flushInterval is the delay in milliseconds between message sends when the
# buffer is being flushed after a reconnect.
#
# cleanupSizeMb is the amount of megabytes of buffers to be dropped when limits
# are reached.
#
# logSizeInterval is the interval in seconds that will trigger a buffering
# status to be logged. Only happens when upstream (remote) sockets are
# disconnected.
#-------------------------------------------------------------------------------

[relay]

# environment variable NSOLID_CONSOLE_RELAY_MAX_BUFFER_SIZE_MB
# environment variable NSOLID_CONSOLE_RELAY_FLUSH_INTERVAL
# environment variable NSOLID_CONSOLE_RELAY_CLEANUP_SIZE_MB
# environment variable NSOLID_CONSOLE_RELAY_LOG_SIZE_INTERVAL

maxBufferSizeMb = -1
flushInterval   = 1
cleanupSizeMb   = 100
logSizeInterval = 10

#-------------------------------------------------------------------------------
# data settings
#
# dir           - the directory where data will be persisted
# retentionDays - the number of days of metric data that will be retained
# oldDataThresholdMs - how old a record should be to be considered backfill
# backfillTimeoutMs  - after not seeing old data for this long, switch to
#                      standard mode and backfill downsampled records
# dbname        - Influxdb database name
#
# See note above concerning relative paths.
#-------------------------------------------------------------------------------

[data]

# environment variable NSOLID_CONSOLE_DATA_DIR
# environment variable NSOLID_CONSOLE_DATA_RETENTION_DAYS
# environment variable NSOLID_CONSOLE_DATA_OLD_DATA_THRESHOLD_MS
# environment variable NSOLID_CONSOLE_DATA_BACKFILL_TIMEOUT_MS
# environment variable NSOLID_CONSOLE_DATA_DBNAME

dir                = "~/.nsolid-console/data"
retentionDays      = 31
oldDataThresholdMs = 10000
backfillTimeoutMs  = 30000
dbname             = 'database'

#-------------------------------------------------------------------------------
# influxdb settings
#
# url            - base url to connect to externally managed influxdb
# user           - user for the influxdb API, could de local or external influxdb
# password       - password credentials for the Influxdb API
# org            - The influxdb organization to write on
# token          - The influxdb API token
# defaultBucket  - The default bucket (where time series are stored)
# uiDisabled     - Disable/eneble the InfluxDB user interface (disabled by default)
# retentionPeriodSeconds - retention in seconds for the default bucket
# maxConcurrency - Amount of concurrent workers writting metrics
#-------------------------------------------------------------------------------

# environment variable NSOLID_CONSOLE_INFLUXDB_URL
# environment variable NSOLID_CONSOLE_INFLUXDB_USER
# environment variable NSOLID_CONSOLE_INFLUXDB_PASSWORD
# environment variable NSOLID_CONSOLE_INFLUXDB_ORG
# environment variable NSOLID_CONSOLE_INFLUXDB_TOKEN
# environment variable NSOLID_CONSOLE_INFLUXDB_DEFAULT_BUCKET
# environment variable NSOLID_CONSOLE_INFLUXDB_UI_DISABLED
# environment variable NSOLID_CONSOLE_INFLUXDB_RETENTION_PERIOD_SECONDS
# environment variable NSOLID_CONSOLE_INFLUXDB_MAX_CONCURRENCY

[influxdb]

url = ""
user = "nsolid"
password = "L+T;95cTBC}~jPnj"
org = "nsolid"
token = "nsolid-token"
defaultBucket = "agentData"
uiDisabled = true
retentionPeriodSeconds = 3600
maxConcurrency = 2

[[influxdb.policies]]
name = "agentData"
retentionHours = 1
shardRetentionHours = 1
startupRetentionHours = 24
startupShardRetentionHours = 24
default = true

[[influxdb.policies]]
name = "appAverageData"
retentionHours = 1
shardRetentionHours = 1
startupRetentionHours = 24

[[influxdb.policies]]
name = "one_minute_daily"
retentionHours = 24
shardRetentionHours = 1
startupRetentionHours = 24

[[influxdb.policies]]
name = "one_hour_monthly"
retentionDays = 31
shardRetentionDays = 7
useSettingsDuration = true

[[influxdb.policies]]
name = "rp_events"
retentionDays = 365
shardRetentionDays = 7

#-------------------------------------------------------------------------------
# notification settings
#
# consoleURL - the base URL of the console, for use in providing links
# back to the console in notifications.
# stackFrames - the number of frames to be shown in Slack event loop blocked
# notifications
#-------------------------------------------------------------------------------
[notification]

# environment variable NSOLID_CONSOLE_NOTIFICATION_CONSOLE_URL
# environment variable NSOLID_CONSOLE_NOTIFICATION_STACK_FRAMES

consoleURL = "http://localhost:6753"
stackFrames = 10

#-------------------------------------------------------------------------------
# view settings
#
# interval - how often to process saved views
#-------------------------------------------------------------------------------
[view]

interval = 5000

#-------------------------------------------------------------------------------
# anomaly detection settings
#
# memAnomalyTimeout - timeout for anomaly
#-------------------------------------------------------------------------------

# environment variable NSOLID_CONSOLE_MEMORY_ANOMALY_TIMEOUT

[anomaly]

timeout = 60000

#-------------------------------------------------------------------------------
# log settings
#
# influx - the name of the file where the influxd log will be written
#
# See note above concerning relative paths.
#-------------------------------------------------------------------------------

[logs]

# environment variable NSOLID_CONSOLE_LOGS_INFLUX

influx = "~/.nsolid-console/influxdb.log"

#-------------------------------------------------------------------------------
# vulnerability settings
#
# refreshMinutes - how often the vulnerability database will be refreshed
#-------------------------------------------------------------------------------

[vulnerabilities]

# environment variable NSOLID_CONSOLE_VULNERABILITIES_REFRESH_MINUTES

refreshMinutes = 30

#-------------------------------------------------------------------------------
# assets settings - storage of heap snapshots, cpu profiles, etc
#
# cleanupMinutes  - how often the asset files are cleaned up; the oldest asset
#                   files are deleted to ensure constraints below are met.
# maxAssets       - maximum number of assets to retain
# maxAssetsMb     - maximum size of all assets to retain
# summaryTimeout  - Set the minutes you want the worker pool task run for
# summaryLimit    - Set to false, to let the task in the pool run indefinitely
#                   until they complete
#-------------------------------------------------------------------------------

[assets]

# environment variable NSOLID_CONSOLE_ASSETS_CLEANUP_MINUTES
# environment variable NSOLID_CONSOLE_ASSETS_MAX_ASSETS
# environment variable NSOLID_CONSOLE_ASSETS_MAX_ASSETS_MB
# environment variable NSOLID_CONSOLE_ASSETS_SUMMARY_TIMEOUT
# environment variable NSOLID_CONSOLE_ASSETS_SUMMARY_LIMIT

cleanupMinutes  = 5
maxAssets       = 500
maxAssetsMb     = 100
summaryTimeout  = 0
summaryLimit    = true

Advanced Environment Variables

The variables described below should only be necessary if a proxy is required in front of N|Solid Console.

If this is not needed, ignore this section as the variables will be configured by the N|Solid agent via the COMMAND interface.

Environment Variable	Description
NSOLID_DATA	This is the route to the Console data port. It should be formatted as "host:port", and follows the same conventions as NSOLID_COMMAND. If this argument is not specified, N|Solid will attempt to discover this port from Console via the COMMAND interface
NSOLID_BULK	This is the route to the Console bulk port. It should be formatted as "host:port", and follows the same conventions as NSOLID_COMMAND. If this argument is not specified, N|Solid will attempt to discover this port from Console via the COMMAND interface
NSOLID_PUBKEY	This is Console's public key. If a custom key is not configured, the default keypair that ships with N|Solid will be used

External InfluxDB

If you already maintain an instance or cluster of InfluxDB enterprise or want to use Influx Cloud and want N|Solid Console to use your database to store its own metrics, you may do so using the NSOLID_CONSOLE_INFLUXDB_URL, NSOLID_CONSOLE_INFLUXDB_USER and NSOLID_CONSOLE_INFLUXDB_PASSWORD environment variables or set the values at the corresponding configuration file section. This should point to the http(s) listener for your InfluxDB and include the correct protocol and auth credentials if needed.

This will look similar to

NSOLID_CONSOLE_INFLUXDB_URL=http://my-influx-host:8086
NSOLID_CONSOLE-INFLUXDB_USER=myuser
NSOLID_CONSOLE-INFLUXDB_PASSWORD=secret

If errors occur reading or writing to this instance, a notification banner should appear in your console as well as specific error messages in the N|Solid Console log.

N|Solid Console will create and manage its own database and retention policies in the InfluxDB and should be configured using the standard configuration options.

Note: The supported InfluxDB version is v2.x, the InfluxDB instance must be a fresh instance with no initial user, organization and bucket defined; otherwise, N|Solid Console won't set up its standard options or even work.

Stats Retention

Historical metrics, displayed in the line-chart UI elements, are trimmed to the last 15 minutes by default.

License Keys

Registering Your Console

In order to access N|Solid you must have a valid NodeSource account. If you have not connected your Console to your account, when you try and access the console you will be redirected to the welcome screen. Using this form to log into your NodeSource account will automatically configure your Console server and allow you to associate it with your account or organization.

Once connected, you should be immediately redirected to the N|Solid Console.

Updating Your License

If you want your Console to be associated with a different account or organization, click Settings on the right side of the menu at the top of the page.

If you are an administrator for the linked organization, you will see a "Reset License" button which can be used to restore the Console to its initial login state.

If you do not have administrative access to the registered license and need to reset the Console's registration state, you can start the Console with the NSOLID_CONSOLE_AUTH_REQUIRE_LOGIN=false environment variable to disable the authentication requirement and allow access to the Reset Console button. Remember to restart without this setting if authentication is still desired.

User Authentication

Beginning with N|Solid 3.4.0, users will be asked to authenticate before they can access the console. If the user is not the owner of the account or a member of the associated organization, they will not be permitted to access the console.

To allow additional users to access your console, add them to the NodeSource Accounts organization which is associated with this Console.

If you do not wish to enforce user authentication, it can be disabled by setting the NSOLID_CONSOLE_AUTH_REQUIRE_LOGIN=false environment variable or its associated config file setting.

This authentication also impacts nsolid-cli. If you require use of the CLI, you should set NSOLID_CONSOLE_AUTH_ADMIN_TOKEN or the corresponding config file setting to a secure value and use it with the --auth argument. This grants administrative access to the console and should be used with discretion. See Command Line Interface for instructions.

Using StatsD without connecting to Console

You must have a valid license to use the N|Solid Runtime either with the Console or communicating directly to your StatsD endpoint. If you do connect to your N|Solid Console, the license will be configured automatically for you. If you prefer to use your runtime without connecting to console, you must provide your license in the form of a signed token. This can be obtained from a running licensed N|Solid Console by running nsolid-cli license-token or by querying http://console:6753/api/v3/license-token directly.

If you do not have a N|Solid Console available, you can contact NodeSource Support and they can provide you with one. The token will be valid for the duration of your license period and must be refreshed when your expiration date is extended.

Your valid license token can be specified as the NSOLID_LICENSE_TOKEN environment variable or included in the nsolid section of package.json as "licenseToken".

Offline or Air-Gapped operation

Similar to the StatsD situation, your N|Solid installation must have a valid license to operate. If your system is not able to contact the NodeSource web services, you may use the license token as described previously by pasting it into the License Key entry field in your N|Solid Console.

Make sure you are not passing your xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx license key as the token value. This is your license key and cannot be used in offline licensing.

Moving the N|Solid Console server

The data maintained in the N|Solid Console server is stored in a directory determined by the dir property of the [data] section of the configuration file. The default value is ~/.nsolid-console/data. If the contents of the directory are copied to a new machine, the N|Solid Console server can be run with its configuration pointing to the copied directory.

Troubleshooting

Debug Messages

The N|Solid Runtime and CLI all can have debug messaging enabled by using the NODE_DEBUG=nsolid environment variable.

$ NODE_DEBUG=nsolid NSOLID_APP=testapp NSOLID_COMMAND=localhost ~/ns/nsolid-node/nsolid
> NSOLID 16597: starting agent (js init) name: testapp id: e24a79b2aae58b63e385a4c0ce9ed91f3d0202ee tags: undefined
NSOLID 16597: nsolid agent e24a79b2aae58b63e385a4c0ce9ed91f3d0202ee starting with config
NSOLID 16597: { command: '9001',
  data: undefined,
  bulk: undefined,
  pubkey: undefined,
  statsd: undefined,
  statsdBucket: 'nsolid.${env}.${app}.${hostname}.${shortId}',
  statsdTags: undefined,
  hostname: 'rpi3-1',
  env: 'prod',
  interval: null,
  tags: undefined,
  app: 'testapp',
  appVersion: undefined }
NSOLID 16597: { zmq_command_remote: 'tcp://localhost:9001',
  zmq_data_remote: null,
  zmq_bulk_remote: null,
  statsd_addr: null,
  storage_pubkey: '^kvy<i^qI<r{=ZDrfK4K<#NtqY+zaH:ksm/YGE6I' }
NSOLID 16597: registering default commands
NSOLID 16597: nsolid initializing
NSOLID 16597: agent spawn()
NSOLID 16597: agent spawned
NSOLID 16597: e24a79b2aae58b63e385a4c0ce9ed91f3d0202ee nsolid initialized
NSOLID 16597: { command_remote: 'tcp://localhost:9001',
  data_remote: 'tcp://localhost:9002',
  bulk_remote: 'tcp://localhost:9003',
  storage_pubkey: '^kvy<i^qI<r{=ZDrfK4K<#NtqY+zaH:ksm/YGE6I' }