BigPanda Agent

The utility is installed on the main server where the monitoring data can be accessed. The agent can then be configured to capture the necessary data from its respective location and push it to BigPanda for normalization into a BigPanda Alert. Native configuration commands exist for some popular monitoring systems like Nagios, Zenoss, and Zabbix.

You can install the BigPanda agent on any of the following OS versions:

OS	Version(s)
RHEL	7, 8, and 9
CentOS	7 and Stream
Debian	9 (Stretch), 10 (Buster), and 11 (Bullseye)
Ubuntu	16.04 (Xenial), 18.04 (Bionic), 20.04 (Focal), and 22.04 (Jammy)

Python compatibility

To use the Open Integration Manager for Agent-based integrations, Python version>= 3.8.0 and an Agent version >= 10.2 are required.

Upgraded installation for agent version 10.4.0 and above

The BigPanda agent has been upgraded for improved stability and system security. Agent versions 10.4.0 and up are installed using a virtual environment.

Key Features

Sends monitoring data from on-prem solutions to the BigPanda Console
Works with multiple integrations
Built-in alert throttling
Configurable event logging

Available Configuration Options

The generic BigPanda agent is available for configuration on the below systems:

Integrations that Require the BigPanda Agent

The following integrations leverage the BigPanda Agent:

See the specific integration instructions for details on installation and configuration.

Throttling

To help balance alert load on the BigPanda servers, the agent has a built-in throttling mechanism.

Configured globally, throttling is performed on a per-Agent plugin level. This means that if your BigPanda Agent has plugins configured for both Nagios and Raw Alerts, each plugin will be separately throttled.

Property	Type	Description / Default
`throttle_count`	integer	(Default: 2000) This is the maximum number of alerts to send out per plugin per `throttle_interval`
`throttle_interval`	integer	(in seconds -- Default: 60) This interval resets the `throttle_count` once its value elapses. E.G. If 3000 alerts are passed in the first 10 seconds, there will be a pause for the remaining 50 seconds for that plugin.

Property

Type

Description / Default

throttle_count

integer

(Default: 2000) This is the maximum number of alerts to send out per plugin per throttle_interval

throttle_interval

integer

(in seconds -- Default: 60) This interval resets the throttle_count once its value elapses.

E.G. If 3000 alerts are passed in the first 10 seconds, there will be a pause for the remaining 50 seconds for that plugin.

To override these settings, add these two properties to the backend property object in /etc/bigpanda/bigpanda.conf. Be sure to restart the agent.

{
  "root": {
    "agent_id": "0000000-4444-333-222-11111111",
    "version": "5.11.0",
    "plugins": [
			
    ],
    "data_encoding": "utf-8",
    "backend": {
      "verify_certificate": true,
      "address": "https://api.bigpanda.io",
      "timeout": 30,
      "api_token": "12345678901234567890",
      "throttle_count": 4000,
      "throttle_interval": 80
    }
  }
}

Logging

The BigPanda Agent is designed to log events into a file for visibility. This logging has default configurations that can be updated to the desired specifications.

The agent provides the option to

Configure logging options through a single file
Change the level of logging the agent performs
Change the destination of the logs

To learn more about configuring log files in the BigPanda Agent, see the Configure the BigPanda Agent Log documentation.

The BigPanda Agent Raw Alerts Plugin

The Raw Alerts plugin works similarly to the REST API integration. Alert JSON files are generated by a source and queued up in a directory to be consumed by the plugin.

Use the Plugin

This plugin is used in conjunction with specific source systems (like our SNMPD agent). It can also be initialized and used with any other source.

Go to the BigPanda console in the Integrations tab.
Select the REST API Integration. Name the Integration and generate an App Key.
Run the following command in the command line: $ sudo bigpanda-config --add rawalertstransfer --app-key <GENERATED APP KEY>

Test the Plugin

To test the new plugin, you can add a JSON file to the following directory. /var/lib/bigpanda/queue/

Follow the guidelines to a valid alert payload when writing to the directory. Payload property options can be found in the Alerts API.

Multiple App Key Support

By default, the plugin will use the app_key provided during plugin initialization.

It is possible to override this app_key to use a different integration's key by including the app_key in the JSON file, as presented in the example below.

{
  "app_key": "48275f111111111111cafdca981",
  "status": "critical",
  "host": "host_test",
  "category": "testing",
  "description": "This is an example"
}

Update the BigPanda Agent

You can upgrade the BigPanda Agent to access the features and fixes available in a newer version.

Process

Stop the BigPanda agent by running the following command.
```
sudo service bigpanda stop
```

Upgrade the agent by running one of the following commands, depending on your OS.

For RedHat / CentOS:

sudo yum update 
sudo yum list --showduplicates bigpanda-agent | expand 
sudo yum install bigpanda-agent-

For Debian / Ubuntu:

sudo apt update 
sudo apt install bigpanda-agent

Make sure that the BigPanda Agent has started by running the following command.
```
sudo service bigpanda start
```
Verify the BigPanda Agent is loaded by running the following command.
```
sudo systemctl status bigpanda
```
Verify that the Agent version has been upgraded by running the following command.
```
sudo grep version /etc/bigpanda/bigpanda.conf
```

Migrate the BigPanda Agent to v10.x or Higher

The BigPanda Agent has been updated to route alert traffic to the Open Integration Manager. Use the steps below to update from a v9.x release to a v10.x release.

Minimum Versions

To use the Open Integration Manager for Agent-based integrations, Python version >= 3.8.0 and an Agent version >= 10.2 are required.

For RHEL 7/8 based OS, Python version 3.8 is required to run the Agent version >= 10.2, and is installed during the migration process. For RHEL 9, the system version of Python 3.9 is used.

Prepare to Migrate the Agent

Before migrating the Agent, take the following steps:

Ensure a backup has been made of the agent config file. This will serve as a copy should you need to roll back the upgrade.
```
sudo cp /etc/bigpanda/agent/bigpanda.conf /etc/bigpanda/agent/bigpanda.conf.tmp
```
Ensure the user doing the upgrade has been added to the sudoers list. Do not upgrade from the root account.

If there are multiple versions of python3 installed, install a python3 alternative to use Python 3.8 or later.

For RedHat / CentOS:

sudo alternatives --install /usr/bin/python3 python3 $(which python3.8) 1

For Debian / Ubuntu:

sudo update-alternatives --install /usr/bin/python3 python3 $(which python3.8) 1

Migration Process

The migration should happen seamlessly during the update process. Once the new version is installed, review the agent config file to ensure the new information is accurate.

v10.x config example

{
  "root": {
    "version": "10.2.0",
    "agent_id": "<agent_id>",
    "data_encoding": "utf-8",
    "backend": {
      "alert_address": "https://integrations.bigpanda.io",
      "backend_address": "https://api.bigpanda.io",
      "api_token": "<api_token>",
      "timeout": 30,
      "verify_certificate": true
    },
    "plugins": [
      {
        "name": "agent/heartbeat",
        "endpoint": "/agents/<agent_id>/heartbeat",
        "action": "POST",
        "config": {
          "interval": 60
        }
      },
      {
        "name": "rawalertstransfer",
        "app_key": "<app_key>",
        "action": "POST",
        "endpoint": "/oim/api/alerts",
        "batch_size": 500,
        "enabled": true,
        "config": {
          "queue_directory": "/var/lib/bigpanda/queue",
          "dlq_directory": "/var/lib/bigpanda/dlq",
          "app_key": "<app_key>"
        }
      }
    ]
  }
}

The following fields were updated in the v10.x config:

alert_address has been added and should point to the Open Integration Manager.
backend_address has been added, replacing address, and should point to the BigPanda API backend URL.
The endpoint for each plugin has been updated to point to the /oim/api/alerts endpoint as needed.

Using Alternative Python Versions

The BigPanda Agent version 10.x and later requires Python version >= 3.8. The BigPanda Agent installer sideloads Python 3.8 as a Python alternative. This will install the bigpanda module and all Python packages in /usr/lib/python3.8/site-packages/.

To use an alternative version of python3, follow the guide below to install the Agent dependencies in the correct location.

Alternate loading for Python 3.9 as an example:

Switch the alternative Python version back to 3.9.

sudo alternatives --config python3

There are 3 programs which provide 'python3'.

  Selection    Command
-----------------------------------------------
*  1           /usr/bin/python3.6
   2           /usr/bin/python3.9
 + 3           /usr/bin/python3.8

Enter to keep the current selection[+], or type selection number: 2

Validate the version of Python was switched to Python 3.9.
```
python3 --version
```
Ensure the package requirements are installed in /usr/lib/python3.9/site-packages/. Site locations can be verified with python3 -m site.
```
python3 -m pip install -r /etc/bigpanda/agent/requirements.txt
```

Copy the bigpanda python module to the new /lib location.

sudo cp -R /usr/lib/python3.8/site-packages/bigpanda/ /usr/lib/python3.9/site-packages/

Once all of the packages are installed in the Python 3.9 /site-packages directory, you can start the bigpanda agent as normal.Once all of the packages are installed in the Python 3.9 /site-packages directory, you can start the bigpanda agent as normal.

Start the BigPanda Agent

Once the BigPanda Agent config has been verified as accurate, you can start the BigPanda agent.

sudo service bigpanda start

Make sure to verify that the agent has started correctly and is receiving heartbeat responses from BigPanda.

tail -50 /var/log/bigpanda/agent.log

FAQs

Where can I find the agent log files?

By default, the log files are located at /var/log/bigpanda/. BigPanda log files are rotated when they reach 10MB and only 3 versions are stored at any given time. To change these settings, see Configure the BigPanda Agent Logs.

Is the BigPanda agent secure?

Yes, we’ve designed the agent to be secure and non-intrusive. The installer uses signed deb/rpm packages. The agent itself runs as a custom non-root user and it communicates with BigPanda via SSL.

How do I uninstall the agent?

See Uninstall the BigPanda Agent.

How do I install multiple BigPanda agents?

In most cases, you need only one agent per master server of your integration. If you have multiple masters, you need to create a separate integration, using different app keys, for each master.

What happens if my internet connection is down?

BigPanda does not miss alerts, even if your connection is down. The BigPanda agent intelligently retries sending your alerts, until it’s successful. Once the connection is revived, you will see the events in BigPanda.

Can I run the agent behind a proxy server?

Yes, see the documentation for configuring the BigPanda Agent behind a proxy server.

Can I use the agent to communicate with a monitoring server behind my DMZ?

Yes, see the documentation for Configuring the BigPanda Agent with a DMZ.

Can I use the same agent on multiple integrations?

No, each agent is assigned a unique "agent_id" value (found in the /etc/bigpanda/bigpanda.config file) and can only support one integration.

Next Steps

Learn how to Install the BigPanda Agent for RedHat or CentOS, Debian or Ubuntu, or Docker.

Learn how to Configure the BigPanda Agent Log

Learn how to Integrate with BigPanda

In this section: