Table Of Contents

Previous topic

Introduction

Next topic

Installing the Universal Probe

Getting Started Using the Universal Probe

This quick start guide will explain the basics on how to install, configure and run UP. More detail is provided in subsequent sections of this document.

Installing UP

The Universal Probe (UP) is distributed as a tar archive, one for each supported platform. Basic installation is very simple, just ensure you have the correct tar archive for your platform and then execute:

$ tar -xzof up_donbot.1_x86-ubuntu10.04.tar.gz
$ cd up_d.1_x86-ubuntu10.04
$ ./install.sh
I: Host platform: x86-ubuntu10.04 (use --platform if incorrect)
I: Installing up...
I: done!

This will install UP into the default location of /opt/abilisoft.com/up, binaries are in /opt/abilisoft.com/up/bin.

Running UP

It is now possible to start up by invoking it directly:

$ /opt/abilisoft.com/up/bin/up
up application initialising (7.1 (donbot.1)  r14146  20130510)

However since no listeners, chains or dispatchers have been configured it will not do anything at this point (basic configuration steps are explained later in this section). To stop up again:

$ /opt/abilisoft.com/up/bin/up --stop
I: Sent SIGTERM to PID=1279
I: Waiting for up daemon to stop . done

Rather than typing the path to the up binary each time, a shell script is provided for convenience. Source the scripts as follows:

$ . /opt/abilisoft.com/up/tools/env.sh
Following variables where set/modified:
...

This will update the current environment so that only up needs to be entered, e.g:

$ up
up application initialising (7.1 (donbot.1)  r14146  20130510)
$ up --stop
I: Sent SIGTERM to PID=6426
I: Waiting for up daemon to stop . done

Configuring a Listener

Configuring listeners is done in a configuration file called /opt/abilisoft.com/up/etc/listeners.xml The following configures a fairly standard SNMP listener:

<?xml version="1.1" encoding="UTF-8"?>
<listeners>
  <snmp id="trap">
    <chain>trap</chain>
    <synthevents>true</synthevents>
    <listen></listen>
    <port>162</port>
  <snmp>
</listeners>

This configures one SNMP listener named “trap” which will listen on all IPv4 and IPv6 interfaces on the default SNMP port. In fact both the <listen/> and <port/> tags could have been omitted as they are the default values. Obviously it is possible to configure a specific IP address in the <listen/> tag to restrict the interface to listen on.

Note

You may recognise the “id” attribute and realise this is defined to be the special type xsd:ID the XML standard. Since you can not have duplicate values of xsd:ID in a file this ensure each listener you configure is uniquely named.

Additionally this says the listener needs to send out so called “synthetic events”. These are events generated by the listener itself such as “started”, “stopped” or on error conditions. Each listener has it’s own specific set of synthetic events detailed in the listeners’ documentation, however all of them have the start, stop and error synthetic messages.

Lastly, and very importantly, this configures all events received by this listener to be passed on to the “trap” chain. This is essentially the entry-point to the rules processing for all incoming events from this listener. As we will see in just a bit this is where you can write rules which basically means decide how the incoming event is handled.

Configuring a Dispatcher

Dispatchers are the destinations to which UP will send outgoing events after it has processed incoming events using the rule chains (described next). They are configured in a format very similar to listeners, but this time in /opt/abilisoft.com/up/etc/dispatchers.xml:

<?xml version="1.1" encoding="UTF-8"?>
<dispatchers>
  <reef id="reef">
    <uri>http://localhost/reef/</uri>
  </reef>
  <email id="mail">
    <sendmail/>
  </email>
</dispatchers>

This configures two dispatchers: one Abilisoft Reef event manager dispatcher called “reef” and one email dispatcher called “mail”. Both have a fairly simple configuration. The reef dispatcher only needs a single URI as configuration while the email dispatcher is configured to use the local MTA. It is also possible to configure the email dispatcher to use an SMTP server, but this requires a few more options.

With this configuration these two dispatchers will now be available to the rule chains under their names: “reef” and “mail”.

Writing a Rule Chain

Referring back to the listener configuration the “trap” listener was configured to use the “trap” chain. Rule chains are written in files using the .chain extension in the configuration directory, so the first chain we write is /opt/abilisoft.com/up/etc/trap.chain:

# -*- coding: utf-8; mode: python -*-

"""Very simple rule chain to handle SNMP traps

This rule chain handles incoming SNMP events from the ``trap`` SNMP
listener.
"""

import up

def rule_synth_stop(event):
    """Send an email for stop synthetic events"""
    if event.synth and event['name'] == 'stop':
        out = up.EmailEvent(event)
        out.to = 'noc@example.com'
        out.subject = '{id} listener stopped'.format(id=event.listener.id)
        out.body = """Warning,

Received a stop synthetic event for the {id} {kind} listener.  Please
take appropriate action.
"""
        mail_dispatcher = up.getdispatcher('mail')
        mail_dispatcher.send(out)
        return None
    else:
        return event


def rule_synth(event):
    """Drop any remaining synthetic events"""
    if event.synth:
        return None
    else:
        return event


def rule_community(event):
    """Drop events from unknown communities"""
    if (event.listener.kind != 'snmp'
            or event['community'] not in ['public', 'private']):
        return None
    else:
        return event

def rule_create_outgoing_reef(event):
    """Create the outgoing reef event

    This rule creates the basic outgoing reef event and stores it
    on the incoming event under the "out" attribute.  It uses the
    snmpTrapOID varbind value to create the reef_key which is
    probably overly-simplistic.
    """
    out = up.ReefEvent(event)
    out['reef_key'] = event['snmpTrapOID']
    event.out = out
    return event

def rule_severity(event):
    """Set the severity of the reef event"""
    if event['community'] == 'private':
        event.out['reef_severity'] == 'major'
    else:
        event.rout['reef_severity'] == 'minor'
    return event

def rule_dispatch(event):
    """Dispatch to the Reef manager"""
    dispatcher = up.getdispatcher('reef')
    dispatcher.send(event.out)
    return None

This is quite a lot to take in at once, so let’s break it down.

Preamble

1
2
3
4
5
6
7
8
9
# -*- coding: utf-8; mode: python -*-

"""Very simple rule chain to handle SNMP traps

This rule chain handles incoming SNMP events from the ``trap`` SNMP
listener.
"""

import up

The first line is a comment and normally optional, however it is nice to have and a good practice to include it. Firstly it tells UP that the chain file is encoded using the UTF-8 character set, this become important if you start using non-ASCII characters e.g. names etc. UTF-8 is the default character set if not specified. Secondly this line is also recognised by many text editors who will now also ensure you use the correct encoding.

The second part of this line is recognised by many editors to signify the contents of this file is python code and will prompt them to display the code properly highlighted etc. This makes editing rule chains a much nicer experience.