12.3. MATE Overview
Prev | Chapter 12. MATE | Next

## 12.3. MATE Overview

### 12.3.1. Introduction

MATE creates a filterable tree based on information contained in frames that share some relationship with information obtained from other frames. The way these relationships are made is described in a configuration file. The configuration file tells MATE what makes a PDU and how to relate it to other PDUs.

MATE analyzes each frame to extract relevant information from the "protocol" tree of that frame. The extracted information is contained in MATE PDUs; these contain a list of relevant attributes taken from the tree. From now on, I will use the term "PDU" to refer to the objects created by MATE containing the relevant information extracted from the frame; I’ll use "frame" to refer to the "raw" information extracted by the various dissectors that pre-analyzed the frame.

For every PDU, MATE checks if it belongs to an existing "Group of PDUs" (GOP). If it does, it assigns the PDU to that GOP and moves any new relevant attributes to the GOP’s attribute list. How and when do PDUs belong to GOPs is described in the configuration file as well.

Every time a GOP is assigned a new PDU, MATE will check if it matches the conditions to make it belong to a "Group of Groups" (GOG). Naturally the conditions that make a GOP belong to a GOG are taken from the configuration file as well.

Once MATE is done analyzing the frame it will be able to create a "protocol" tree for each frame based on the PDUs, the GOPs they belong to and naturally any GOGs the former belongs to.

How to tell MATE what to extract, how to group it and then how to relate those groups is made using AVPs and AVPLs.

Information in MATE is contained in Attribute Value Pairs (AVPs). AVPs are made of two strings: the name and the value. AVPs are used in the configuration and there they have an operator as well. There are various ways AVPs can be matched against each other using those operators.

AVPs are grouped into AVP Lists (AVPLs). PDUs, GOPs and GOGs have an AVPL each. Their AVPLs will be matched in various ways against others coming from the configuration file.

MATE will be instructed how to extract AVPs from frames in order to create a PDU with an AVPL. It will be instructed as well, how to match that AVPL against the AVPLs of other similar PDUs in order to relate them. In MATE the relationship between PDUs is a GOP, it has an AVPL as well. MATE will be configured with other AVPLs to operate against the GOP’s AVPL to relate GOPs together into GOGs.

A good understanding on how AVPs and AVPLs work is fundamental to understand how MATE works.

#### 12.3.1.1. About MATE

MATE was originally written by Luis Ontanon, a Telecommunications systems troubleshooter, as a way to save time filtering out the packets of a single call from huge capture files using just the calling number. Later he used the time he had saved to make it flexible enough to work with protocols other than the ones he was directly involved with.

### 12.3.2. Attribute Value Pairs (AVP)

Information used by MATE to relate different frames is contained in Attribute Value Pairs (AVPs). AVPs are made of two strings - the name and the value. When AVPs are used in the configuration, an operator is defined as well. There are various ways AVPs can be matched against each other using those operators.

      avp_name="avp's value"
      another_name= "1234 is the value"

The name is a string used to refer to a "type" of an AVP. Two AVPs won’t match unless their names are identical.

The name must start with a lowercase letter (a-z) and can contain only alphanumeric characters (a-zA-Z0-9) and the special characters "_", "-", and ".". The name ends with an operator.

You should not use uppercase characters in names, or names that start with “.” or “_”. Capitalized names are reserved for configuration parameters (we’ll call them keywords); nothing forbids you from using capitalized strings for other things as well but it probably would be confusing. I’ll avoid using capitalized words for anything but the keywords in this document, the reference manual, the examples and the base library. Names that start with a “.” would be very confusing as well because in the old grammar, AVPL transforms use names starting with a “.” to indicate they belong to the replacement AVPL.

The value is a string that is either set in the configuration (for configuration AVPs) or by Wireshark while extracting interesting fields from a frame’s tree. The values extracted from fields use the same representation as they do in filter strings except that no quotes are used.

The value will be dealt with as a string even if it is a number. If there are any spaces in the value, the value must be between quotes "". Values that are also keywords such as True and False should also be wrapped in quotes ("True", "False").

       ip_addr=10.10.10.11
       tcp_port=1234
       binary_data=01:23:45:67:89:ab:cd:ef
       parameter12=0x23aa
       parameter_with_spaces="this value has spaces"

The way two AVPs with the same name might match is described by the operator. Remember two AVPs won’t match unless their names are identical. In MATE, match operations are always made between the AVPs extracted from frames (called data AVPs) and the configuration’s AVPs.

Currently defined MATE AVP match operators are:

- Equal = will match if the string given completely matches the data AVP’s value string
- Not Equal ! will match only if the given value string is not equal to the data AVP’s value string
- One Of {} will match if one of the possible strings listed is equal to the data AVP’s value string
- Starts With ^ will match if the string given matches the first characters of the data AVP’s value string
- Ends With $ will match if the string given matches the last characters of the data AVP’s value string
- Contains ~ will match if the string given matches any substring of the data AVP’s value string
- Lower Than < will match if the data AVP’s value string is semantically lower than the string given
- Higher Than > will match if the data AVP’s value string is semantically higher than the string given
- Exists ? (the ? can be omitted) will match as far as a data AVP of the given name exists

### 12.3.3. AVP lists (AVPL)

An AVPL is a set of diverse AVPs that can be matched against other AVPLs. Every PDU, GOP and GOG has an AVPL that contains the information regarding it. The rules that MATE uses to group PDUs and GOPs are AVPL operations.

There will never be two identical AVPs in a given AVPL. However, we can have more than one AVP with the same name in an AVPL as long as their values are different.

Some AVPL examples:

      ( addr=10.20.30.40, addr=192.168.0.1, tcp_port=21, tcp_port=32534, user_cmd=PORT,
            data_port=12344, data_addr=192.168.0.1 )
      ( addr=10.20.30.40, addr=192.168.0.1, channel_id=22:23, message_type=Setup,
            calling_number=1244556673 )
      ( addr=10.20.30.40, addr=192.168.0.1, ses_id=01:23:45:67:89:ab:cd:ef )
      ( user_id=pippo, calling_number=1244556673, assigned_ip=10.23.22.123 )

In MATE there are two types of AVPLs:

- data AVPLs that contain information extracted from frames.
- configuration AVPLs that come from the configuration and are used to tell MATE how to relate items based on their data AVPLs.

Data AVPLs can be operated against configuration AVPLs in various ways:

- Loose Match: Will match if at least one of the AVPs of each AVPL match. If it matches it will return an AVPL containing all AVPs from the data AVPL that did match the configuration AVPs.
- "Every" Match: Will match if none of the AVPs of the configuration AVPL fails to match a present AVP in the data AVPL, even if not all of the configuration AVPs have a match. If it matches it will return an AVPL containing all AVPs from the data AVPL that did match one AVP in the configuration AVPL.
- Strict Match: Will match if and only if every one of the configuration AVPs have at least one match in the data AVPL. If it matches it will return an AVPL containing the AVPs from the data AVPL that matched.
- There’s also a Merge operation that is to be performed between AVPLs where all the AVPs that don’t exist in the data AVPL but exist in the configuration will be added to the data AVPL.
- Other than that, there are Transforms - a combination of a match AVPL and an AVPL to merge.

Prev | Up | Next
12.2. Getting Started | Home | 12.4. MATE Frame Analysis