MATE Reference Manual

Attribute Value Pairs

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

These pairs are made of a name, a value and in the configuration an operator. Names and values are strings. AVPs with operators diverse 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).

Value

The value is a string it is either set in the configuration (for configuration AVPs) or by Wireshark while extracting interesting fields from a tree. 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 defined match operators are:

• Equal = test for equality that is: either strings are identical or the match will fail.

• Not Equal ! will match only if the strings aren't equal.

• One Off | will match if one of the possible matches given is equal to the operand's string

• Starts With ^ will match if the operand string matches the first characters of the operation value string

• Ends WIth $ will match if the operand string matches the last characters of the operation value string

• Contains ~ will match if the operand string matches some of the characters of the operation value string

• Lower Than < will match if the operand string is semantically lower than the operation value string

• Higher Than > will match if the operand string is semantically lower than the operation value string

• Exists ? (can be omitted) will match the name matches

Equal AVP Operator

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

Example

• attrib=aaa; matches attrib=aaa;

  attrib=aaa; does not match attrib=bbb;

Not equal AVP operator

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

Examples

• attrib=aaa; matches attrib!bbb;

  attrib=aaa; does not match attrib!aaa;

"One of" AVP operator

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

Examples

• attrib=1; matches attrib|1|2|3;

  attrib=2; matches attrib|1|2|3;

  attrib=4; does not match attrib|1|2|3;

"Starts with" AVP operator

The "starts with" operator matches if the first characters of the operand are identical to the operator.

Examples

• attrib=abcd; matches attrib^abc;

  attrib=abc; matches attrib^abc;

  attrib=ab; does not match attrib^abc;

  attrib=abcd; does not match attrib^bcd;

  attrib=abc; does not match attrib^abcd;

"Ends with" operator

The ends with operator will match if the last bytes of the operand are equal to the operator.

Examples

• attrib=wxyz; matches attrib$xyz;

  attrib=yz; does not match attrib$xyz;

  attrib=abc...wxyz; does not match attrib$abc;

Contains operator

• The "contains" operator will match if the operand contains a string identical to the operator's value.

Example

• attrib=abcde; matches attrib~bcd;

  attrib=abcde; matches attrib~abc;

  attrib=abcde; matches attrib~cde;

  attrib=abcde; does not match attrib~xyz;

"Lower than" operator

The "lower than" operator will match if the operand is semantically lower than the operator.

Examples

• attrib=abc; matches attrib<bcd;

  attrib=1; matches attrib<2;

  but beware: attrib=10; does not match attrib<9;

  attrib=bcd; does not match attrib<abc;

  attrib=bcd; does not match attrib<bcd;

BUGS

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

"Higher than" operator

The "higher than" operator will match if the operand is semantically higher than the operator.

Examples

• attrib=bcd; matches attrib>abc;

  attrib=3; matches attrib>2;

  but beware: attrib=9; does not match attrib>10;

  attrib=abc; does not match attrib>bcd;

  attrib=abc; does not match attrib>abc;

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

• attrib=abc; matches attrib?;

  attrib=abc; matches attrib; this is the same as the previous example

  obviously attrib=abc does not match other_attrib?;

Attribute/Value Pair List (AVPL)

• PDUS, GoPs and GoGs use an AVPL to contain the tracing information. An AVPL is an unsorted set of AVPs that can be matched against other AVPLs.

Operations between AVPLs

• There are three types of match operations that can be performed between AVPLs. The PDU/GoP/GoG AVPL will be always the operand and the operation AVPL will always come from the configuration.

• 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 operand AVPL that did match the operator's AVPs.

• "Every" Match: Will match if none of the AVPs of the operator AVPL fails to match a present AVP in the operand AVPL, even if not all of the operator's AVPs have a match. If it matches it will return an AVPL containing all AVPs from the operand AVPL that did match one AVP in the operator AVPL.

• Strict Match: Will match if and only if each of the operator's AVPs have at least one match in the operand AVPL. If it matches it will return an AVPL containing the AVPs from the operand 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 operand AVPL but exist in the operand will be added to the operand AVPL.

• There are Transformations as well that combine a match avpl and an avpl to merge.

Loose Match

A loose match between AVPLs will return if at least one of the operand's AVPs matches one of the operator's AVPs.

Loose matches are used between GopExtras and PDUs, and, GogExtras and Gops. These might be used in Transforms.

Loose Match Examples

• attr_a=aaa; attr_b=bbb; attr_c=xxx; =Loose=> attr_a?; attr_c?; ==> attr_a=aaa; attr_c=xxx;

  attr_a=aaa; attr_b=bbb; attr_c=xxx; =Loose=> attr_a?; attr_c=ccc; ==> attr_a=aaa;

  attr_a=aaa; attr_b=bbb; attr_c=xxx; =Loose=> attr_a=xxx; attr_c=ccc; ==> No Match!

Every Match

An "every" match between AVPLs will return if none of the operator's AVPs that exists in the operand AVPL fails to match.

These might be used in Transforms.

Examples

• attr_a=aaa; attr_b=bbb; attr_c=xxx; =Every=> attr_a?; attr_c?; ==> attr_a=aaa; attr_c=xxx;

  attr_a=aaa; attr_b=bbb; attr_c=xxx; =Every=> attr_a?; attr_c?; attr_d=ddd; ==> attr_a=aaa; attr_c=xxx;

  attr_a=aaa; attr_b=bbb; attr_c=xxx; =Every=> attr_a?; attr_c=ccc; ==> No Match!

  attr_a=aaa; attr_b=bbb; attr_c=xxx; =Every=> attr_a=xxx; attr_c=ccc; ==> No Match!

Strict Match

• A Strict match will return if and only if every AVP in the operator has at least one match in the operand and none fails.

  These are used between Gop keys and Pdu AVPLs. These might be used in Transforms.

Examples

• attr_a=aaa; attr_b=bbb; attr_c=xxx; =Strict=> attr_a?; attr_c=xxx; ==> attr_a=aaa; attr_c=xxx;

  attr_a=aaa; attr_b=bbb; attr_c=xxx; attr_c=yyy; =Strict=> attr_a?; attr_c?; ==> attr_a=aaa; attr_c=xxx; attr_c=yyy;

  attr_a=aaa; attr_b=bbb; attr_c=xxx; =Strict=> attr_a?; attr_c=ccc; ==> No Match!

  attr_a=aaa; attr_b=bbb; attr_c=xxx; =Strict=> attr_a?; attr_c?; attr_d?; ==> No Match!

AVPL Merge

• An AVPL might be merged into another. That would add to the former every AVPs that does not exists already in the first AVPL.

• This is done between the result of a key match and against Gop or Gog AVPL, between an extra match and the Gop/Gog AVPL, between a Transform match and Pdu/Gop AVPL when inserting (but not when replacing).

Examples

• attr_a=aaa; attr_b=bbb; =Merges=> attr_a=aaa; attr_c=xxx; =former=becomes=> attr_a=aaa; attr_b=bbb; attr_c=xxx;

  attr_a=aaa; attr_b=bbb; =Merges=> attr_c=xxx; attr_d=ddd; =former=becomes=> attr_a=aaa; attr_b=bbb; attr_c=xxx; aattr_d=ddd;

Transformations

TODO: write this part

Action=Transform; Name=mi_mgw; Match=Every; Mode=Insert; m3pc=11522; cic=24; .term=DS1/1/2/24;
Action=Transform; Name=mi_mgw; Match=Every; Mode=Insert; m3pc=11522; cic=25; .term=DS1/1/2/25;

Action=Transform; Name=radius_same_port; Mode=Insert; Match=Strict; radius_port; radius_port;
Action=Transform; Name=radius_same_port; Mode=Insert; Match=Every; radius_port; .radius_port=0;

Configuration AVPLs

PDU's configuration actions

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

Action=PduDef

• MATE will look for Pdus in the order in which these AVPLs appear in its configuration and will create PDUs of every type it can from a frame unless specifically instructed to Stop once it has found a type. If Stoped at a given type it will extract all Pdus it finds of that type and the previously defined types but not those coming after.

    Action=PduDef; Name=pduname; Proto=protoname; Transport=l2p[/l3p[/l4p[/...]]]; [Payload=l2p[/l3p[/l4p[/...]]];] 
[DropPduIfUnassigned={TRUE|FALSE};] [DiscardPduData={TRUE|FALSE};]  [Stop={TRUE|FALSE};] .... attrname=filterable.field; ....

PduDef's Name AVP

• There can be only one item with a given Name in MATE's configuration. The Name is used to distinguish between different types of Pdus. The Name will be used in the filterable fields related to this type of Pdu MATE creates. The Name is mandatory.

PduDef's Proto AVP

• Every instance of the Proto in a frame will generate one Pdu with the attributes that are in the {Proto's range and/or the respective Transport ranges. It is Mandatory.

PduDef's Transport AVP

• The Pdu's Proto, and its Transport protocols tell MATE which fields of a frame can go into the Pdu. In order to extract an attribute from a frame's tree the highlighted area of the field in the hex display must be within the highlighted area of either the protocol or it's relative transports. Transports are choosen moving backwards from the protocol highlighted area, in the order they are given. Proto=http; Transport=tcp/ip; does what you expect it to. Selects the first tcp range that precedes the current http range, and the ip range that precedes the tcp range. If there is another ip "range" before the first (in case of IP tunneling) that one is not going to be selected. Transport=tcp/ip/ip that "logically" would select the encapsulating IP header too so far doesn't work. Once we selected the ranges MATE will fetch those fields belonging to them defined in the PDU and PDUExtra AVPLs for the PDU type. It is mandatory, if you don't want to use any transport use Transport=mate. This doesn't work in 0.10.9, "mate" is not defined as a field yet, it works in newer releases.

PduDef's Payload AVP

• Other than the Pdu's Proto, and its Transport protocols there's also a Payload attribute to tell MATE from which ranges to extract fields of a frame into the Pdu. In order to extract an attribute from a frame's tree the highlighted area of the field in the hex display must be within the highlighted area of either the protocol or it's relative transports. Payloads are choosen moving forward from the protocol highlighted area, in the order they are given. Proto=http; Transport=tcp/ip; Payload=mmse will select the first mmse range after the current http range.

  • Once we selected the ranges MATE will fetch those fields belonging to them defined in the PDU and PDUExtra AVPLs for the PDU type.

PduDef's DropPduIfUnassigned AVP

• If set to TRUE MATE will destroy the Pdu's if it cannot assign it to a Gop. If set to FALSE (the default if not given) MATE will keep them.

PduDef's DiscardPduData AVP

• If set to TRUE MATE will delete the Pdu's AVPL once it has analyzed it, this is useful to save memory (of which MATE uses a lot). If set to FALSE (the default if not given) MATE will keep the Pdu attributes.

PduDef's Stop AVP

• If Stop is set to FALSE (the default if not given) MATE will continue to look for Pdus of other types in the frame. If set to TRUE it will not try create more PDUs of other types from the current frame.

Remaining part of the AVPL

• The remaining of the AVPL contains AVPs whose value is the name of an Wireshark filterable field and their name is the name the extracted AVP will take.

Example: addr=ip.addr; port=udp.port; datum=proto.datum;

Action=PduExtra

• There can be more PduExtra AVPLs for each type of Pdu.

        Action=PduExtra; For=pduname; [DropPduIfUnassigned={TRUE|FALSE};] [DiscardPduData={TRUE|FALSE};]  [Stop={TRUE|FALSE};] .... attrname=filterable.field; ....

• The AVPL will be dealt as if it was part of the PduDef AVPL, the setting AVPs will overrule the prior setting.

Action=PduCriteria

• Once every attribute is extracted and if a PduCriteria is defined for this type of Pdu the Pdu's extracted AVPL will be matched against the criteria if it fails the Pdu will be dropped.

        Action=PduCriteria; For=pduname; [Mode={Accept|Reject};] [Match={Strict|Every|Loose};] ....

PduCriteria's For AVP

• As in most MATE's config AVPLs the For AVP tells MATE to which type of Pdu the AVPL applies. It is mandatory.

PduCriteria's Mode AVP

• If Mode is set to Accept (the default if not given) the PDU's AVPL will be dropped unless it matches the rest of the AVPL. Or else, if set to Reject Pdus whose AVPL matches the rest of the AVPL will be dropped.

PduCriteria's Match AVP

• The Match AVP will tell MATE which AVPL match operation type should it use to match against the Pdu's AVPL. It can either be Loose, Every or Strict, which is the default if it is not given.

Action=PduTransform

        Action=PduTransform; Name=transformname; For=pduname;

Name AVP

For AVP

Gop's configuration actions

Action=GopDef

Declares a Gop type and its prematch candidate key.

        Action=GopDef; Name=gopname; On=pduname; [DiscardUnassignedGop={FALSE|TRUE};]  [ShowPduTree={NoTree|PduTree|FrameTree};]  [ShowGopTimes={TRUE|FALSE};] [GopExpiration=seconds;] [GopIdleTimeout=seconds;] [GopLifetime=seconds;]....

Name AVP

The Name given to the Gop. The name is used to refer to this type of Gop elsewhere in the configuration and as a prefix for the name of the fields related to the Gop. This attribute is mandatory.

On AVP

The Pdu's Name which this type of Gop is supposed to be groupping. This attribute is mandatory.

GopDef's DiscardUnassignedGop AVP

Whether or not a Gop that has not being assigned to any Gog should be discarded. If TRUE the Gop is discarded right after creation, If FALSE, the default, the unassigned Gop is kept. Helps saving memory and to speed up filtering.

GopDef ShowPduTree AVP

Controls the Pdus subtree of the Gop:

• NoTree: suppress the tree

• PduTree: the tree is shown and shows the Pdus by Pdu Id

• FrameTree: the tree is shown and shows the Pdus by the frame number in which they are

GopDef ShowGopTimes AVP

Whether or not to show the times subtree of the Gop. If TRUE, the default, the subtree with the timers is added to the Gop's tree, . If false the subtree is suppressed.

GopDef GopExpiration AVP

Floating number: Number of seconds after a Gop is released after which no more Pdus are to be assigned to the Gop. If zero, the default, Pdus not matching the key but not the start condition will be assigned to Gop even after release.

GopDef GopIdleTimeout AVP

Floating number: Number of seconds after which if the Gop hasn't being assigned Pdus the gop will be considered released. If zero, the default, the Gop won't be released if no pdus arrive (unless it's lifetime is expires).

GopDef GopLifetime AVP

Floating number: Number of seconds after the Gop Start after which the Gop will be considered released regardless of any other thing. If zero, the default, the lifetime is infinite.

Action=GopStart

If given it tells MATE when a Pdu matching a Gop's key is supposed to start a Gop. If not given a Pdu whose AVPL matches an existing GogKey will act as a start for a Gop.

        Action=GopStart; For=gopname; .....

For AVP

The name of the Gop type for which this start condition is declared

Action=GopStop

If given it tells MATE in which condition a Gop should be stopped. If omitted the Gop is said to be auto-stopped, that is, the Gop is going to be marked as stop as soon as it's created.

        Action=GopStop; For=gopname; .....

For AVP

Action=GopExtra

Tells MATE which attributes from the Pdu's AVPL other than the Gop's key ones are to be copied into the Gop's AVPL. It is used as well to set attributes of the Gop after its GopDef has being already declared.

        Action=GopExtra; For=gopname; [DiscardUnassignedGop={FALSE|TRUE};]  [ShowPduTree={NoTree|PduTree|FrameTree};]  [ShowGopTimes={TRUE|FALSE};] ....

For AVP

GopExtra's DiscardUnassignedGop AVP

GopExtra ShowPduTree AVP

GopExtra ShowGopTimes AVP

Action=GopTransform

        Action=GopTransform; Name=transformname; For=gopname;

Name AVP

For AVP

GoG's Configuration AVPLs

Action=GogDef

        Action=GogDef; Name=gogname; [GogExpiration=(float);] [GopTree={FALSE|TRUE};]

Name AVP

GogExpiration

• How long in seconds after all the gops assigned to a gog have been released new gops matching any of the session keys should create a new gog instead of being assigned to the previous one. Its value can range from 0.0 to infinite. Defaults to 2.0 seconds.

Action=GogKey

        Action=GogKey; For=gogname; On=gopname; ....

For AVP

On AVP

Action=GogExtra

                Action=GogDef; For=gogname; [GogExpiration=(float);] [GopTree={FALSE|TRUE};] .....

For AVP

GogExpiration

• How long in seconds after all the gops assigned to a gog have been released new gops matching any of the session keys should create a new gog instead of being assigned to the previous one. Its value can range from 0.0 to infinite. Defaults to 2.0 seconds.

Action=GogTransform

        Action=GogTransform; Name=transformname; For=gogname;

Name AVP

For AVP

Settings Config AVPL

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

GogExpiration

• How long in seconds after all the gops assigned to a gog have been released new gops matching any of the session keys should create a new gog instead of being assigned to the previous one. Its value can range from 0.0 to infinite. Defaults to 2.0 seconds.

DiscardPduData

• Whether or not the AVPL of every PDU should be deleted after it was being processed (saves memory). It can be either TRUE or FALSE. Defaults to TRUE. Setting it to FALSE can save you from a headache if your config does not work.

DiscardUnassignedPdu

• Whether PDUs should be deleted if they are not assigned to any Gop. It can be either TRUE or FALSE. Defaults to FALSE. Set it to TRUE to save memory if unassigned Pdus are useless.

DiscardUnassignedGop

• Whether GoPs should be deleted if they are not assigned to any session. It can be either TRUE or FALSE. Defaults to FALSE. Setting it to TRUE saves memory.

ShowPduTree

ShowGopTimes

Debugging Stuff

• The following settngs are used to debug MATE and its configuration. All levels default to 0 (no debugging).

Debug_Filename

• If present debug messages will be output to that file, if not present debug output will go to the console.

Debug_Level

• Sets the level of debugging for generic debug messages. It is an integer ranging from 0 (print only errors) to 9 flood me with junk.

Debug_Pdu

• Sets the level of debugging for messages regarding PDU creation. It is an integer ranging from 0 (print only errors) to 9 flood me with junk.

Debug_Gop

• Sets the level of debugging for messages regarding PDU analysis (that is how do they fit into GoPs). It is an integer ranging from 0 (print only errors) to 9 flood me with junk.

Debug_Gog

• Sets the level of debugging for messages regarding GoP analysis (that is how do they fit into GoGs). It is an integer ranging from 0 (print only errors) to 9 flood me with junk.

Settings Example

•  Action=Settings; SessionExpiration=3.5; DiscardPduData=FALSE; 

Action=Include

• Will include a file to the configuration.

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

Filename

• The filename of the file to include. If it does not beging with '/' it will look for the file in the current path.

Lib

• The name of the lib config to include. will look for libname.mate in wiresharks_dir/matelib .

Include Example

• Action=Include; Filename=rtsp.mate;

  This will include the file called "rtsp.mate" into the current config.