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.

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:

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

On Windows:

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:

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:

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:

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 - all plugins are allowed to run
  • 1 - enabled (default) - only correctly signed and verified plugins will be run. An attempt to load an unsigned plugin or a plugin with an invalid signature will throw an error and the plugin will not be executed.
  • 2 - warning - all plugins are allowed to run. An attempt to loading an unsigned plugin or a plugin with an invalid signature will throw a warning.

To enable signature validation, 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, the snap installer puts keyrings that can be used - see the detailed plugin trust docs for more. To differentiate between separate folder or file paths, use ":" on Linux and ";" on Windows.

Example

Configuration on Linux:

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

Configuration on Windows:

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:

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:

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: unix:///var/run/swisnapd.sock on Linux and npipe:////./pipe/swisnapd on Windows) - string representing address on which REST API will be available.
  • enable (default: true) - boolean value indicating if REST server should be started. Disabling this option will interfere with the Swisnap Command-line.
  • https (default: false) - use secure HTTP.
  • rest_auth: (default: false) - force authentication when connecting with the REST API.
  • rest_auth_password - password that should be required to connect with the REST API (in the form of basic authentication).
  • rest_certificate - path to the REST server certificate.
  • rest_key - path to the private key used by REST server.

Example

On Linux:

restapi:
  addr: unix:///var/run/swisnapd.sock
  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:

restapi:
  addr: npipe:////./pipe/swisnapd
  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.

  • library_path - path or list of paths containing .so/.dll dependencies for plugins based on cgo bindings (typically v2 plugins written in C# or python). When set, the provided paths are appended to LD_LIBRARY_PATH (on linux) or PATH (on windows) environment variables during SWISnap service startup.

Navigation Notice: When the APM Integrated Experience is enabled, AppOptics shares a common navigation and enhanced feature set with other integrated experience products. How you navigate AppOptics and access its features may vary from these instructions.

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.