12.8. Configuration AVPLs

12.8.1. Pdsu’s configuration actions

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

12.8.1.1. Pdu declaration block header

In each frame of the capture, MATE will look for source proto_name's PDUs in the order in which the declarations appear in its configuration and will create Pdus of every type it can from that frame, unless specifically instructed that some Pdu type is the last one to be looked for in the frame. If told so for a given type, MATE will extract all Pdus of that type and the previously declared types it finds in the frame but not those declared later.

The complete declaration of a Pdu looks as below; the mandatory order of the diverse clauses is as shown.

    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
    };

12.8.1.2. Pdu name

The name is a mandatory attribute of a Pdu declaration. It is chosen arbitrarily, except that each name may only be used once in MATE’s configuration, regardless the class of an item it is used for. The name is used to distinguish between different types of Pdus, Gops, and Gogs. The name is also used as part of the filterable fields' names related to this type of Pdu which MATE creates.

However, several Pdu declarations may share the same name. In such case, all of them are created from each source PDU matching their Proto, Transport, and Payload clauses, while the bodies of their declarations may be totally different from each other. Together with the Accept (or Reject) clauses, this feature is useful when it is necessary to build the Pdu’s AVPL from different sets of source fields depending on contents (or mere presence) of other source fields.

12.8.1.2.1. Proto and Transport clauses

Every instance of the protocol proto_name PDU in a frame will generate one Pdu with the AVPs extracted from fields that are in the proto_name's range and/or the ranges of underlying protocols specified by the Transport list. It is a mandatory attribute of a Pdu declaration. The proto_name is the name of the protocol as used in Wireshark display filter.

The Pdu’s Proto, and its Transport list of protocols separated by / tell MATE which fields of a frame can get into the Pdu’s AVPL. In order that MATE would extract an attribute from a frame’s protocol tree, the area representing the field in the hex display of the frame must be within the area of either the Proto or it’s relative Transport s. Transport s are chosen moving backwards from the protocol area, in the order they are given.

Proto http Transport tcp/ip does what you’d expect it to - it selects the nearest tcp range that precedes the current http range, and the nearest ip range that precedes that tcp range. If there is another ip range before the nearest one (e.g. in case of IP tunneling), that one is not going to be selected. Transport tcp/ip/ip that "logically" should select the encapsulating IP header too doesn’t work so far.

Once we’ve selected the Proto and Transport ranges, MATE will fetch those protocol fields belonging to them whose extraction is declared using the Extract clauses for the Pdu type. The Transport list is also mandatory, if you actually don’t want to use any transport protocol, use Transport mate. (This didn’t work until 0.10.9).

12.8.1.2.2. Payload clause

Other than the Pdu’s Proto and its Transport protocols, there is also a Payload attribute to tell MATE from which ranges of Proto's payload 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 area of the Proto's relative payload(s). Payload s are chosen moving forward from the protocol 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’ve selected the Payload ranges, MATE will fetch those protocol fields belonging to them whose extraction is declared using the Extract clauses for the Pdu type.

12.8.1.2.3. Extract clause

Each Extract clause tells MATE which protocol field value to extract as an AVP value and what string to use as the AVP name. The protocol fields are referred to using the names used in Wireshark display filters. If there is more than one such protocol field in the frame, each instance that fulfills the criteria stated above is extracted into its own AVP. The AVP names may be chosen arbitrarily, but to be able to match values originally coming from different Pdus (e.g., hostname from DNS query and a hostname from HTTP GET request) later in the analysis, identical AVP names must be assigned to them and the dissectors must provide the field values in identical format (which is not always the case).

12.8.1.2.4. Transform clause

The Transform clause specifies a list of previously declared Transform s to be performed on the Pdu’s AVPL after all protocol fields have been extracted to it. The list is always executed completely, left to right. On the contrary, the list of Match clauses inside each individual Transform is executed only until the first match succeeds.

12.8.1.2.5. Criteria clause

This clause tells MATE whether to use the Pdu for analysis. It specifies a match AVPL, an AVPL match type (Strict, Every, or Loose) and the action to be performed (Accept or Reject) if the match succeeds. Once every attribute has been extracted and eventual transform list has been executed, and if the Criteria clause is present, the Pdu’s AVPL is matched against the match AVPL; if the match succeeds, the action specified is executed, i.e. the Pdu is accepted or rejected. The default behaviours used if the respective keywords are omitted are Strict and Accept. Accordingly, if the clause is omitted, all Pdus are accepted.

12.8.1.2.6. DropUnassigned clause

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

12.8.1.2.7. DiscardPduData clause

If set to TRUE, MATE will delete the Pdu’s AVPL once it has analyzed it and eventually extracted some AVPs from it into the Gop’s AVPL. 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.

12.8.1.2.8. LastExtracted clause

If 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 to create Pdus of other types from the current frame, yet it will continue to try for the current type.

12.8.1.3. Gop’s configuration actions

12.8.1.3.1. 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
    };
12.8.1.3.2. Gop name

The name is a mandatory attribute of a Gop declaration. It is chosen arbitrarily, except that each name may only be used once in MATE’s configuration, regardless the class of an item it is used for. The name is used to distinguish between different types of Pdus, Gops, and Gogs. The name is also used as part of the filterable fields' names related to this type of Gop which MATE creates.

12.8.1.3.3. On clause

The name of Pdus which this type of Gop is supposed to be groupping. It is mandatory.

12.8.1.3.4. Match clause

Defines what AVPs form up the key part of the Gop’s AVPL (the Gop’s key AVPL or simply the Gop’s key). All Pdus matching the key AVPL of an active Gop are assigned to that Gop; a Pdu which contains the AVPs whose attribute names are listed in the Gop’s key AVPL, but they do not strictly match any active Gop’s key AVPL, will create a new Gop (unless a Start clause is given). When a Gop is created, the elements of its key AVPL are copied from the creating Pdu.

12.8.1.3.5. Start clause

If given, it tells MATE what match_avpl must a Pdu’s AVPL match, in addition to matching the Gop’s key, in order to start a Gop. If not given, any Pdu whose AVPL matches the Gop’s key AVPL will act as a start for a Gop. The Pdu’s AVPs matching the match_avpl are not automatically copied into the Gop’s AVPL.

12.8.1.3.6. Stop clause

If given, it tells MATE what match_avpl must a Pdu’s AVPL match, in addition to matching the Gop’s key, in order to stop a Gop. If omitted, the Gop is "auto-stopped" - that is, the Gop is marked as stopped as soon as it is created. The Pdu’s AVPs matching the match_avpl are not automatically copied into the Gop’s AVPL.

12.8.1.3.7. Extra clause

If given, tells MATE which AVPs from the Pdu’s AVPL are to be copied into the Gop’s AVPL in addition to the Gop’s key.

12.8.1.3.8. Transform clause

The Transform clause specifies a list of previously declared Transform s to be performed on the Gop’s AVPL after the AVPs from each new Pdu, specified by the key AVPL and the Extra clause’s match_avpl, have been merged into it. The list is always executed completely, left to right. On the contrary, the list of Match clauses inside each individual Transform is executed only until the first match succeeds.

12.8.1.3.9. Expiration clause

A (floating) number of seconds after a Gop is Stop ped during which further Pdus matching the Stop ped Gop’s key but not the Start condition will still be assigned to that Gop. The default value of zero has an actual meaning of infinity, as it disables this timer, so all Pdus matching the Stop ped Gop’s key will be assigned to that Gop unless they match the Start condition.

12.8.1.3.10. IdleTimeout clause

A (floating) number of seconds elapsed from the last Pdu assigned to the Gop after which the Gop will be considered released. The default value of zero has an actual meaning of infinity, as it disables this timer, so the Gop won’t be released even if no Pdus arrive - unless the Lifetime timer expires.

12.8.1.3.11. Lifetime clause

A (floating) of seconds after the Gop Start after which the Gop will be considered released regardless anything else. The default value of zero has an actual meaning of infinity.

12.8.1.3.12. DropUnassigned clause

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. Setting it to TRUE helps save memory and speed up filtering.

12.8.1.3.13. TreeMode clause

Controls the display of Pdus subtree of the Gop:

  • NoTree: completely suppresses showing 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
  • BasicTree: needs investigation
12.8.1.3.14. ShowTimes clause

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.

12.8.1.4. Gog’s configuration actions

12.8.1.4.1. 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
    };
12.8.1.4.2. Gop name

The name is a mandatory attribute of a Gog declaration. It is chosen arbitrarily, except that each name may only be used once in MATE’s configuration, regardless the class of an item it is used for. The name is used to distinguish between different types of Pdus, Gops, and Gogs. The name is also used as part of the filterable fields' names related to this type of Gop which MATE creates.

12.8.1.4.3. Member clause

Defines the key AVPL for the Gog individually for each Gop type gopname. All gopname type Gops whose key AVPL matches the corresponding key AVPL of an active Gog are assigned to that Gog; a Gop which contains the AVPs whose attribute names are listed in the Gog’s corresponding key AVPL, but they do not strictly match any active Gog’s key AVPL, will create a new Gog. When a Gog is created, the elements of its key AVPL are copied from the creating Gop.

Although the key AVPLs are specified separately for each of the Member gopname s, in most cases they are identical, as the very purpose of a Gog is to group together Gops made of Pdus of different types.

12.8.1.4.4. Extra clause

If given, tells MATE which AVPs from any of the Gop’s AVPL are to be copied into the Gog’s AVPL in addition to the Gog’s key.

12.8.1.4.5. Expiration clause

A (floating) number of seconds after all the Gops assigned to a Gog have been released during which new Gops matching any of the session keys should still be assigned to the existing Gog instead of creating a new one. Its value can range from 0.0 to infinite. Defaults to 2.0 seconds.

12.8.1.4.6. Transform clause

The Transform clause specifies a list of previously declared Transform s to be performed on the Gog’s AVPL after the AVPs from each new Gop, specified by the key AVPL and the Extra clause’s match_avpl, have been merged into it. The list is always executed completely, left to right. On the contrary, the list of Match clauses inside each individual Transform is executed only until the first match succeeds.

12.8.1.4.7. TreeMode clause

Controls the display of Gops subtree of the Gog:

  • NoTree: completely suppresses showing the tree
  • BasicTree: needs investigation
  • FullTree: needs investigation
12.8.1.4.8. ShowTimes clause

Whether or not to show the times subtree of the Gog. If TRUE, the default, the subtree with the timers is added to the Gog’s tree. If FALSE, the subtree is suppressed.

12.8.1.5. Settings Config AVPL

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

12.8.1.5.1. 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.

12.8.1.5.2. 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.

12.8.1.5.3. 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.

12.8.1.5.4. 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.

12.8.1.5.5. ShowPduTree
12.8.1.5.6. ShowGopTimes

12.8.1.6. Debugging Stuff

The following settings are used to debug MATE and its configuration. All levels are integers ranging from 0 (print only errors) to 9 (flood me with junk), defaulting to 0.

12.8.1.6.1. 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
    };
12.8.1.6.2. Filename clause

The {{{path/name}}} is a full path to the file to which debug output is to be written. Non-existent file will be created, existing file will be overwritten at each opening of a capture file. If the statement is missing, debug messages are written to console, which means they are invisible on Windows.

12.8.1.6.3. Level clause

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).

12.8.1.6.4. Pdu Level clause

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).

12.8.1.6.5. Gop Level clause

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).

12.8.1.6.6. Gog Level clause

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).

12.8.1.6.7. Settings Example
Action=Settings; SessionExpiration=3.5; DiscardPduData=FALSE;

12.8.1.7. Action=Include

Will include a file to the configuration.

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

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

12.8.1.7.2. Lib

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

12.8.1.7.3. Include Example
Action=Include; Filename=rtsp.mate;

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