Quickstart

This quick start guide will explain the basics on how to install, configure and run Reef. More detail is provided in subsequent sections of this document. While not entirely necessary, it might be worthwhile scanning the section on The Reef Datamodel to gain an understanding of the data structures that underpin Reef functionality.

Installing Reef

Reef 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 reef_donbot.1_x86-ubuntu14.04.tar.gz
$ cd reef_d.1_x86-ubuntu14.04
$ ./install.sh
I: Host platform: x86-ubuntu14.04 (use --platform if incorrect)
I: Installing reef...
I: done!

This will install Reef into the default location of /opt/abilisoft.com/reef. This location will include the ashttpd web server application and a pre-configured SQLite database.

Note

The SQLite database installed by default is more than adequate for lightweight, engineering or demonstration deployments, however it is not recommended for production deployments. It is trivial to configure an alternate database, refer to the section on Running and Configuring Reef for more information.

Running Reef

You can start Reef by invoking the ashttpd web server which by default is configured to load the Reef WSGI application. The binary for ashttpd is in /opt/abilisoft.com/reef/bin and can be invoked as follows:

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

By default ashttpd will listen on port 80 on all interfaces.

Changed in 7.4: Reef used to default to using port 8080.

Note

Make sure the server you installed Reef on has a firewall configuration that will allow HTTP requests to port 80 on all interfaces.

Note

On some platforms and security configuration Reef may not be permitted to bind to port 80. You may have to use the --httpd_port command-line option to use a different port in that case.

Open a browser and navigate to the Reef landing page:

http://<server name>

The value for <server name> will depend on where you launch the web browser and the configuration of the server you installed Reef on. The value will be an IP address, FQDN or a host name. If you run the browser on the server Reef was installed on then a value of localhost will work. Here are some examples:

http://192.168.2.12
http://localhost
http://earth.abilisoft.com
http://reefserver

The Reef landing page will look something like that shown in Reef Landing Page below.

Reef Landing Page

The page contains Reef status information and some links, refer to the Reef User Guide documentation for more information.

You can establish the run status of ashttpd from the command line, return to the terminal window (or open an new one):

$ opt/abilisoft.com/reef/bin/ashttpd --status
ashttpd running, pid: 7868

To stop ashttpd, in a terminal window enter:

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

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

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

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

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

The Reef Client

Make sure ashttpd is running. Navigate a web browser to the Reef landing page and click the link Reef Client. This will navigate you to the Reef client logon page:

Reef client logon

Log in using the default administrator credentials:

Username: admin
Password: admin

Warning

Make sure you change the administrator’s password at the earliest opportunity, as described in Changing the admin password.

After logging in you will be presented with three tabs within event management dashboard:

• Summary Tab - This view displays an overall summary of events currently managed by the Reef server.
• Service Tab - This view displays a set of panels representing “services” currently defined by Reef and the events related to them.
• Events Tab - This view displays all the events currently managed by the Reef server.

Refer to the Reef User Guide for more details on Reef event management client usage.

If you have not configured any event sources to send events to Reef, it is likely you will see no event data. You can, if you want to, continue with this “Quickstart” guide. However this might be a good time to configure some event sources using (for example) Abilisoft MA or UP. Refer to the relevant documentation (e.g. Abilisoft Monitoring Agent Documentation or Abilisoft Universal Probe Documentation respectively).

Adding fake events

Alternatively you can create some fake events to play with. Open a terminal and enter the following command (be sure to hit enter after the \ character on the first line of the command, alternatively omit the \ character and type the command all on one line):

$ PYTHONPATH=/opt/abilisoft.com/reef/share/reef.pyz \
  /opt/abilisoft.com/thirdparty/bin/python -c "import reef.seed" 100

You will see the message:

Generating 100 unique events

Note

Make sure your terminal session is the same user you used to install Reef as you will need write access to where Reef was installed.

The command will insert 100 “test” events. You can specify as many events as you like and run the command as often as you like. If you want to delete the test events before Reef receives any real events then use the Delete All button on the Actions tab in the Reef client.

The Reef Admin Console

Make sure ashttpd is running. Navigate a web browser to the Reef landing page and click the link Reef Administration. This will navigate you to the Reef Administration console. Depending on if or when you last logged on you may be presented with the Admin console logon page:

Admin console logon

Log in using the default administrator credentials:

Username: admin
Password: admin

You will be navigated to the Admin home page:

Admin home

The Reef administration home page is quite straightforward, it contains various links to objects within the Event Management database and a list of recent actions (which will be empty for a fresh installation). Clicking on any of these links will navigate you to the relevant page. The top right of the page contains links to change the current user’s password and to log out.

This section will cover Site Adminstration basics but additional detail is provided in the Reef Site Administration section.

Changing the admin password

Clicking Change password will navigate you to the Change Password page:

Change Password

Enter the user’s original password (e.g. admin) and the new password, confirm the new password and click Change my password.

Forgotten the admin password?

If you have inadvertently forgotten the admin password you can reset it via the command line. Open a terminal and enter the following command (be sure to hit enter after the \ character on the each line of the command, alternatively omit the \ character and type the command all on one line):

$ PYTHONPATH=/opt/abilisoft.com/reef/share/reef.pyz \
  /opt/abilisoft.com/thirdparty/bin/django-admin.py \
  changepassword admin --settings=reef.django_settings

Enter the new password when prompted:

Changing password for user 'admin'
Password:
Password (again):
Password changed successfully for user 'admin'

Note

Make sure your terminal session is the same user you used to install Reef as you will need write access to where Reef was installed.

Adding a user

You may want to set up additional administrative users, or set up additional users that can only log onto the Reef event management client. On the Admin home page, click on the Add link next to Users. Enter the new user’s name and password then click Save. This will navigate you to the settings page for that user where you can enter personal information, set permissions and update user related dates. Any user defined here can log on to the Reef Event Management Client.

Giving a user admin status

Only users with administrative status can access the Reef Admin console. After the step above, find and check the Staff status check box under the Permissions section, then click Save. This user will now be able to log on to the Reef Admin console.

Deleting a user

Make sure the user you want to delete is not logged in. On the Admin home page, click on the Users which will display a list of all defined users. Check the box next to any users you want to delete. From the Action drop-down list select Delete selected users and click Go. Confirm the action, after which you will be navigated back to the User list.

Reef Service Definitions

A Reef Service represents a set of related events. This is simply a set of event filters that group events according to the service definition. Services can be displayed on the Event Management client Summary tab, their colour indicating how “bad” things are using a simple RAG metaphor. Additionally all services are displayed as hart widget panels in the Services tab; the event distributions displayed in the charts relate to the filtered set of events defined by that service. This enables Reef Event Management client users to quickly determine the state of a service and drill down to the events represented by the service.

Each Service consists of a name, label and description along with one or more Filter Definitions. Each filter definition is made up of one or more Filter Terms (i.e. a comparison of an event field with a particular value). Let’s look at an example requirement for a service definition.

Example requirement

Consider two of the servers that send events into Reef are in the company’s perimeter network. We would like to define a Service that represents events from these servers, but only ones with a critical or major severity. We also want to show the events in a particular sort order, i.e. ascending in criticality, then node name.

Note

Following this example will benefit from taking the step to add fake events described in Adding fake events. The fake events added will have node name values that are compatible with this example.

Below is an outline of the service definition.

Service definition

The service is defined as:

• name - dmz_servers
• label - DMZ Servers
• description - Company servers that are in the DMZ

The service has two filter definitions described below.

Filter Definitions

Filter Definition 1 - neptune dmz events:

node == 'neptune.abilisoft.com' AND severity == (critical OR major)

Filter Definition 2 - pluto dmz events:

node == 'pluto.abilisoft.com' AND severity == (critical OR major)

DMZ service definition

On the Admin home page, click on the Add link next to the Service defs link.

• In the Name field enter dmz_servers
• In the Label field enter DMZ Servers
• Add a suitable Description field value.
• Check the Show summary box.

Note

Checking the Show summary box will cause the service to appear as an icon on the Event Management dashboard summary tab.

• In the Servicedef-filterdef relationships section click the + icon next to the first Filterdef drop down list to add a new Filter Definition. A pop-up window will appear titled Add filter def. Populate the form as described in Neptune filter definition and click Save.
• The Filterdef drop down list will be populated with the name of this first filter definition.
• In the Servicedef-filterdef relationships section click the + icon next to the second Filterdef drop down list to add a new Filter Definition. A pop-up window will appear titled Add filter def. Populate the form as described in Pluto filter definition and click Save.
• The Filterdef drop down list will be populated with the name of this second filter definition.
• Click Save. Read the section Reviewing in the Event Management client to understand how to use the new service.

Neptune filter definition

In the pop-up window, complete the Add filter def form as follows:

• In the Name field enter neptune dmz events
• Add suitable Label and Description field values.
• Check the And terms box.

Note

The And terms box defines how the filter terms are applied. This means that for an event to contribute to the service’s state it must fulfil all the filter terms defined. If the And terms box is unchecked, then an event will contribute to the service’s state if it fulfills any of the filter terms.

• In the Sort order field enter the value severity,node.

Note

The Sort order field accepts a list of comma separated event attribute names. Optionally, an attribute name may be prefixed with a ‘-‘ indicating a reverse sort order for that attribute. So for example, entering severity,-count will display events related to the Filter Definition firstly in ascending severity order and then descending count value.

• In the Filter terms section define two filter terms:

• Enter node in the first row’s Attr name field.
• Select EXACT from the Op dropdown list.
• Enter neptune.abilisoft.com in the first row’s Cmp val0 field.
• Enter severity in the second row’s Attr name field.
• Select IREGEX from the Op dropdown list.

Note

Their are lots of filter operators, this one performs a case insensitive regular expression match. Refer to the section on Filter Operators for more information.

• Enter critical|major in the second row’s Cmp val0 field.
• Click Save

Pluto filter definition

In the pop-up window, complete the Add filter def form as follows:

• In the Name field enter pluto dmz events
• Add suitable Label and Description field values.
• Check the And terms box.
• In the Sort order field enter the value severity,node.
• In the Filter terms section define two filter terms:

• Enter node in the first row’s Attr name field.
• Select EXACT from the Op dropdown list.
• Enter pluto.abilisoft.com in the first row’s Cmp val0 field.
• Enter severity in the second row’s Attr name field.
• Select IREGEX from the Op dropdown list.
• Enter critical|major in the second row’s Cmp val0 field.

• Click Save

Reviewing in the Event Management client

Open a web browser and log into the Reef event management client. On the Summary tab you will see the new service labelled DMZ Servers as shown in the DMZ Service Example.

DMZ Service Example

Click on the service icon to click-through to a filtered event list showing critical and major events from “our DMZ”, sorted by severity, then node name.

Note

If the event list is not as expected, check “all events” to see if there are events that fulfil the service criteria defined. The test events are randomly generated and a few more injections of test data should provide enough variety to show up in this test service definition.

Now click on the Service tab. Here you will also see our new service definition. Shift+click the chart to display a bar-chart, then Ctrl+click the bar chart repeatedly until you get the Severity event distribution chart which should look something like the chart in the Service Panel Example below.

Service Panel Example

Note

When making service definition updates, changes are reflected in any logged on Reef Event Management client after the next dashboard update - there is no need to reload the client.