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.
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.
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.
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 = test for equality, that is: either the value strings are identical or the match will fail.
- Not Equal ! will match only if the value strings aren’t equal.
- One Of {} will match if one of the value strings listed is equal to the data AVP’s string. Individual tems of the list inside the curly braces are separated using | character.
- Starts With ^ will match if the configuration value string matches the first characters of the data AVP’s value string.
- Ends With $ will match if the configuration value string matches the last characters of the data AVP’s value string.
- Contains ~ will match if the configuration value string matches a substring of the characters of the data AVP’s value string.
- Lower Than < will match if the data AVP’s value string is semantically lower than the configuration value string.
- Higher Than > will match if the data AVP’s value string is semantically higher than the configuration value string.
- Exists ? (can be omitted) will match if the AVP name matches, regardless what the value string is.
This operator tests 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
This operator matches if the value strings of two AVPs are not equal.
- Example
- attrib=aaa matches attrib!bbb attrib=aaa does not match attrib!aaa
The "one of" operator matches if the data AVP value is equal to one of the values listed in the "one of" AVP.
- Example
- attrib=1 matches attrib{1|2|3} attrib=2 matches attrib{1|2|3} attrib=4 does not match attrib{1|2|3}
The "starts with" operator matches if the first characters of the data AVP value are identical to the configuration AVP value.
- Example
- 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
The ends with operator will match if the last bytes of the data AVP value are equal to the configuration AVP value.
- Example
- attrib=wxyz matches attrib$xyz attrib=yz does not match attrib$xyz attrib=abc…wxyz does not match attrib$abc
The "contains" operator will match if the data AVP value contains a string identical to the configuration AVP value.
- Example
- attrib=abcde matches attrib~bcd attrib=abcde matches attrib~abc attrib=abcde matches attrib~cde attrib=abcde does not match attrib~xyz
The "lower than" operator will match if the data AVP value is semantically lower than the configuration AVP value.
- Example
- 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
The "higher than" operator will match if the data AVP value is semantically higher than the configuration AVP value.
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
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.
There are three types of match operations that can be performed between AVPLs. The Pdu’s/GoP’s/GoG’s AVPL will be always one of the operands; the AVPL operator (match type) and the second operand AVPL will always come from the configuration. Note that a diverse AVP match operator may be specified for each AVP in the configuration AVPL.
An AVPL match operation returns a result AVPL. In Transforms, the result AVPL may be replaced by another AVPL. The replacement means that the existing data AVPs are dropped and the replacement AVPL from the configuration is Merged to the data AVPL of the Pdu/GoP/GoG.
- Loose Match: Will match if at least one of the AVPs of the two operand AVPLs match. If it matches, it returns a result AVPL containing all AVPs from the data AVPL that did match the configuration’s AVPs.
- "Every" Match: Will match if none of the AVPs of the configuration AVPL fails to match an AVP in the data AVPL, even if not all of the configuration AVPs have a match. If it matches, it returns a result AVPL containing all AVPs from the data AVPL that did match an AVP in the configuration AVPL.
- Strict Match: Will match if and only if each of the AVPs in the configuration AVPL has at least one match in the data AVPL. If it matches, it returns a result AVPL containing those AVPs from the data AVPL that matched.
A loose match between AVPLs succeeds if at least one of the data AVPs matches at least one of the configuration AVPs. Its result AVPL contains all the data AVPs that matched.
Loose matches are used in Extra operations against the Pdu's AVPL to merge the result into Gop's AVPL, and against Gop's AVPL to merge the result into Gog's AVPL. They may also be used in Criteria and Transforms.
![[Note]](wsug_graphics/note.svg) | Note |
|---|---|
|
As of current (2.0.1), Loose Match does not work as described here, see issue 12184. Only use in Transforms and Criteria is effectively affected by the bug. |
Loose Match Examples
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Loose (attr_a?, attr_c?) =⇒ (attr_a=aaa, attr_c=xxx)
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Loose (attr_a?, attr_c=ccc) =⇒ (attr_a=aaa)
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Loose (attr_a=xxx; attr_c=ccc) =⇒ No Match!
An "every" match between AVPLs succeeds if none of the configuration’s AVPs that have a counterpart in the data AVPL fails to match. Its result AVPL contains all the data AVPs that matched.
These may only be used in Criteria and Transforms.
| Note |
|---|---|
|
As of current (2.0.1), Loose Match does not work as described here, see issue 12184. |
"Every" Match Examples
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Every (attr_a?, attr_c?) =⇒ (attr_a=aaa, attr_c=xxx)
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Every (attr_a?, attr_c?, attr_d=ddd) =⇒ (attr_a=aaa, attr_c=xxx)
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Every (attr_a?, attr_c=ccc) =⇒ No Match!
(attr_a=aaa; attr_b=bbb; attr_c=xxx) Match Every (attr_a=xxx, attr_c=ccc) =⇒ No Match!
A Strict match between AVPLs succeeds if and only if every AVP in the configuration AVPL has at least one counterpart in the data AVPL and none of the AVP matches fails. The result AVPL contains all the data AVPs that matched.
These are used between Gop keys (key AVPLs) and Pdu AVPLs. They may also be used in Criteria and Transforms.
Examples
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Strict (attr_a?, attr_c=xxx) =⇒ (attr_a=aaa, attr_c=xxx)
(attr_a=aaa, attr_b=bbb, attr_c=xxx, attr_c=yyy) Match Strict (attr_a?, attr_c?) =⇒ (attr_a=aaa, attr_c=xxx, attr_c=yyy)
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Strict (attr_a?, attr_c=ccc) =⇒ No Match!
(attr_a=aaa, attr_b=bbb, attr_c=xxx) Match Strict (attr_a?, attr_c?, attr_d?) =⇒ No Match!
An AVPL may be merged into another one. That would add to the latter every AVP from the former that does not already exist there.
This operation is done
- between the result of a key match and the Gop’s or Gog’s AVPL,
- between the result of an Extra match and the Gop’s or Gog’s AVPL,
- between the result of a Transform match and Pdu’s/Gop’s AVPL. If the operation specified by the Match clause is Replace, the result AVPL of the match is removed from the item’s AVPL before the modify_avpl is merged into it.
Examples
(attr_a=aaa, attr_b=bbb) Merge (attr_a=aaa, attr_c=xxx) former becomes (attr_a=aaa, attr_b=bbb, attr_c=xxx)
(attr_a=aaa, attr_b=bbb) Merge (attr_a=aaa, attr_a=xxx) former becomes (attr_a=aaa, attr_a=xxx, attr_b=bbb)
(attr_a=aaa, attr_b=bbb) Merge (attr_c=xxx, attr_d=ddd) former becomes (attr_a=aaa, attr_b=bbb, attr_c=xxx, attr_d=ddd)
A Transform is a sequence of Match rules optionally followed by an instruction how to modify the match result using an additional AVPL. Such modification may be an Insert (merge) or a Replace. The syntax is as follows:
Transform name {
Match [Strict|Every|Loose] match_avpl [[Insert|Replace] modify_avpl] ; // may occur multiple times, at least once
};
For examples of Transforms, check the Manual page.
TODO: migrate the examples here?
The list of Match rules inside a Transform is processed top to bottom; the processing ends as soon as either a Match rule succeeds or all have been tried in vain.
Transforms can be used as helpers to manipulate an item’s AVPL before the item is processed further. An item declaration may contain a Transform clause indicating a list of previously declared Transforms. Regardless whether the individual transforms succeed or fail, the list is always executed completely and in the order given, i.e. left to right.
In MATE configuration file, a Transform must be declared before declaring any item which uses it.