Documentation forAppOptics

Installation - Linux

Easy Installation

To find the easy installation guide, go to AppOptics home page and click on the "Add Host" button. It will show you these steps to install the SolarWinds Snap Agent via our install wrapper script:

  1. Download install wrapper script from https://files.solarwinds.cloud/solarwinds-snap-agent-installer.sh:

    Copy
    curl -sSO https://files.solarwinds.cloud/solarwinds-snap-agent-installer.sh
  2. Run install wrapper script, passing in the API token with the --token option.

    Copy
    sudo bash solarwinds-snap-agent-installer.sh --token <your api token> [--yes] [--debug]
  3. The easy install walk through will include the API token. If you want to create your own token, follow the instructions described in API Tokens and Token Roles.

    The metrics API token can also be set via the SOLARWINDS_TOKEN environment variable:

    Copy
    export SOLARWINDS_TOKEN=<your api token>
    sudo -E bash solarwinds-snap-agent-installer.sh [--yes] [--debug]

More information about different options provided by installer script can be found using the --help option. To troubleshoot issues during installation --debug option can be used.

For manual installation without install script follow Advanced Installation

Installation with log monitoring

The SolarWinds Snap Agent installer includes a –detect-logs option. When this option is used, a basic configuration that detects standard logs on the system is enabled on Linux hosts. To enable custom log monitoring options, see Logs Collector/Forwarder.

  1. Call the installation script the option –detect-logs

    Copy
    sudo bash solarwinds-snap-agent-installer.sh --token <your api token> --detect-logs [--yes] [--debug]
    • To use a Loggly token that differs from your AppOptics token, use the option --loggly-token, followed by your Loggly token:

      Copy
      sudo bash solarwinds-snap-agent-installer.sh --token <your api token> --detect-logs --loggly-token <your loggly token> [--yes] [--debug]

      After the script completes, the API token is stored in the logs publishers configuration file /opt/SolarWinds/Snap/etc/plugins.d/publisher-logs.yaml

    • Configuration for the PaperTrail syslog publisher (port based) is done by updating configuration file. See Logs Collector/Forwarder to find more detailed information about PaperTrail syslog publisher settings.

  2. If the --detect-logs --yes option was not used when calling the installation script, you will be asked whether found logs should be monitored. Options are:

    • Yes: basic configuration is enabled that detects standard logs on the system
    • No: any existing configuration with detected logs will be stored in example file: /opt/SolarWinds/Snap/etc/tasks-autoload.d/task-logs-files.yaml.example.new and Snap Agent will not start monitoring logs.
  3. Define what logs you would like to monitor.

    • Enter the full path to each log you want to monitor under config: > file_paths in the /opt/SolarWinds/Snap/etc/task-autoload.d/task-logs-files.yaml file on your server
    • For more details about the configuration file, see Logs Collector/Forwarder.

    After installation log plugin will be started.

  4. Grant the solarwinds user permissions to the log files. In order to read the log files and report on its content, the user solarwinds must have read permission. It is recommended that you do one of the following to grant permissions:

    • Make sure that the adm group has access to the log files. The solarwinds user is a member of the adm user group, which is designed for accessing logs.
    • Add the solarwinds user to another user group that has access to the log files

    If the files were already added to the /opt/SolarWinds/Snap/etc/task-autoload.d/task-logs-files.yaml before setting the correct permissions on the directory and files, restart the swisnapd service:

    Copy
    sudo service swisnapd restart

Installation with TLS encrypted REST API

To enable encrypted REST API user has to pass --secure option to installation script:

Copy
sudo bash solarwinds-snap-agent-installer.sh [--yes] [--debug] --token <your api token> --secure

Installer will ask for REST authentication password and paths to REST certificate and key - solarwinds user has to have read access to both certificate and key.

REST Certificate should be signed by trusted CA (it has to be stored in system's keychain).

User now has three options of running Snap's CLI:

  • Environment variables:

    Copy
    export SNAP_REST_PASSWORD=true
    export SNAP_URL=https://<listen_address>:<listen_port>
    # then, each swisnap call will ask for API password.
    swisnap plugin list
  • CLI flags:

    Copy
    swisnap --password --url https://<listen_address>:<listen_port> plugin list
  • Mix of config and environment variable:

    Copy
    cat > swisnap-config.json <<EOF
    {
      "rest": {
        "rest-auth-pwd": "mypassword"
      }
    }
    EOF

    export SNAP_URL=https://<listen_address>:<listen_port>
    swisnap --config swisnap-config.json plugin list

Installation with TLS encrypted communication between Snaps and its plugins

To enable encrypted communication between Snap and its plugins, the user has to:

  • set --secure flag
  • either provide copy of previously generated CA certificate and certificate-key pairs for Snap and plugins, or let the installer script generate them.

If user chooses to generate keys and certificates, then it is required to provide passphrases to each of the key.

Passing previously generated certificates:

Copy
sudo bash solarwinds-snap-agent-installer.sh [--debug] --token <your api token> [--yes] --secure --ca-path /path/to/ca.crt --plugin-cert-path /path/to/plugin.crt --plugin-key-path /path/to/plugin.pem --snap-cert-path /path/to/snap.crt --snap-key-path /path/to/snap.pem

Letting script generate required files:

Copy
sudo bash solarwinds-snap-agent-installer.sh [--debug] --token <your api token> [--yes] --secure --ca-passphrase <capassphrase> --plugin-passphrase <pluginpassphrase> --snap-passphrase <snappassphrase>

If user omits optional [--yes] flag, then the script will ask for confirmation before generating each certificate.

Generated certificates, sign requests and keys are stored in /tmp/SolarWinds/Snap/ directory.

Autoload plugins will use certificate and key specified by --plugin-cert-path and --plugin-key-path

Upgrade

Follow these steps to upgrade the agent:

For deb based platforms:

Copy
sudo apt-get install solarwinds-snap-agent

For rpm based platforms:

Copy
sudo yum update solarwinds-snap-agent

If you've made local changes to /opt/SolarWinds/Snap/etc/config.yaml or default task files under /opt/SolarWinds/Snap/etc/tasks.d, the package manager should preserve those changes either by default or with an optional setting, please refer to your package manager manual for details.

Logrotate

SolarWinds Snap Agent package by default contains logrotate configuration file /opt/SolarWinds/Snap/etc/logrotate.d/solarwinds-snap-agent for rotating /var/log/SolarWinds/Snap/swisnapd.log. The logrotate configuration file is automatically linked to /etc/logrotate.d/ folder during agent installation if logrotate is present on the system. If logrotate is not installed while installing agent, you will need to link logrotate configuration file manually.

Advanced Installation

Follow these steps to manually install the agent, by setting up the required repository and running your system's package management commands:

  1. Set up the repository using the appropriate deb or rpm instructions

  2. Set the metrics API token using the SOLARWINDS_TOKEN environment variable

    Copy
    export SOLARWINDS_TOKEN=<your api token>

    Optionally, to not start the agent at the end of installation, set the AGENT_INSTALL_ONLY environment variable to 1:

    Copy
    export AGENT_INSTALL_ONLY=1
  3. Install the agent package

    For deb based platforms:

    Copy
    sudo -E apt-get install solarwinds-snap-agent

    For rpm based platforms:

    Copy
    sudo -E yum install solarwinds-snap-agent

Troubleshooting

To learn more about how to restart the SolarWinds Snap Agent, where its log file is located, and other common troubleshooting techniques, please check the Troubleshooting page.

Uninstalling the Agent

For deb based systems:

Copy
sudo apt-get remove solarwinds-snap-agent

Configuration files will remain on deb based system after uninstalling the Snap Agent. Do not remove these manually. To remove all configuration files from your system after uninstalling the Snap Agent, run the following command:

sudo apt-get remove --purge solarwinds-snap-agent

for RPM based systems:

Copy
sudo yum erase solarwinds-snap-agent

Uninstall Script:

Copy
sudo bash /opt/SolarWinds/Snap/support/before-remove.sh
sudo bash /opt/SolarWinds/Snap/support/after-remove.sh

The SolarWinds Snap Agent will be automatically removed from the Infrastructure Host view after 60 minutes.

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.