Documentation forAppOptics

Configuration (config.yaml)

Overview

SolarWinds Snap Agent's main configuration file is:

  • /opt/SolarWinds/Snap/etc/config.yaml (on Unix)
  • c:\ProgramData\SolarWinds\Snap\config.yaml (On Windows)

The configuration file uses the YAML file format, it is read on agent startup.

NOTE: Updates to configuration file take effect only after restarting the agent.

Configuration options

Log level

The log_level setting controls logging verbosity. Allowed values:

  • trace
  • debug
  • info
  • warning
  • error
  • fatal
  • panic

log_path should point to the directory where log file ("swisnapd.log") should be created. If directory doesn’t exist, snap will log to default directory.

On Linux:

Copy
log_level: warning
log_path: /var/log/SolarWinds/Snap
log_format: text

On Windows:

Copy
log_level: warning
log_path: C:/ProgramData/SolarWinds/Snap/log
log_format: text

Auto-loading

Auto-load mechanism allows starting tasks and plugins on swisnapd startup. Those tasks will be started immediately after service start/restart.

Task auto-loading

task_autoload_path points to the directory containing definitions of tasks that should be started when Snap is executed. Only new (v2) tasks are allowed in this folder. See more in the detailed task file documentation. The task is associated with one or many plugins (binaries) that must be present in plugin_path.

Legacy plugins auto-loading

auto_discover_path relates to the legacy snap mechanism and points to the directory from which system plugins (executables) should always be automatically started.

Additionaly, plugins are started during startup when extension of the corresponding configuration file located in the directory plugins/include is ".yaml" (not ".example"). Tasks files referenced by plugins files need to be present in task_path and binaries in plugin_path.

To check which plugins and tasks have been loaded please refer to command line documentation

Autoload configuration on Linux:

Copy
control:
  auto_discover_path: /opt/SolarWinds/Snap/autoload
  tasks_autoload_path: /opt/SolarWinds/Snap/etc/tasks-autoload.d
  plugin_path: /opt/SolarWinds/Snap/bin
  task_path: /opt/SolarWinds/Snap/etc/tasks.d
  plugins:
    include: /opt/SolarWinds/Snap/etc/plugins.d

Autoload configuration on Windows:

Copy
control:
  auto_discover_path: "C:/Program Files/SolarWinds/Snap/autoload"
  tasks_autoload_path: "C:/ProgramData/SolarWinds/Snap/tasks-autoload.d"
  plugin_path: "C:/Program Files/SolarWinds/Snap/bin"
  task_path: "C:/ProgramData/SolarWinds/Snap/tasks.d"
  plugins:
    include: "C:/ProgramData/SolarWinds/Snap/plugins.d"

Global tags

User can define tags which will be added to every metric or metrics containing specific namespace:

Copy
control:
  tags:
    /:
    environment: production
  /nginx:
    site: mysite.com

Security - Signed plugins

Users can request that only trusted plugins will be executed by snap to avoid potential system hijacking when custom binaries are loaded. In the default installation, each binary plugin is shipped with the associated signature file (".asc" extension). To validate that signature is correct user should switch plugin_trust_level. Allowed values:

  • 0 - no validation (default) - all plugins are allowed to run
  • 1 - enabled - only correctly signed and verified plugins will be run. An attempt to loading a not-signed plugin or plugin with an invalid signature will result in throwing error and preventing such plugin from being executed.
  • 2 - warning - all plugins are allowed to run. An attempt to loading a not-signed plugin or plugin with an invalid signature will result in throwing a warning.

To enable signature validation also keyring_paths have to be provided as a list of folders or/and files. If the folder is provided in the configuration, snap will look for each file with ".gpg", ".pub" or ".pubring" extension. By default, snap installer puts keyrings that can be used - see the detailed plugin trust docs for more. To separate different path/folders use ":" on Linux and ";" on Windows.

Example

Configuration on Linux:

Copy
control:
  plugin_trust_level: 1
  keyring_paths: "/opt/SolarWinds/Snap/bin/.gnupg/swisnap.gpg:/home/MyUser/keyrings"

Configuration on Windows:

Copy
control:
  plugin_trust_level: 1
  keyring_paths: "C:/Program Files/SolarWinds/Snap/.gnupg;C:/ProgramData/MyUser/keyrings"

Security - communication

Snap communicates with plugins via GRPC protocol. By default, communication is not encrypted, but TLS can optionally be enabled by setting tls_cert_path and tls_key_path. When TLS is enabled both sides, snap and plugin, verify their certificates:

  • snap (client) verifies certificate returned by a plugin (server)
  • a plugin (server) verifies certificate returned by snap (client)

Client certificate and its private key used to sign certificate are defined by tls_cert_path and tls_key_path. Analogically, server certificate and its private key are defined by plugin_tls_cert_path and plugin_tls_key_path but in case one of them is empty server certificate and key are set to client ones.

ca_cert_paths setting is used to provide a list of intermediate certificates and/or folders containing intermediate certificates which are used to validate TLS connection by both parties. When empty: the system intermediate certificate list is used.

Example

On linux:

Copy
control:
  tls_cert_path: /tmp/snap-cli.crt
  tls_key_path: /tmp/snap-cli.key
  plugin_tls_cert_path: /tmp/snap-srv.crt
  plugin_tls_key_path: /tmp/snap-srv.key
  ca_cert_paths: /tmp/small-setup-ca.crt:/tmp/medium-setup-ca.crt:/tmp/ca-certs/

On Windows:

Copy
control:
  tls_cert_path: C:/Tmp/snap-cli.crt
  tls_key_path: C:/Tmp/snap-cli.key
  plugin_tls_cert_path: C:/Tmp/snap-srv.crt
  plugin_tls_key_path: C:/Tmp/snap-srv.key
  ca_cert_paths: C:/Tmp/small-setup-ca.crt:/tmp/medium-setup-ca.crt:/tmp/ca-certs/

Rest API

Snap exposes RESTful APIs that allow performing various actions like obtaining a list of running plugins or running new tasks. Full list of allowed operations is documented in the REST API docs. REST configuration consists of following options:

  • addr (default: 127.0.0.1) - string representing address on which REST API will be available,
  • port (default: 21413) - port on which REST API will be available,
  • enable (default: true) - bool value indicating if REST server should be started. Disabling this option will cause dysfunction of Swisnap Command-line.
  • https (default: false) - use secure HTTP,
  • rest_auth: (default: false) - force authentication when connecting with REST API,
  • rest_auth_password - password that should be required to connect with REST API (in the form of basic authentication),
  • rest_certificate - path to REST server certificate,
  • rest_key - path to private key used by REST server.

Example

On Linux:

Copy
restapi:
  addr: 127.0.0.1
  port: 21413
  enable: true
  https: true
  rest_auth: true
  rest_auth_password: pa$$word1
  rest_certificate: /tmp/rest_srv.crt
  rest_key: /tmp/rest_srv.key

On Windows:

Copy
restapi:
  addr: 127.0.0.1
  port: 21413
  enable: true
  https: true
  rest_auth: true
  rest_auth_password: pa$$word1
  rest_certificate: C:/tmp/rest_srv.crt
  rest_key: C:/tmp/rest_srv.key

Other options

Other options available:

  • plugin_load_timeout (ie. 30s) - the maximum time allowed for the plugin binary to start and establish communication with snap. When exceeded, snap will return an error.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.