MATE Reference Manual

Attribute Value Pairs

MATE uses AVPs for almost everything: to keep the data it has extracted from the frames' trees as well as to keep the elements of the configuration.

These "pairs" (actually tuples) are made of a name, a value and, in case of configuration AVPs, an operator. Names and values are strings. AVPs with operators other than '=' are used only in the configuration and are used for matching AVPs of Pdus, GoPs and GoGs in the analysis phase.

Name

The name is a string used to refer to a class of AVPs. Two attributes won't match unless their names are identical. Capitalized names are reserved for keywords (you can use them for your elements if you want but I think it's not the case). MATE attribute names can be used in Wireshark's display filters the same way like names of protocol fields provided by dissectors, but they are not just references to (or aliases of) protocol fields.

Value

The value is a string. It is either set in the configuration (for configuration AVPs) or by MATE while extracting interesting fields from a dissection tree and/or manipulating them later. The values extracted from fields use the same representation as they do in filter strings.

Operators

Currently only match operators are defined (there are plans to (re)add transform attributes but some internal issues have to be solved before that). The match operations are always performed between two operands: the value of an AVP stated in the configuration and the value of an AVP (or several AVPs with the same name) extracted from packet data (called "data AVPs"). It is not possible to match data AVPs to each other.

The defined match operators are:

Equal AVP Operator

This operator tests whether the values of the operator and the operand AVP are equal.

Example

Not equal AVP operator

This operator matches if the value strings of two AVPs are not equal.

Examples

"One of" AVP operator

The "one of" operator matches if the data AVP value is equal to one of the values listed in the "one of" AVP.

Examples

"Starts with" AVP operator

The "starts with" operator matches if the first characters of the data AVP value are identical to the configuration AVP value.

Examples

"Ends with" operator

The ends with operator will match if the last bytes of the data AVP value are equal to the configuration AVP value.

Examples

Contains operator

Example

"Lower than" operator

The "lower than" operator will match if the data AVP value is semantically lower than the configuration AVP value.

Examples

BUGS

It should check whether the values are numbers and compare them numerically

"Higher than" operator

The "higher than" operator will match if the data AVP value is semantically higher than the configuration AVP value.

Examples

BUGS

It should check whether the values are numbers and compare them numerically

Exists operator

The exists operator will always match as far as the two operands have the same name.

Examples

Attribute/Value Pair List (AVPL)

Operations between AVPLs

Loose Match

Loose Match Examples

Every Match

"Every" Match Examples

Strict Match

Examples

AVPL Merge

Examples

Transforms

    Transform name {
      Match [Strict|Every|Loose] match_avpl [[Insert|Replace] modify_avpl] ; // may occur multiple times, at least once
    };

Configuration AVPLs

Pdu's configuration actions

The following configuration AVPLs deal with PDU creation and data extraction.

Pdu declaration block header

    Pdu name Proto proto_name Transport proto1[/proto2/proto3[/...]]] {
      Payload proto; //optional, no default value
      Extract attribute From proto.field ; //may occur multiple times, at least once
      Transform (transform1[, transform2[, ...]]); //optional
      Criteria [{Accept|Reject}] [{Strict|Every|Loose} match_avpl];
      DropUnassigned {true|false}; //optional, default=false
      DiscardPduData {true|false}; //optional, default=false
      LastExtracted {true|false}; //optional, default=false
    };

Pdu name

Proto and Transport clauses

Payload clause

Extract clause

Transform clause

Criteria clause

DropUnassigned clause

DiscardPduData clause

LastExtracted clause

Gop's configuration actions

Gop declaration block header

Declares a Gop type and its prematch candidate key.

    Gop name On pduname Match key {
      Start match_avpl; // optional
      Stop match_avpl; // optional
      Extra match_avpl; // optional
      Transform transform_list; // optional
      Expiration time; // optional
      IdleTimeout time; // optional
      Lifetime time; // optional
      DropUnassigned [TRUE|FALSE]; //optional
      ShowTree [NoTree|PduTree|FrameTree|BasicTree]; //optional
      ShowTimes [TRUE|FALSE]; //optional, default TRUE
    };

Gop name

On clause

Match clause

Start clause

Stop clause

Extra clause

Transform clause

Expiration clause

IdleTimeout clause

Lifetime clause

DropUnassigned clause

TreeMode clause

ShowTimes clause

Gog's configuration actions

Gop declaration block header

Declares a Gog type and its prematch candidate key.

    Gog name {
      Member gopname (key); // mandatory, at least one
      Extra match_avpl; // optional
      Transform transform_list; // optional
      Expiration time; // optional, default 2.0
      GopTree [NoTree|PduTree|FrameTree|BasicTree]; // optional
      ShowTimes [TRUE|FALSE]; // optional, default TRUE
    };

Gop name

Member clause

Extra clause

Expiration clause

Transform clause

TreeMode clause

ShowTimes clause

Settings Config AVPL

The Settings config element is used to pass to MATE various operational parameters. the possible parameters are

GogExpiration

DiscardPduData

DiscardUnassignedPdu

DiscardUnassignedGop

ShowPduTree

ShowGopTimes

Debugging stuff

Debug declaration block header

    Debug {
      Filename "path/name"; //optional, no default value
      Level [0-9]; //optional, generic debug level
      Pdu Level [0-9]; //optional, specific debug level for Pdu handling
      Gop Level [0-9]; //optional, specific debug level for Gop handling
      Gog Level [0-9]; //optional, specific debug level for Gog handling
    };

Filename clause

Level clause

Pdu Level clause

Gop Level clause

Gog Level clause

Settings Example

Action=Include

        Action=Include; {Filename=filename;|Lib=libname;}

Filename

Lib

Include Example

Mate/Reference (last edited 2018-10-20 08:26:27 by GuyHarris)