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.

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:

    [Unit]
    Description=Abiquo eventscatcher systemd service
    After=network.target

    [Service]
    Type=simple
    User=tomcat
    WorkingDirectory=/opt/abiquo/eventscatcher
    ExecStart=/bin/java -jar /opt/abiquo/eventscatcher/eventscatcher.jar --api-endpoint {api.endpoint} --api-username {api.username} --api-password {api.password}

    [Install]
    WantedBy=multi-user.target

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