Abiquo Events Catcher

The Abiquo Events Catcher (eventscatcher) lets you run commands when Abiquo generates a new event of a specific type. So, for example, you can send an email when a user logs in.

To obtain the Abiquo Events Catcher app, please contact Abiquo Customer Service

You can use the API to find out the current event types with this method: EventsResource.html#list-events-types. And the Abiquo wiki lists Events in the Events table.

Usage

 --api-endpoint (-ae) VAL     : Abiquo API URL to connect
 --api-password (-ap) VAL     : Abiquo API password
 --api-username (-au) VAL     : Abiquo API username
 --api-version (-av) VAL      : Override Abiquo version on API requests (default: current version)
 --database-file (-df) VAL    : Event-catcher Database file (default: ./catcherdb)
 --fetch-interval (-fi) N     : Fetch interval in minutes (default: 10)
 --first-fetch-delay (-ffd) N : Delay of first event fetch in minutes (default: 0)
 --first-fetch-range (-ffr) N : First fetch range in minutes (default: 60)
 --receivers-file (-rf) VAL   : Receivers INI file (default: ./receivers.ini)

How to configure catchers

By default, eventscatcher will try to read the receivers.ini file in the current working directory (CWD). The following is a sample file.

[example-catch-1]
actions=TAGS_SYNC, LOGIN
command=echo.sh

[example-cath-2]
actions=LOGIN
command=sendemail.sh

Note that you can add as many catchers as you like.

Each command will be run by eventscatcher with the following arguments:

First argument is the complete event JSON (https://wiki.abiquo.com/api/latest/event.html)
Second argument is the JSON of the entity related to the event. This can be empty.

> sh echo.sh "event_json" "entity_json"

Deployment

Create the working folder at /opt/abiquo/eventscatcher that contains the following.

The app: eventscatcher.jar
The receivers config file: receivers.ini
The bash scripts for the commands: such as echo.sh, sendemail.sh, or your own scripts)

Add a new service to systemd to run eventscatcher.

To create a new file called /etc/systemd/system/eventscatcher.service:

You will need to:

Set the actual username after User= (make sure that the user has permissions to work in the /opt/abiquo/eventscatcher folder)
Set the proper app args after --api-endpoint, --api-username and --api-password
Set the correct java binary after ExecStart

Then run the following commands.

systemctl start eventscatcher.service to start the service
systemctl status eventscatcher.service to check the status
systemctl enable eventscatcher.service to start service on boot

Logging

There are two logs the current working directory:

The app’s general log, which is named eventscatcher.log
The command running log, which is named eventscatcher-executions.log