N|Solid Documentation

Versions

Networking

N|Solid Storage

N|Solid Storage is the component that provides data persistence for your measurements and artifacts, such as snapshots and CPU profiles. It communicates directly with your N|Solid Agent processes and provides the API interface for both nsolid-cli and nsolid-console.

Command Line Arguments

These are the supported command line arguments if you're starting N|Solid Storage explicitly.

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

Configuration File

N|Solid Storage 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 default-config.toml in the etc directory of the nsolid-storage 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: 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_STORAGE_LOG_LEVEL

logLevel = "info"

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

[license]

# environment variable NSOLID_STORAGE_LICENSE_KEY

key = ""

#-------------------------------------------------------------------------------
# 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 storage 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_STORAGE_WEB_PROTO
# environment variable NSOLID_STORAGE_WEB_SERVER
# environment variable NSOLID_STORAGE_WEB_HTTP_PROXY
# environment variable NSOLID_STORAGE_WEB_HTTPS_PROXY

proto      = "https"
server     = "0.0.0.0:4000" # 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-storage/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-storage expire in 08/2026
#-------------------------------------------------------------------------------

[web.https]

# environment variable NSOLID_STORAGE_WEB_HTTPS_KEY
# environment variable NSOLID_STORAGE_WEB_HTTPS_CERT

key  = ""
cert = ""

#-------------------------------------------------------------------------------
# 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
#
# If running the storage 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]

# [::] means "any address", covering both ipv4 and ipv6.

# environment variable NSOLID_STORAGE_SOCKETS_COMMAND_BIND_ADDR
# environment variable NSOLID_STORAGE_SOCKETS_DATA_BIND_ADDR
# environment variable NSOLID_STORAGE_SOCKETS_BULK_BIND_ADDR
# environment variable NSOLID_STORAGE_SOCKETS_PUBLIC_KEY
# environment variable NSOLID_STORAGE_SOCKETS_PRIVATE_KEY
# environment variable NSOLID_STORAGE_SOCKETS_HWM
# environment variable NSOLID_STORAGE_SOCKETS_BULK_HWM

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

# 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 storage server to connect to.  These should
# be formatted as "tcp://host:port"

# environment variable NSOLID_STORAGE_SOCKETS_COMMAND_REMOTE_ADDR
# environment variable NSOLID_STORAGE_SOCKETS_DATA_REMOTE_ADDR
# environment variable NSOLID_STORAGE_SOCKETS_BULK_REMOTE_ADDR

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

#-------------------------------------------------------------------------------
# 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.
#
# 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_STORAGE_RELAY_MAX_BUFFER_SIZE_MB
# environment variable NSOLID_STORAGE_RELAY_CLEANUP_SIZE_MB
# environment variable NSOLID_STORAGE_RELAY_LOG_SIZE_INTERVAL

maxBufferSizeMb = -1
cleanupSizeMb   = 100
logSizeInterval = 10

#-------------------------------------------------------------------------------
# data settings
#
# dir - the directory where data will be persisted
#
# See note above concerning relative paths.
#-------------------------------------------------------------------------------

[data]

# environment variable NSOLID_STORAGE_DATA_DIR

dir = "~/.nsolid-storage/data"

#-------------------------------------------------------------------------------
# notification settings
#
# consoleURL - the base URL of the console, for use in providing links
# back to the console in notifications.
#-------------------------------------------------------------------------------
[notification]

# environment variable NSOLID_STORAGE_NOTIFICATION_CONSOLE_URL

consoleURL = "http://localhost:3000"

#-------------------------------------------------------------------------------
# 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_STORAGE_LOGS_INFLUX

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

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

[vulnerabilities]

# environment variable NSOLID_STORAGE_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
#-------------------------------------------------------------------------------

[assets]

# environment variable NSOLID_STORAGE_ASSETS_CLEANUP_MINUTES
# environment variable NSOLID_STORAGE_ASSETS_MAX_ASSETS
# environment variable NSOLID_STORAGE_ASSETS_MAX_ASSETS_MB

cleanupMinutes  = 5
maxAssets       = 500
maxAssetsMb     = 100

Relay Mode

N|Solid Storage supports running in a relay mode in order to support proxying through firewalls, buffering agent data during downtime and scaling with complex network topologies.

The relay sits between agents and N|Solid Storage (in default or relay configuration). In this mode, nsolid-storage looks like an N|Solid Storage instance to agents but does not have any N|Solid Storage functionality enabled.

Relay Configuration

To use relay mode, set the --relay flag and the three [sockets] variables described below. These can be provided via the configuration file or as environment variables. If omitted, the defaults will be used.

You should change the NSOLID_COMMAND, NSOLID_DATA and NSOLID_BULK variables as those will be the ones that the relay itself listens on while it uses the NSOLID_STORAGE_SOCKETS-* variables in order to connect to N|Solid Storage.

In the simplest case you will set the NSOLID_STORAGE_SOCKETS_* variables to the same that the related NSOLID_* variables were set to and pick different addresses for the NSOLID_STORAGE_SOCKETS_* variables.

Environment Variables

Environment Variable Description
NSOLID_STORAGE_SOCKETS_COMMAND_REMOTE_ADDR This is the route to the Storage command port that the relay will use to connect to it. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND
NSOLID_STORAGE_SOCKETS_DATA_REMOTE_ADDR This is the route to the Storage data port that the relay will use. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND. Unlike NSOLID_DATA you have to specify this variable or include it in your config.
NSOLID_STORAGE_SOCKETS_BULD_REMOTE_ADDR This is the route to the Storage bulk port that the relay will use. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND. Unlike NSOLID_BULK you have to specify this variable or include it in your config.

Configuration File

Below is an example of configuring of the [sockets] section of a configuration file to support relay mode. Note that we also changed the related Bind addresses.

[sockets]
commandBindAddr = "tcp://<storage-address>::8001"
dataBindAddr    = "tcp://<storage-address>:8002"
bulkBindAddr    = "tcp://<storage-address>:8003"

commandRemoteAddr = "tcp://<storage-address>:9001"
dataRemoteAddr = "tcp://<storage-address>:9002"
bulkRemoteAddr = "tcp://<storage-address>:9003"

Docker Compose File

Relay mode environment variables need to be added to the storage section. In order to match the settings in the above configuration file you would add the following.

  storage:
    environment:
      - NSOLID_COMMAND=storage:8001
      - NSOLID_DATA=storage:8002
      - NSOLID_BULK=storage:8003
      - NSOLID_STORAGE_SOCKETS_COMMAND_REMOTE_ADDR=storage:9001
      - NSOLID_STORAGE_SOCKETS_DATA_REMOTE_ADDR=storage:9002
      - NSOLID_STORAGE_SOCKETS_BULD_REMOTE_ADDR=storage:9003

See the Docker page for more information on setting up Docker Compose.

Advanced Environment Variables

The variables described below should only be necessary if your setup requires you to use a proxy in front of N|Solid Storage.

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

Environment Variable Description
NSOLID_DATA This is the route to your Storage data port. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND. If you do not specify this argument, NSolid will attempt to discover this port from Storage via the COMMAND interface.
NSOLID_BULK This is the route to your Storage bulk port. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND. If you do not specify this argument, NSolid will attempt to discover this port from Storage via the COMMAND interface.
NSOLID_PUBKEY This is Storage's public key, if you have configured a non-default one. If you do not specify a key, the default keypair that ships with NSolid will be used.

Moving the N|Solid Storage server

The data maintained the N|Solid Storage server is stored in a directory determined by the dir property of the [data] section of the configuration file. The default value is ~/.nsolid-storage/data. The contents of the directory can be copied to a new machine, and then the N|Solid Storage server can be run with it's configuration pointing to the copied directory.