Using Homer 5

Using Homer 5.x

This guide provides a quick application breakdown for old and new users

Initial Login

Login to HOMER using the default credentials initialized during setup.

Exercise 1: Login to Homer

• If your initial login succeed, congratulations!
• If your initial login failed - either your webserver or database are misconfigured!

Dashboard

Homer 5 ships with a dynamic dashboard/widget system which can easily be extended using standard javascript and AngularJS. All elements are user-defined and can be assembled based on requirements using the provided examples feed either internal or external data sources.

Custom dashboards can be created/managed using the dedicated icon (see example below) and saved as JSON objects stored on the webserver.

All Search queries and Widgets are linked to the global Time-Range selector:

Any change in Range Selector will cause a full Dashboard refresh automatically:

Administration

The Administrative dashboard is composed of dynamic widgets covering the basic roles:

• User Management
• Node Management
  • Database connectors
• Alias Management
  • IP to Name Aliases

Exercise 2: Change your password

• This is the perfect time to change your admin password! ;)

Done? Let's proceed further!

SIP Search

The SIP Search dashboard is composed by a dynamic set of customizable form-widgets.

SIP Search: Usage

Form fields can accept single or multiple semicolon separated parameters:

Source IP: 5.4.5.6;192.43.5.6

By default the "AND" logic is used when searching using multiple parameters - to switch to "OR" functionality just add the Logic OR component to your forms.

Perform a search for sessions in a given time-range in a few mouse clicks:

Use the Query Limit parameter to determine the max. desired number of results.

Timezone Selection

Searches and Search Results can automatically be translated to different timezone using the drop-down menu included in the Time Range selector:

SIP Search: Result Type

Several result types are available do choose the output format for a query:

Type	Description
TABLE	Display results in grid
COUNT	Display counter only
PCAP	Return results in PCAP file
TEXT	Return results in TXT file
CLOUD	Upload results to Cloud API

SIP Search: Customization

Each widget in the SIP search dashboard can be fully customized and adapted to the desired workflow and to present the most used filtering parameters.

You can also choose to create a mini-search widget within other Dashboards:

SIP Search: Results

Search results are presented in a colour-coded grid with sub-filtering per column and field:

Selecting an individual Call-ID from the results will open the Session details and present:

• SIP Session Messages
• RTP/RTCP QoS Reports
• Session Logs

RISON Parameters

Search results can be tailored using optional RISON Parameters

Grid Options

The search results grid and column visibility can be customized to match the user preference using the embedded menu at the top-right border of the grid itself presenting the available fields for display:

Grid preferences can be saved in the User Profile using the dedicated menu options:

It is also possible to create your own custom columns in the "search results". You will have to edit the "columnDefs" scope in /var/www/html/homer/js/modules/pages/controllers/resultCtrl.js

Here is an example to display a new column with the cseq field (you can refer to the table "sip_capture_call_YYYYMMDD" field names if you do not know them).

{field: 'cseq', displayName: 'cseq', visible: true},

Visualizers

Homer features a growing number of "widgets" performing different functionality and feeding internal or external data sources. Widgets are independently configurable and support several charting libraries up to the user/developer preferences, tuned to the beat of the central Range Selector and automatically reacting to changes.

Homer internal widgets currently support the following charting libraries:

• Highcharts (beautifully slow)
• CanvasJS (blazing as brutal)
• nvD3 (best of both worlds)

The "SIPCAPTURE" plugin is responsible for interfacing with Homer's internal API driven by an integrated Wizard to assist users configuring the available options and parameters for each combination easily leveraging a centralized datasource mapper:

Alarms

Homer can be programmed to detect, identify, store and trigger action on events directly from the kamailio/opensips capture plan, and allows users to easily investigate attacks, scans and other abuse conditions as well as attaching and triggering specific actions to them (ie: send an email, trap, etc)

Alarms are defined and manipulated directly within the capture script of HOMER:

if($ua =~ "(friendly-scanner|sipvicious|sipcli)") {
	$var(atype) = 'scanner';
sql_query("cb", "INSERT INTO alarm_data_mem (create_date, type, total, source_ip, description) VALUES(NOW(), '$var(atype)', 1, '$si', 'Friendly scanner alarm!') ON DUPLICATE KEY UPDATE total=total+1");
	route(KILL_VICIOUS);
}
#Alarm for Scanner;
           if($var(atype) == "scanner") {
                  sql_query("cb", "DELETE FROM alarm_data_mem WHERE type='scanner' AND total < $var(avalue)");
                  if($var(anotify) == 1) {
                     sql_query("cb", "SELECT * FROM alarm_data_mem WHERE type='scanner' AND total  >= $var(avalue) LIMIT 2", "rd");       
                     if($dbr(rd=>rows) > 0) {
                           route(SEND_ALARM);
                     } sql_result_free("rd");
                  }
           }

route[SEND_ALARM] {
  	exec_msg('echo "Value: $var(thvalue), Type: $var(atype), Desc: $var(aname)" | mail -s "HOMER ALERT $var(atype) - $var(thvalue)" $var(aemail)') ;
}

Aliases

The Aliases management feature is used in Call-Flow generators to convert IP addresses to Hostnames, and more importantly to correlate traffic to gateways with multiple iterfaces (public/private) or networks (ipv4/ipv6)

Example:

    Soft-Switch Public IP: AA.BB.CC.DD
    Soft-Switch Private IP: EE.FF.GG.HH
    Soft-Switch IPv6: III::LLLL:MMMM:NNNN:OOOO

NOTE: Replace with your actual IP addresses_

In Homer add several ALIASES with the exact same NAME:

    IP: AA.BB.CC.DD
    NAME: SWITCH1
    STATUS: 1

    IP: EE.FF.GG.HH
    NAME: SWITCH1
    STATUS: 1

    IP: [III::LLLL:MMMM:NNNN:OOOO]
    NAME: SWITCH1
    STATUS: 1

Session Correlation

In order for HOMER to automatically match and correlate separate call legs forked by a B2BUA, configure api/preferences.php with the appropriate correlation logic:

Call-ID Suffix

      /* BLEG DETECTION */
      define('BLEGDETECT', 1); /* always detect BLEG leg in CFLOW/PCAP*/
      define('BLEGCID', "b2b"); /* options: x-cid, b2b */
      define('BLEGTAIL', "_b2b-1"); /* session-ID correlation suffix for SPCE b2b mode */

X-CID

Custom headers (ie: X-CID) can be leveraged in HOMER for session correlation:

      /* BLEG DETECTION */
      define('BLEGDETECT', 1); /* always detect BLEG leg in CFLOW/PCAP*/
      define('BLEGCID', "x-cid"); /* options: x-cid, b2b */

Kamailio

To define a custom header to correlate A-leg with B-leg, configure the callid_aleg_header in SIPCAPTURE module configuration kamailio.cfg

     modparam("sipcapture", "callid_aleg_header", "X-CID")

The field will accept a single value or a list of headers, separated by semicolon:

     modparam("sipcapture", "callid_aleg_header", "X-CID0;X-CID1")

OpenSIPS

OpenSIPS provides the ability to directly manipulate the HEP object. A custom header (any) can be parsed by OpenSIPS into a variable and used as correlation_id in the HEP Header of the mirrored packet:

hep_set("utf8-string", "0x0011",  "3", "$var(correlation_id)");

To be continued....