Traditional Installer

Install the Spyderbat Event Forwarder on Linux using the traditional installer.

Before installing the Event Forwarder, enable SIEM forwarding on at least one saved query in the console. Without this step, the forwarder polls the API and receives nothing. See SIEM Forwarding.

The traditional installer sets up the Event Forwarder as a systemd service on Linux. It creates the sbevents system user, installs the binary to /opt/spyderbat-events/, and registers the service. Supports x86_64 and arm64.

Run only one Event Forwarder instance per organization. Multiple instances each receive the full event stream independently and will cause duplicate events in your SIEM.

Prerequisites

• A Linux host with systemd (VM, bare metal, or EC2)

• Spyderbat Nano Agents deployed on the hosts you want to monitor

• Your org UID and a Spyderbat API key (see API Key Setup)

• SIEM forwarding enabled on at least one saved query (see SIEM Forwarding)

• At least 512 MB of available memory and 1 CPU core if running alongside other services

Install

1. Download the latest release from github.com/spyderbat/event-forwarder/releases.

2. Unpack the tarball:

   mkdir /tmp/sef
   tar xfz spyderbat-event-forwarder.*.tgz -C /tmp/sef

3. Run the installer:

   cd /tmp/sef
   sudo ./install.sh

   The installer prints the config file location and the commands to start the service:

   spyderbat-event-forwarder is installed!
   
   Please edit the config file now:
       /opt/spyderbat-events/etc/config.yaml
   
   To start the service, run:
       sudo systemctl start spyderbat-event-forwarder.service
   
   To view the service status, run:
       sudo journalctl -fu spyderbat-event-forwarder.service

4. Edit the config file:

   sudo vi /opt/spyderbat-events/etc/config.yaml

   Minimal configuration (required fields only):

   spyderbat_org_uid: YOUR-ORG-UID
   spyderbat_secret_api_key: YOUR-API-KEY
   
   # Non-US / non-default deployments only: hostname only, no scheme
   # api_host: api.example.spyderbat.com

   The api_host field is only needed if you are not using the default US deployment (api.prod.spyderbat.com). The value must be a hostname without a scheme — api.example.com is correct; https://api.example.com will cause a startup error.

   With webhook output (for Panther, Splunk HEC, or any HTTP endpoint):

   spyderbat_org_uid: YOUR-ORG-UID
   spyderbat_secret_api_key: YOUR-API-KEY
   
   webhook:
     endpoint_url: https://your-siem/ingest
     compression_algo: zstd
     max_payload_bytes: 1048576
     authentication:
       method: bearer
       parameters:
         secret_key: YOUR-BASE64-ENCODED-SECRET

   For architecture details, see Spyderbat Event Forwarder.

5. Start the service:

   sudo systemctl start spyderbat-event-forwarder.service

6. Verify the service is enabled to start at boot (the installer does this automatically):

   sudo systemctl is-enabled spyderbat-event-forwarder.service

   This should print enabled.

Verify the installation

Tail the service logs to confirm the forwarder started and is receiving events:

sudo journalctl -fu spyderbat-event-forwarder.service

The forwarder logs status as JSON. Look for lines where the "message" field reports new record counts, for example:

{"schema":"event_forwarder:meta:1.0.0","message":"5 new records (0 invalid, 5 logged)",...}

You can also tail the event output file directly for human-readable ndjson events:

sudo tail -f /opt/spyderbat-events/var/log/spyderbat_events.log

For detailed verification steps and troubleshooting, see Event Forwarder validation.

Troubleshooting: service fails to start (crash loop)

If the forwarder crashes repeatedly on startup, check the logs for a DNS or URL error:

sudo journalctl -u spyderbat-event-forwarder.service --no-pager -n 20

A common cause is an incorrect api_host value. The field requires a hostname only — no scheme:

• Correct: api_host: api.example.spyderbat.com

• Incorrect: api_host: https://api.example.spyderbat.com

After fixing the config, clear the failed service state before restarting:

sudo systemctl reset-failed spyderbat-event-forwarder.service
sudo systemctl start spyderbat-event-forwarder.service

Forward events to Splunk with the Universal Forwarder

If you use the Splunk Universal Forwarder, point it at the event output file:

sudo splunk add monitor /opt/spyderbat-events/var/log/spyderbat_events.log

Related pages

• SIEM Forwarding — control plane setup

• Spyderbat Event Forwarder — architecture overview

• SIEM Forwarding Quickstart — end-to-end setup guide

• Panther Webhook Configuration — webhook setup example