On-Prem Event Collector

Supported Versions	Type	Authentication Type
Linux. See Supported platforms.	On-prem agent	BigPanda API token, plus an ingest token for your tools

The On-Prem Event Collector collects events from tools on your network and forwards them to BigPanda through the Open Integration Manager (OIM). It runs as a single binary under systemd and buffers every event on local disk before delivery. If BigPanda is unreachable, events wait in the buffer and deliver when the connection returns.

Limited availability

The On-Prem Event Collector is available to design partners only. Contact your BigPanda account team for access. [VERIFY]

Linux only

Version 1.0 supports Linux hosts only. macOS and Windows binaries are published, but the service can't be installed on them yet.

Key features

Four ingestion paths: JSON push, scheduled pull from a tool's API or a local command, SNMP trap forwarding, and Tivoli EIF.
Durable buffer: Events are written to a bounded write-ahead log on disk before delivery, with retry and backoff.
Rules-based routing: Send each event to a different OIM integration based on its field values.
Dry-run testing: The test command shows exactly what the agent would send, without sending it.
Built-in monitoring: A local health endpoint and Prometheus metrics.

How events reach BigPanda

Path	How events arrive	Opt-in setting
JSON push	Your tool sends a JSON POST to the agent	`listen` (always on)
Source pull	The agent polls your tool on an interval	`sources:` block
SNMP forward	The agent captures raw SNMP traps and forwards them for cloud-side processing	`snmp:` block
Tivoli EIF	The agent accepts IBM Tivoli EIF events over TCP	`eif:` block

Every path shares the same buffer and delivery. Events are batched and sent to OIM as a JSON array.

Supported platforms

Version 1.0 runs on Linux with systemd.

Support level	Platforms
Tested on a real host	Ubuntu 24.04, Rocky 9
Tested in containers	Ubuntu 20.04 and 22.04, Debian 12 and 13
Packaged, untested	Ubuntu 18.04, Debian 11, RHEL, AlmaLinux and CentOS 7 to 9, Rocky 8, Amazon Linux 2 and 2023, and other Debian or RHEL derivatives

Debian 12 and 13 need version 1.0.1 or later.

Before you start

Item	Where to find it
A Linux host that can reach your tools and BigPanda	Your infrastructure team
An OIM integration and its app key	The integration page in BigPanda [VERIFY-LINK]
A BigPanda API token	[VERIFY] Where does the customer find the API token used by `--token`?
Outbound HTTPS from the host to `integrations.bigpanda.io`	Your network team

Enable array payloads on the OIM integration

The agent sends events in batches, as a JSON array. Enable array payloads on the OIM integration before you start the agent. Without that setting, OIM accepts the request but the alerts arrive with keys such as 0_host and fail validation. [VERIFY] Exact name and location of the array payload setting in OIM.

Install the agent

Run the install script on the host. It detects the OS and architecture, verifies the download, and installs the bigpanda-forager package, which is the On-Prem Event Collector.

Run the install script.

curl -fsSL https://bigpandaio.jfrog.io/artifactory/int-archive/bigpanda-forager/install.sh | sudo sh

Confirm the installed version.
```
bigpanda-forager --version
```

The install script takes three optional flags:

Flag	Effect
`--dry-run`	Shows what the script would do, without installing anything
`--version <version>`	Installs that version instead of the latest
`--yes`	Upgrades or downgrades an installed agent without asking

Pass a flag after sh -s --, for example curl -fsSL <install_url> | sudo sh -s -- --version <version>.

Migrating from the legacy BigPanda agent

From version 1.0.1, the On-Prem Event Collector installs on the same host as the legacy bigpanda-agent package. It doesn't read the legacy agent's configuration. To remove the legacy agent, run sudo apt remove bigpanda-agent or sudo yum remove bigpanda-agent.

Install with a package manager

If a configuration management tool (Ansible, Puppet, Chef) installs packages on your hosts, add the BigPanda repository and install bigpanda-forager by name.

Debian or Ubuntu:

curl -fsSL https://bigpandaio.jfrog.io/artifactory/api/security/keypair/bigpanda/public \
  | sudo gpg --dearmor -o /usr/share/keyrings/bigpanda.gpg
echo "deb [signed-by=/usr/share/keyrings/bigpanda.gpg] https://bigpandaio.jfrog.io/artifactory/int-deb $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/bigpanda.list
sudo apt update
sudo apt install bigpanda-forager

RHEL or Rocky:

sudo tee /etc/yum.repos.d/bigpanda.repo <<'REPO'
[bigpanda]
name=BigPanda
baseurl=https://bigpandaio.jfrog.io/artifactory/int-rpm/bigpanda/agents
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://bigpandaio.jfrog.io/artifactory/api/security/keypair/bigpanda/public
REPO
sudo yum install bigpanda-forager

Install on an air-gapped host

Download the package and its checksum manifest on a connected machine, then copy both to the host.

Download the checksum manifest.

curl -fsSLO "https://bigpandaio.jfrog.io/artifactory/int-archive/bigpanda-forager/<version>/checksums.txt"

Download the package for the host's OS.
- Debian or Ubuntu: https://bigpandaio.jfrog.io/artifactory/int-deb/pool/bigpanda-forager_<version>-1_amd64.deb
- RHEL or Rocky: https://bigpandaio.jfrog.io/artifactory/int-rpm/bigpanda/agents/bigpanda-forager-<version>-1.x86_64.rpm

Verify the package against the manifest.

sha256sum -c checksums.txt --ignore-missing

Install the package with sudo dpkg -i <package>.deb or sudo rpm -i <package>.rpm.

Prefer the repository install

The direct download is verified over TLS only, with no detached signature. The repository install checks signed metadata on every install and upgrade.

Verify the signing key

The repository install trusts the BigPanda public key. Pin its fingerprint before you rely on it.

curl -fsSL https://bigpandaio.jfrog.io/artifactory/api/security/keypair/bigpanda/public \
  | gpg --homedir "$(mktemp -d)" --with-colons --import-options show-only --dry-run --import - \
  | awk -F: '$1 == "fpr" { print $10; exit }'

The output must be 0BA5103DC11AE76C7838D7F055D011BC24E10FB7. No output means the check failed. Don't trust the key.

Set up and start the agent

The package registers the service but installs no configuration. Three commands get the agent running.

Write the configuration file.
```
sudo bigpanda-forager init --token <api_token> --app-key <app_key>
```
- init writes /etc/bigpanda/forager/forager.yaml and won't overwrite an existing file without --force.
- Without --ingest-token, init generates one and prints it once. Save it: your tools need it to send events.
Check the host and configuration.
```
sudo bigpanda-forager doctor
```
doctor checks the configuration, the ports, OIM reachability, and directory permissions. It changes nothing.
Start the service.
```
sudo bigpanda-forager start
```

Run doctor before start

On a running agent, the two port checks fail because the agent itself holds the ports.

Send a test event

Send one event to confirm the agent accepts it.

curl -i -XPOST http://localhost:8080/ \
  -H 'Authorization: Bearer <ingest_token>' \
  -H 'Content-Type: application/json' \
  -d '{"host":"web01","check":"cpu","status":"critical","description":"CPU above 90%"}'

A 202 Accepted response means the event is buffered on disk. It isn't delivered yet. Check the OIM integration in BigPanda for the alert.

Manage the service

Command	Effect
`sudo bigpanda-forager start`	Starts the service
`sudo bigpanda-forager stop`	Stops the service
`sudo bigpanda-forager status`	Shows the service status
`sudo bigpanda-forager run`	Runs the agent in the foreground, as the service manager does
`sudo bigpanda-forager uninstall`	Unregisters the service

sudo systemctl restart bigpanda-forager also restarts the agent.

Upgrade the agent

Upgrade with apt or yum, or re-run the install script. A package upgrade keeps the service registered and restarts it if it was running. The install script never upgrades without asking; pass --yes to upgrade from automation.

Upgrading from v0.0.5

The first upgrade from v0.0.5 leaves the agent stopped. Start it with sudo bigpanda-forager start on Debian or Ubuntu, or sudo bigpanda-forager install && sudo bigpanda-forager start on RHEL or Rocky.

Remove the agent

Stop the tools that send events to the agent.
Remove the package with sudo apt remove bigpanda-forager or sudo yum remove bigpanda-forager.
To remove all data, delete /etc/bigpanda/forager/, /var/lib/bigpanda-forager, /var/log/bigpanda-forager, and /var/run/bigpanda-forager, then run sudo userdel bigpanda.

Buffered events are lost

Removing /var/lib/bigpanda-forager deletes any events still waiting in the buffer. Check that buffer_pending on the health endpoint reads 0 first.

Removing the package keeps the configuration and data, so a reinstall picks up where it left off. [STUB] Add the standard OIM integration deletion steps and the data-removal and auto-resolution callouts.

Next steps

Configure the On-Prem Event Collector [VERIFY-LINK]
Normalize and route events with the On-Prem Event Collector [VERIFY-LINK]
Test events with the On-Prem Event Collector [VERIFY-LINK]
Monitor the On-Prem Event Collector [VERIFY-LINK]

In this section: