[[ChMate]] == MATE [[ChMateIntroduction]] === Introduction MATE: Meta Analysis and Tracing Engine What is MATE? Well, to keep it very short, with MATE you can create user configurable extension(s) of the display filter engine. MATE's goal is to enable users to filter frames based on information extracted from related frames or information on how frames relate to each other. MATE was written to help troubleshooting gateways and other systems where a "use" involves more protocols. However MATE can be used as well to analyze other issues regarding a interaction between packets like response times, incompleteness of transactions, presence/absence of certain attributes in a group of PDUs and more. MATE is a Wireshark plugin that allows the user to specify how different frames are related to each other. To do so, MATE extracts data from the frames' tree and then, using that information, tries to group the frames based on how MATE is configured. Once the PDUs are related MATE will create a "protocol" tree with fields the user can filter with. The fields will be almost the same for all the related frames, so one can filter a complete session spanning several frames containing more protocols based on an attribute appearing in some related frame. Other than that MATE allows to filter frames based on response times, number of PDUs in a group and a lot more. So far MATE has been used to: * Filter all packets of a call using various protocols knowing just the calling number. (MATE's original goal) * Filter all packets of all calls using various protocols based on the release cause of one of its "segments". * Extrapolate slow transactions from very "dense" captures. (finding requests that timeout) * Find incomplete transactions (no responses) * Follow requests through more gateways/proxies. * more... [[ChMateGettingStarted]] === Getting Started These are the steps to try out MATE: * Run Wireshark and check if the plugin is installed correct (MATE should appear in Help->About->Plugins) * Get a configuration file e.g. tcp.mate (see https://wiki.wireshark.org/Mate/Examples[Mate/Examples] for more) and place it somewhere on your harddisk. * Go to Preferences->Protocols->MATE and set the config filename to the file you want to use (you don't have to restart Wireshark) * Load a corresponding capture file (e.g. https://wiki.wireshark.org/SampleCaptures/http.cap[http.cap]) and see if MATE has added some new display filter fields, something like: `mate tcp_pdu:1->tcp_ses:1` or, at prompt: `path_to/wireshark -o "mate.config: tcp.mate" -r http.cap`. If anything went well, your packet details might look something like this: image::wsug_graphics/ws-mate-tcp-output.png[] [[ChMateManual]] === MATE Manual ==== Introduction MATE creates a filterable tree based on information contained in frames that share some relationship with information obtained from other frames. The way this 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 atributes 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. [[AVP]] ==== Attribute Value Pairs 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 "kind" of an AVP. Two AVPs won't match unless their names are identical. 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 transformations 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 name can contain only alphanumeric characters, "_", and ".". The name ends with an operator. 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 "". ---- 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's AVP match operators are: * <> +*=*+ will match if the string given completely matches the data AVP's value string * <> +*!*+ will match only if the given value string is not equal to the data AVP's value string * <> +*{}*+ will match if one of the possible strings listed is equal to the data AVP's value string * <> +*^*+ will match if the string given matches the first characters of the data AVP's value string * <> +*$*+ will match if the string given matches the last characters of the data AVP's value string * <> +*~*+ will match if the string given matches any substring of the data AVP's value string * <> +*<*+ will match if the data AVP's value string is semantically lower than the string given * <> +*>*+ will match if the data AVP's value string is semantically higher than the string given * <> +*?*+ (the ? can be ommited) will match as far as a data AVP of the given name exists ==== AVP lists 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. * operation 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 operation AVPLs in various ways: * <>: 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. * <>: 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. * <>: Will match if and only if every one 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 <> 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. * Other than that there are <> - a combination of a match AVPL and an AVPL to merge. ==== MATE Analysis MATE's analysis of a frame is performed in three phases: * In the first phase, MATE attempts to extract a MATE Pdu from the frame's protocol tree. MATE will create a Pdu if MATE's config has a +Pdu+ declaration whose +Proto+ is contained in the frame. * In the second phase, if a Pdu has been extracted from the frame, MATE will try to group it to other Pdus into a Gop (Group of Pdus) by matching the key criteria given by a +Gop+ declaration. If there is no Gop yet with the key criteria for the Pdu, MATE will try to create a new Gop for it if it matches the +Start+ criterium given in the Gop declaration. * In the third phase, if there's a Gop for the Pdu, MATE will try to group this Gop with other Gops into a Gog (Group of Groups) using the criteria given by the +Member+ criteria of a Gog declaration. image::wsug_graphics/ws-mate-analysis.png[] The extraction and matching logic comes from MATE's configuration; MATE's configuration file is declared by the +mate.config+ preference. By default it is an empty string which means: do not configure MATE. The config file tells MATE what to look for in frames; How to make PDUs out of it; How will PDUs be related to other similar PDUs into Gops; And how Gops relate into Gogs. The MATE configuration file is a list of declarations. There are 4 types of declarations: +Transform+, +Pdu+, +Gop+ and +Gog+. ===== Mate's PDU's MATE will look in the tree of every frame to see if there is useful data to extract, and if there is, it will create one or more PDU objects containing the useful information. The first part of MATE's analysis is the "PDU extraction"; there are various "Actions" that are used to instruct MATE what has to be extracted from the current frame's tree into MATE's PDUs. ====== PDU data extraction MATE will make a Pdu for each different proto field of Proto type present in the frame. MATE will fetch from the field's tree those fields that are defined in the <> declaration whose initial offset in the frame is within the boundaries of the current Proto and those of the given Transport and Payload statements. ---- Pdu dns_pdu Proto dns Transport ip { Extract addr From ip.addr; Extract dns_id From dns.id; Extract dns_resp From dns.flags.response; }; ---- MATE will make a Pdu for each different proto field of Proto type present in the frame. MATE will fetch from the field's tree those fields that are defined in the <> AVPL whose initial offset in the frame is within the boundaries of the current Proto and those of the various assigned Transports. image::wsug_graphics/ws-mate-dns_pane.png[] Once MATE has found a +Proto+ field for which to create a Pdu from the frame it will move backwards in the frame looking for the respective +Transport+ fields. After that it will create AVPs named as each of those given in the rest of the AVPL for every instance of the fields declared as its values. image::wsug_graphics/ws-mate-dns_pdu.png[] Sometimes we need information from more than one +Transport+ protocol. In that case MATE will check the frame looking backwards to look for the various +Transport+ protocols in the given stack. MATE will choose only the closest transport boundary per "protocol" in the frame. This way we'll have all Pdus for every +Proto+ that appears in a frame match its relative transports. ---- Pdu isup_pdu Proto isup Transport mtp3/ip { Extract m3pc From mtp3.dpc; Extract m3pc From mtp3.opc; Extract cic From isup.cic; Extract addr From ip.addr; Extract isup_msg From isup.message_type; }; ---- image::wsug_graphics/ws-mate-isup_over_mtp3_over_ip.png[] This allows to assign the right +Transport+ to the Pdu avoiding duplicate transport protocol entries (in case of tunneled ip over ip for example). ---- Pdu ftp_pdu Proto ftp Transport tcp/ip { Extract addr From ip.addr; Extract port From tcp.port; Extract ftp_cmd From ftp.command; }; ---- image::wsug_graphics/ws-mate-ftp_over_gre.png[] Other than the mandatory +Transport+ there is also an optional +Payload+ statement, which works pretty much as +Transport+ but refers to elements after the +Proto+'s range. It is useful in those cases where the payload protocol might not appear in a Pdu but nevertheless the Pdu belongs to the same category. ---- Pdu mmse_over_http_pdu Proto http Transport tcp/ip { Payload mmse; Extract addr From ip.addr; Extract port From tcp.port; Extract method From http.request.method; Extract content From http.content_type; Extract http_rq From http.request; Extract resp From http.response.code; Extract host From http.host; Extract trx From mmse.transaction_id; Extract msg_type From mmse.message_type; Extract notify_status From mmse.status; Extract send_status From mmse.response_status; }; ---- image::wsug_graphics/ws-mate-mmse_over_http.png[] ====== Conditions on which to create PDUs There might be cases in which we won't want MATE to create a PDU unless some of its extracted attributes meet or do not meet some criteria. For that we use the +Criteria+ statements of the +Pdu+ declarations. ---- Pdu isup_pdu Proto isup Transport mtp3/ip { ... // MATE will create isup_pdu PDUs only when there is not a point code '1234' Criteria Reject Strict (m3pc=1234); }; Pdu ftp_pdu Proto ftp Transport tcp/ip { ... // MATE will create ftp_pdu PDUs only when they go to port 21 of our ftp_server Criteria Accept Strict (addr=10.10.10.10, port=21); }; ---- The +Criteria+ statement is given an action (+Accept+ or +Reject+), a match mode (+Strict+, +Loose+ or +Every+) and an AVPL against which to match the currently extracted one. ====== Transforming the attributes of a PDU Once the fields have been extracted into the Pdu's AVPL, MATE will apply any declared transformation to it. The way transforms are applied and how they work is described later on. However it's useful to know that once the AVPL for the Pdu is created, it may be transformed before being analyzed. That way we can massage the data to simplify the analysis. ====== MATE's PDU tree Every successfully created Pdu will add a MATE tree to the frame dissection. If the Pdu is not related to any Gop, the tree for the Pdu will contain just the Pdu's info, if it is assigned to a Gop, the tree will also contain the Gop items, and the same applies for the Gog level. ---- mate dns_pdu:1 dns_pdu: 1 dns_pdu time: 3.750000 dns_pdu Attributes dns_resp: 0 dns_id: 36012 addr: 10.194.4.11 addr: 10.194.24.35 ---- The Pdu's tree contains some filterable fields * +*mate.dns_pdu*+ will contain the number of the "dns_pdu" Pdu * +*mate.dns_pdu.RelativeTime*+ will contain the time passed since the beginning of the capture in seconds * the tree will contain the various attributes of the Pdu as well, these will all be strings (to be used in filters as "10.0.0.1", not as 10.0.0.1) ** mate.dns_pdu.dns_resp ** mate.dns_pdu.dns_id ** mate.dns_pdu.addr ===== Grouping Pdus together (Gop) Once MATE has created the Pdus it passes to the Pdu analysis phase. During the PDU analysis phase MATE will try to group Pdus of the same type into 'Groups of Pdus' (aka *Gop*s) and copy some AVPs from the Pdu's AVPL to the Gop's AVPL. image::wsug_graphics/ws-mate-pdu_analysis.png[] ====== What can belong to a Gop Given a Pdu, the first thing MATE will do is to check if there is any Gop declaration in the configuration for the given Pdu type. If so, it will use its +*Match*+ AVPL to match it against the Pdu's AVPL; if they don't match, the analysis phase is done. If there is a match, the AVPL is the Gop's candidate key which will be used to search the Gop's index for the Gop to which to assign the current PDU. If there is no such Gop and this Pdu does not match the +*Start*+ criteria of a Gop declaration for the Pdu type, the Pdu will remain unassigned and only the analysis phase will be done. ---- Gop ftp_ses On ftp_pdu Match (addr, addr, port, port); Gop dns_req On dns_pdu Match (addr, addr, dns_id); Gop isup_leg On isup_pdu Match (m3pc, m3pc, cic); ---- ====== Start of a Gop If there was a match, the candidate key will be used to search the Gop's index to see if there is already a Gop matching the Gop's key the same way. If there is such a match in the Gops collection, and the PDU doesn't match the +*Start*+ AVPL for its kind, the PDU will be assigned to the matching Gop. If it is a +*Start*+ match, MATE will check whether or not that Gop has been already stopped. If the Gop has been stopped, a new Gop will be created and will replace the old one in the Gop's index. ---- Gop ftp_ses On ftp_pdu Match (addr, addr, port, port) { Start (ftp_cmd=USER); }; Gop dns_req On dns_pdu Match (addr, addr, dns_id) { Start (dns_resp=0); }; Gop isup_leg On isup_pdu Match (m3pc, m3pc, cic) { Start (isup_msg=1); }; ---- If no +*Start*+ is given for a Gop, a Pdu whose AVPL matches an existing Gog's key will act as the start of a Gop. ====== What goes into the Gop's AVPL Once we know a Gop exists and the Pdu has been assigned to it, MATE will copy into the Gop's AVPL all the attributes matching the key plus any AVPs of the Pdu's AVPL matching the +*Extra*+ AVPL. ---- Gop ftp_ses On ftp_pdu Match (addr, addr, port, port) { Start (ftp_cmd=USER); Extra (pasv_prt, pasv_addr); }; Gop isup_leg On isup_pdu Match (m3pc, m3pc, cic) { Start (isup_msg=1); Extra (calling, called); }; ---- ====== End of a Gop Once the Pdu has been assigned to the Gop, MATE will check whether or not the Pdu matches the +*Stop*+, if it happens, MATE will mark the Gop as stopped. Even after stopped, a Gop may get assigned new Pdus matching its key, unless such Pdu matches +*Start*+. If it does, MATE will instead create a new Gop starting with that Pdu. ---- Gop ftp_ses On ftp_pdu Match (addr, addr, port, port) { Start (ftp_cmd=USER); Stop (ftp_cmd=QUIT); // The response to the QUIT command will be assigned to the same Gop Extra (pasv_prt, pasv_addr); }; Gop dns_req On dns_pdu Match (addr, addr, dns_id) { Start (dns_resp=0); Stop (dns_resp=1); }; Gop isup_leg On isup_pdu Match (m3pc, m3pc, cic) { Start (isup_msg=1); // IAM Stop (isup_msg=16); // RLC Extra (calling, called); }; ---- If no +*Stop*+ criterium is stated for a given Gop, the Gop will be stopped as soon as it is created. However, as with any other Gop, Pdus matching the Gop's key will still be assigned to the Gop unless they match a +*Start*+ condition, in which case a new Gop using the same key will be created. ===== Gop's tree For every frame containing a Pdu that belongs to a Gop, MATE will create a tree for that Gop. The example below represents the tree created by the +dns_pdu+ and +dns_req+ examples. ---- ... mate dns_pdu:6->dns_req:1 dns_pdu: 6 dns_pdu time: 2.103063 dns_pdu time since begining of Gop: 2.103063 dns_req: 1 dns_req Attributes dns_id: 36012 addr: 10.194.4.11 addr: 10.194.24.35 dns_req Times dns_req start time: 0.000000 dns_req hold time: 2.103063 dns_req duration: 2.103063 dns_req number of PDUs: 2 Start PDU: in frame 1 Stop PDU: in frame 6 (2.103063 : 2.103063) dns_pdu Attributes dns_resp: 1 dns_id: 36012 addr: 10.194.4.11 addr: 10.194.24.35 ---- Other than the pdu's tree, this one contains information regarding the relationship between the Pdus that belong to the Gop. That way we have: * mate.dns_req which contains the id of this dns_req Gop. This will be present in frames that belong to dns_req Gops. * mate.dns_req.dns_id and mate.dns_req.addr which represent the values of the attributes copied into the Gop. * the timers of the Gop ** mate.dns_req.StartTime time (in seconds) passed since beginning of capture until Gop's start. ** mate.dns_req.Time time passed between the start Pdu and the stop Pdu assigned to this Gop (only created if a Stop criterion has been declared for the Gop and a matching Pdu has arrived). ** mate.dns_req.Duration time passed between the start Pdu and the last Pdu assigned to this Gop. * mate.dns_req.NumOfPdus the number of Pdus that belong to this Gop ** a filterable list of frame numbers of the pdus of this Gop ====== Gop's timers Note that there are two "timers" for a Gop: * *Time*, which is defined only for Gops that have been Stopped, and gives the time passed between the +*Start*+ and the +*Stop*+ Pdus. * *Duration*, which is defined for every Gop regardles of its state, and give the time passed between its +*Start*+ Pdu and the last Pdu that was assigned to that Gop. So: * we can filter for Pdus that belong to Gops that have been Stopped with *mate.xxx.Time* * we can filter for Pdus that belong to unstopped Gops with *mate.xxx && mate.xxx.Time* * we can filter for Pdus that belong to stopped Gops using *mate.xxx.Duration* * we can filter for Pdus that belong to Gops that have taken more (or less) time that 0.5s to complete with *mate.xxx.Time > 0.5* (you can try these also as color filters to find out when response times start to grow) ===== Grouping Gops together (Gog) When Gops are created, or whenever their AVPL changes, Gops are (re)analyzed to check if they match an existent group of groups (Gog) or can create a new one. The Gop analysis is divided into two phases. In the first phase, the still unassigned Gop is checked to verify whether it belongs to an already existing Gog or may create a new one. The second phase eventually checks the Gog and registers its keys in the Gogs index. image::wsug_graphics/ws-mate-gop_analysis.png[] There are several reasons for the author to believe that this feature needs to be reimplemented, so probably there will be deep changes in the way this is done in the near future. This section of the documentation reflects the version of MATE as of wireshark 0.10.9; in future releases this will change. ====== Declaring a Group Of Groups The first thing we have to do configuring a Gog is to tell MATE that it exists. ---- Gog web_use { ... }; ---- ====== Telling MATE what could be a Gog member Then we have to tell MATE what to look for a match in the candidate Gops. ---- Gog web_use { Member http_ses (host); Member dns_req (host); }; ---- ====== Getting interesting data into the Gop Most often, also other attributes than those used for matching would be interesting. In order to copy from Gop to Gog other interesting attributes, we might use +*Extra*+ like we do for Gops. ---- Gog web_use { ... Extra (cookie); }; ---- ====== Gog's tree ---- mate http_pdu:4->http_req:2->http_use:1 http_pdu: 4 http_pdu time: 1.309847 http_pdu time since begining of Gop: 0.218930 http_req: 2 ... (the gop's tree for http_req: 2) .. http_use: 1 http_use Attributes host: www.example.com http_use Times http_use start time: 0.000000 http_use duration: 1.309847 number of GOPs: 3 dns_req: 1 ... (the gop's tree for dns_req: 1) .. http_req: 1 ... (the gop's tree for http_req: 1) .. http_req of current frame: 2 ---- We can filter on: * *mate.http_use.Duration* time elapsed between the first frame of a Gog and the last one assigned to it. * the attributess passed to the Gog ** *mate.http_use.host* ===== AVPL Transforms A Transform is a sequence of Match rules optionally completed with modification of the match result by an additional AVPL. Such modification may be an Insert (merge) or a Replace. Transforms can be used as helpers to manipulate an item's AVPL before it is processed further. They come to be very helpful in several cases. ====== Syntax AVPL Transformations are declared in the following way: ---- Transform name { Match [Strict|Every|Loose] match_avpl [Insert|Replace] modify_avpl ; ... }; ---- The *name* is the handle to the AVPL transformation. It is used to refer to the transform when invoking it later. The +*Match*+ declarations instruct MATE what and how to match against the data AVPL and how to modify the data AVPL if the match succeeds. They will be executed in the order they appear in the config file whenever they are invoked. The optional match mode qualifier (+*Strict*+, +*Every*+, or +*Loose*+) is used to choose the match mode as explained above; +*Strict*+ is a default value which may be omitted. The optional modification mode qualifier instructs MATE how the modify AVPL should be used: * the default value +*Insert*+ (which may be omitted) causes the +*modify_avpl*+ to be *merged* to the existing data AVPL, * the +*Replace*+ causes all the matching AVPs from the data AVPL to be *replaced* by the +*modify_avpl*+. The +*modify_avpl*+ may be an empty one; this comes useful in some cases for both +*Insert*+ and +*Replace*+ modification modes. Examples: ---- Transform insert_name_and { Match Strict (host=10.10.10.10, port=2345) Insert (name=JohnDoe); }; ---- adds name=JohnDoe to the data AVPL if it contains host=10.10.10.10 *and* port=2345 ---- Transform insert_name_or { Match Loose (host=10.10.10.10, port=2345) Insert (name=JohnDoe); }; ---- adds name=JohnDoe to the data AVPL if it contains host=10.10.10.10 *or* port=2345 ---- Transform replace_ip_address { Match (host=10.10.10.10) Replace (host=192.168.10.10); }; ---- replaces the original host=10.10.10.10 by host=192.168.10.10 ---- Transform add_ip_address { Match (host=10.10.10.10) (host=192.168.10.10); }; ---- adds (inserts) host=192.168.10.10 to the AVPL, keeping the original host=10.10.10.10 in it too ---- Transform replace_may_be_surprising { Match Loose (a=aaaa, b=bbbb) Replace (c=cccc, d=dddd); }; ---- gives the following results: * (a=aaaa, b=eeee) gets transformed to (b=eeee, c=cccc, d=dddd) because a=aaaa did match so it got replaced while b=eeee did not match so it has been left intact, * (a=aaaa, b=bbbb) gets transformed to (c=cccc, d=dddd) because both a=aaaa and b=bbbb did match. ====== Usage Once declared, Transforms can be added to the declarations of PDUs, Gops or Gogs. This is done by adding the +*Transform name_list*+ statement to the declaration: ---- Pdu my_proto_pdu Proto my_proto Transport ip { Extract addr From ip.addr; ... Transform my_pdu_transform[, other_pdu_transform[, yet_another_pdu_transform]]; }; ---- * In case of PDU, the list of transforms is applied against the PDU's AVPL after its creation. * In case of Gop and Gog, the list of transforms is applied against their respective AVPLs when they are created and every time they change. ===== Operation image::wsug_graphics/ws-mate-transform.png[] * A list of previously declared Transforms may be given to every Item (Pdu, Gop, or Gog), using the Transform statement. * Every time the AVPL of an item changes, it will be operated against *all* the Transforms on the list given to that item. The Transforms on the list are applied left to right. * Inside each of the Transforms, the item's AVPL will be operated against the Transform's Match clauses starting from the topmost one, until all have been tried or until one of them succeeds. MATE's Transforms can be used for many different things, like: ====== Multiple Start/Stop conditions for a Gop Using +*Transforms*+ we can add more than one start or stop condition to a Gop. ---- Transform start_cond { Match (attr1=aaa,attr2=bbb) (msg_type=start); Match (attr3=www,attr2=bbb) (msg_type=start); Match (attr5^a) (msg_type=stop); Match (attr6$z) (msg_type=stop); }; Pdu pdu ... { ... Transform start_cond; } Gop gop ... { Start (msg_type=start); Stop (msg_type=stop); ... } ---- ====== Marking Gops and Gogs to filter them easily ---- Transform marks { Match (addr=10.10.10.10, user=john) (john_at_host); Match (addr=10.10.10.10, user=tom) (tom_at_host); } ... Gop my_gop ... { ... Transform marks; } ---- After that we can use a display filter *mate.gop.john_at_host* or *mate.gop.tom_at_host* ====== Adding direction knowledge to MATE ---- Transform direction_as_text { Match (src=192.168.0.2, dst=192.168.0.3) Replace (direction=from_2_to_3); Match (src=192.168.0.3, dst=192.168.0.2) Replace (direction=from_3_to_2); }; Pdu my_pdu Proto my_proto Transport tcp/ip { Extract src From ip.src; Extract dst From ip.dst; Extract addr From ip.addr; Extract port From tcp.port; Extract start From tcp.flags.syn; Extract stop From tcp.flags.fin; Extract stop From tcp.flags.rst; Transform direction_as_text; } Gop my_gop On my_pdu Match (addr,addr,port,port) { ... Extra (direction); } ---- ====== NAT NAT can create problems when tracing, but we can easily worked around it by Transforming the NATed IP address and the Ethernet address of the router into the non-NAT address: ---- Transform denat { Match (addr=192.168.0.5, ether=01:02:03:04:05:06) Replace (addr=123.45.67.89); Match (addr=192.168.0.6, ether=01:02:03:04:05:06) Replace (addr=123.45.67.90); Match (addr=192.168.0.7, ether=01:02:03:04:05:06) Replace (addr=123.45.67.91); } Pdu my_pdu Proto my_proto transport tcp/ip/eth { Extract ether From eth.addr; Extract addr From ip.addr; Extract port From tcp.port; Transform denat; } ---- ==== About MATE MATE was originally written by Luis Ontanon, a Telecomunications 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. [[ChMateConfigurationTutorial]] === MATE's configuration tutorial We'll show a MATE configuration that first creates Gops for every DNS and HTTP request, then it ties the Gops together in a Gop based on the host. Finally we'll separate into different Gogs request coming from different users. With this MATE configuration loaded we can: * use *mate.http_use.Duration > 5.5* to filter frames based on the time it takes to load a complete page from the DNS request to resolve its name until the last image gets loaded. * use *mate.http_use.client == "10.10.10.20" && mate.http_use.host == "www.example.com"* to isolate DNS and HTTP packets related to a visit of a certain user. * use *mate.http_req.Duration > 1.5* to filter all the packets of HTTP requests that take more than 1.5 seconds to complete. The complete config file is here: https://wiki.wireshark.org/Mate/Examples?action=AttachFile&do=view&target=web.mate[web.mate] Note: for this example I used _dns.qry.name_ which is defined since Wireshark version 0.10.9. Supposing you have a mate plugin already installed you can test it with the current Wireshark version. ==== A Gop for DNS requests First we'll tell MATE how to create a Gop for each DNS request/response. MATE needs to know what makes a DNS PDU. We describe it this using a Pdu declaration: ---- Pdu dns_pdu Proto dns Transport ip { Extract addr From ip.addr; Extract dns_id From dns.id; Extract dns_resp From dns.flags.response; }; ---- Using +*Proto dns*+ we tell MATE to create Pdus every time it finds *dns*. Using +*Transport ip*+ we inform MATE that some of the fields we are interested are in the *ip* part of the frame. Finally, we tell MATE to import _ip.addr_ as +*addr*+, _dns.id_ as +*dns_id*+ and _dns.flags.response_ as +*dns_resp*+. Once we've told MATE how to extract +*dns_pdus*+ we'll tell it how to match requests and responses and group them into a Gop. For this we'll use a +*Gop*+ declaration to define the Gop, and then, +*Start*+ and +*Stop*+ statements to tell it when the Gop starts and ends. ---- Gop dns_req On dns_pdu Match (addr,addr,dns_id) { Start (dns_resp=0); Stop (dns_resp=1); }; ---- Using the *Gop* declaration we tell MATE that the *Name* of the Gop is _dns_req_, that _dns_pdus_ can become members of the Gop, and what is the key used to match the Pdus to the Gop. The key for this Gop is _"addr, addr, dns_id"_. That means that in order to belong to the same Gop, _dns_pdus_ have to have both addresses and the _request id_ identical. We then instruct MATE that a _dns_req_ starts whenever a _dns_pdu_ matches _"dns_resp=0"_ and that it stops when another _dns_pdu_ matches _"dns_resp=1"_. At this point, if we open a capture file using this configuration, we are able to use a display filter *mate.dns_req.Time > 1* to see only the packets of DNS requests that take more than one second to complete. We can use a display filter *mate.dns_req && ! mate.dns_req.Time* to find requests for which no response was given. *mate.xxx.Time* is set only for Gops that have being stopped. ==== A Gop for HTTP requests This other example creates a Gop for every HTTP request. ---- Pdu http_pdu Proto http Transport tcp/ip { Extract addr From ip.addr; Extract port From tcp.port; Extract http_rq From http.request.method; Extract http_rs From http.response; DiscardPduData true; }; Gop http_req On http_pdu Match (addr, addr, port, port) { Start (http_rq); Stop (http_rs); }; ---- So, if we open a capture using this configuration * filtering with *mate.http_req.Time > 1* will give all the requests where the response header takes more than one second to come * filtering with *mate.http_req.Duration > 1.5* will show those request that take more than 1.5 seconds to complete. You have to know that *mate.xxx.Time* gives the time in seconds between the pdu matching the GopStart and the Pdu matching the GopStop (yes, you can create timers using this!). On the other hand, *mate.xxx.Duration* gives you the time passed between the GopStart and the last pdu assigned to that Gop regardless whether it is a stop or not. After the GopStop, Pdus matching the Gop's Key will still be assigned to the same Gop as far as they don't match the GopStart, in which case a new Gop with the same key will be created. ==== Getting DNS and HTTP together into a Gog We'll tie together to a single Gog all the http packets belonging to requests and responses to a certain host and the dns request and response used to resolve its domain name using the Pdu and Gop definitions of the previous examples To be able to group DNS and HTTP requests together, we need to import into the Pdus and Gops some part of information that both those protocols share. Once the Pdus and Gops have been defined, we can use +*Extract*+ (for Pdus) and +*Extract*+ (for Gops) statements to tell MATE what other protocol fields are to be added to Pdus' and Gops' AVPLs. We add the following statements to the appropriate declarations: ---- Extract host From http.host; // to Pdu http_pdu as the last Extract in the list Extra (host); // to Gop http_req after the Stop Extract host From dns.qry.name; // to Pdu dns_pdu as the last Extract in the list Extra (host); // to Gop dns_req after the Stop ---- Here we've told MATE to import _http.host_ into +*http_pdu*+ and _dns.qry.name_ into +*dns_pdu*+ as +*host*+. We also have to tell MATE to copy the +*host*+ attribute from the Pdus to the Gops, we do this using +*Extra*+. Once we've got all the data we need in Pdus and Gops, we tell MATE what makes different Gops belong to a certain Gog. ---- Gog http_use { Member http_req (host); Member dns_req (host); Expiration 0.75; }; ---- Using the +*Gog*+ declaration we tell MATE to define a Gog type +*Named*+ _http_use_ whose expiration is 0.75 seconds after all the Gops that belong to it had been stopped. After that time, an eventual new Gop with the same key match will create a new Gog instead of been added to the previous Gog. Using the +*Member*+ statements we tell MATE that *http_req*s with the same *host* belong to the same Gog, same thing for *dns_req*s. So far we have instructed mate to group every packet related to sessions towards a certain host. At this point if we open a capture file and: * a display filter *mate.http_use.Duration > 5* will show only those requests that have taken more than 5 seconds to complete starting from the DNS request and ending with the last packet of the http responses. * a display filter *mate.http_use.host == "www.w3c.org"* will show all the packets (both DNS and HTTP) related to the requests directed to www.w3c.org ==== Separating requests from multiple users "Houston: we've had a problem here." This configuration works fine if used for captures taken at the client's side but deeper in the network we'd got a real mess. Requests from many users get mixed together into +*http_uses*+. Gogs are created and stopped almost randomly (depending on the timing in which Gops start and stop). How do we get requests from individual users separated from each other? MATE has a tool that can be used to resolve this kind of grouping issues. This tool are the +*Transforms*+. Once defined, they can be applied against Pdus, Gops and Gogs and they might replace or insert more attributes based on what's there. We'll use them to create an attribute named client, using which we'll separate different requests. For DNS we need the ip.src of the request moved into the Gop only from the DNS request. So we first tell MATE to import ip.src as client: ---- Extract client From ip.src; ---- Next, we tell MATE to replace ( *dns_resp=1, client* ) with just *dns_resp=1* in the Pdu. That way, we'll keep the attribute *client* only in the DNS request Pdus (i.e. packets coming from the client).To do so, we have to add a +*Transform*+ declaration (in this case, with just one clause) before the Pdu declaration which uses it: ---- Transform rm_client_from_dns_resp { Match (dns_resp=1, client) Replace (dns_resp=1); }; ---- Next, we invoke the transform by adding the following line after the +*Extract*+ list of the dns_pdu Pdu: ---- Transform rm_client_from_dns_resp; ---- HTTP is a little trickier. We have to remove the attribute carrying ip.src from both the response and the "continuations" of the response, but as there is nothing to filter on for the continuations, we have to add a fake attribute first. And then we have to remove client when the fake attribute appears. This is possible due to the fact that the +*Match*+ clauses in the +*Transform*+ are executed one by one until one of them succeeds. First, we declare another two +*Transforms*+: ---- Transform rm_client_from_http_resp1 { Match (http_rq); //first match wins so the request won't get the not_rq attribute inserted Match Every (addr) Insert (not_rq); //this line won't be evaluated if the first one matched so not_rq won't be inserted to requests }; Transform rm_client_from_http_resp2 { Match (not_rq, client) Replace (); //replace "client and not_rq" with nothing (will happen only in the response and eventual parts of it) }; ---- Next, we add another +*Extract*+ statement to the +*http_pdu*+ declaration, and apply both +*Transforms*+ declared above in a proper order: ---- Extract client From ip.src; Transform rm_client_from_http_resp1, rm_client_from_http_resp2; ---- In MATE, all the +*Transform*+s listed for an item will be evaluated, while inside a single +*Transform*+, the evaluation will stop at the first successful +*Match*+ clause. That's why we first just match _http_rq_ to get out of the first sequence before adding the _not_rq_ attribute. Then we apply the second +*Transform*+ which removes both _not_rq_ and _client_ if both are there. Yes, +*Transform*+s are cumbersome, but they are very useful. Once we got all what we need in the Pdus, we have to tell MATE to copy the attribute _client_ from the Pdus to the respective Gops, by adding client to +*Extra*+ lists of both Gop declarations: ---- Extra (host, client); ---- On top of that, we need to modify the old declarations of Gop key to new ones that include both _client_ and _host_. So we change the Gog *Member* declarations the following way: ---- Member http_req (host, client); Member dns_req (host, client); ---- Now we got it, every "usage" gets it's own Gog. [[ChMateConfigurationExamples]] === MATE configuration examples The following is a collection of various configuration examples for MATE. Many of them are useless because the "conversations" facility does a better job. Anyway they are meant to help users understanding how to configure MATE. ==== TCP session The following example creates a GoP out of every TCP session. ---- Pdu tcp_pdu Proto tcp Transport ip { Extract addr From ip.addr; Extract port From tcp.port; Extract tcp_start From tcp.flags.syn; Extract tcp_stop From tcp.flags.reset; Extract tcp_stop From tcp.flags.fin; }; Gop tcp_ses On tcp_pdu Match (addr, addr, port, port) { Start (tcp_start=1); Stop (tcp_stop=1); }; Done; ---- This probably would do fine in 99.9% of the cases but 10.0.0.1:20->10.0.0.2:22 and 10.0.0.1:22->10.0.0.2:20 would both fall into the same gop if they happen to overlap in time. * filtering with *mate.tcp_ses.Time > 1* will give all the sessions that last less than one second * filtering with *mate.tcp_ses.NumOfPdus < 5* will show all tcp sessions that have less than 5 packets. * filtering with *mate.tcp_ses.Id == 3* will show all the packets for the third tcp session MATE has found ==== a Gog for a complete FTP session This configuration allows to tie a complete passive ftp session (including the data transfer) in a single Gog. ---- Pdu ftp_pdu Proto ftp Transport tcp/ip { Extract ftp_addr From ip.addr; Extract ftp_port From tcp.port; Extract ftp_resp From ftp.response.code; Extract ftp_req From ftp.request.command; Extract server_addr From ftp.passive.ip; Extract server_port From ftp.passive.port; LastPdu; }; Pdu ftp_data_pdu Proto ftp-data Transport tcp/ip{ Extract server_addr From ip.src; Extract server_port From tcp.srcport; }; Gop ftp_data On ftp_data_pdu (server_addr, server_port) { Start (server_addr); }; Gop ftp_ctl On ftp_pdu (ftp_addr, ftp_addr, ftp_port, ftp_port) { Start (ftp_resp=220); Stop (ftp_resp=221); Extra (server_addr, server_port); }; Gog ftp_ses { Member ftp_ctl (ftp_addr, ftp_addr, ftp_port, ftp_port); Member ftp_data (server_addr, server_port); }; Done; ---- Note: not having anything to distinguish between ftp-data packets makes this config to create one Gop for every ftp-data packet instead of each transfer. Pre-started Gops would avoid this. ==== using RADIUS to filter SMTP traffic of a specific user Spying on people, in addition to being immoral, is illegal in many countries. This is an example meant to explain how to do it not an invitation to do so. It's up to the police to do this kind of job when there is a good reason to do so. ---- Pdu radius_pdu On radius Transport udp/ip { Extract addr From ip.addr; Extract port From udp.port; Extract radius_id From radius.id; Extract radius_code From radius.code; Extract user_ip From radius.framed_addr; Extract username From radius.username; } Gop radius_req On radius_pdu (radius_id, addr, addr, port, port) { Start (radius_code {1|4|7} ); Stop (radius_code {2|3|5|8|9} ); Extra (user_ip, username); } // we define the smtp traffic we want to filter Pdu user_smtp Proto smtp Transport tcp/ip { Extract user_ip From ip.addr; Extract smtp_port From tcp.port; Extract tcp_start From tcp.flags.syn; Extract tcp_stop From tcp.flags.reset; } Gop user_smtp_ses On user_smtp (user_ip, user_ip, smtp_port!25) { Start (tcp_start=1); Stop (tcp_stop=1); } // with the following group of groups we'll group toghether the radius and the smtp // we set a long expiration to avoid the session expire on long pauses. Gog user_mail { Expiration 1800; Member radius_req (user_ip); Member user_smtp_ses (user_ip); Extra (username); } Done; ---- Filtering the capture file with *mate.user_mail.username == "theuser"* will filter the radius packets and smtp traffic for _"theuser"_. ==== H323 Calls This configuration will create a Gog out of every call. ---- Pdu q931 Proto q931 Transport ip { Extract addr From ip.addr; Extract call_ref From q931.call_ref; Extract q931_msg From q931.message_type; Extract calling From q931.calling_party_number.digits; Extract called From q931.called_party_number.digits; Extract guid From h225.guid; Extract q931_cause From q931.cause_value; }; Gop q931_leg On q931 Match (addr, addr, call_ref) { Start (q931_msg=5); Stop (q931_msg=90); Extra (calling, called, guid, q931_cuase); }; Pdu ras Proto h225.RasMessage Transport ip { Extract addr From ip.addr; Extract ras_sn From h225.requestSeqNum; Extract ras_msg From h225.RasMessage; Extract guid From h225.guid; }; Gop ras_req On ras Match (addr, addr, ras_sn) { Start (ras_msg {0|3|6|9|12|15|18|21|26|30} ); Stop (ras_msg {1|2|4|5|7|8|10|11|13|14|16|17|19|20|22|24|27|28|29|31}); Extra (guid); }; Gog call { Member ras_req (guid); Member q931_leg (guid); Extra (called,calling,q931_cause); }; Done; ---- with this we can: * filter all signalling for a specific caller: *mate.call.caller == "123456789"* * filter all signalling for calls with a specific release cause: *mate.call.q931_cause == 31* * filter all signalling for very short calls: *mate.q931_leg.Time < 5* ==== MMS With this example, all the components of an MMS send or receive will be tied into a single Gog. Note that this example uses the +*Payload*+ clause because MMS delivery uses MMSE over either HTTP or WSP. As it is not possible to relate the retrieve request to a response by the means of MMSE only (the request is just an HTTP GET without any MMSE), a Gop is made of HTTP Pdus but MMSE data need to be extracted from the bodies. ---- ## WARNING: this example has been blindly translated from the "old" MATE syntax ## and it has been verified that Wireshark accepts it. However, it has not been ## tested against any capture file due to lack of the latter. Transform rm_client_from_http_resp1 { Match (http_rq); Match Every (addr) Insert (not_rq); }; Transform rm_client_from_http_resp2 { Match (not_rq,ue) Replace (); }; Pdu mmse_over_http_pdu Proto http Transport tcp/ip { Payload mmse; Extract addr From ip.addr; Extract port From tcp.port; Extract http_rq From http.request; Extract content From http.content_type; Extract resp From http.response.code; Extract method From http.request.method; Extract host From http.host; Extract content From http.content_type; Extract trx From mmse.transaction_id; Extract msg_type From mmse.message_type; Extract notify_status From mmse.status; Extract send_status From mmse.response_status; Transform rm_client_from_http_resp1, rm_client_from_http_resp2; }; Gop mmse_over_http On mmse_over_http_pdu Match (addr, addr, port, port) { Start (http_rq); Stop (http_rs); Extra (host, ue, resp, notify_status, send_status, trx); }; Transform mms_start { Match Loose() Insert (mms_start); }; Pdu mmse_over_wsp_pdu Proto wsp Transport ip { Payload mmse; Extract trx From mmse.transaction_id; Extract msg_type From mmse.message_type; Extract notify_status From mmse.status; Extract send_status From mmse.response_status; Transform mms_start; }; Gop mmse_over_wsp On mmse_over_wsp_pdu Match (trx) { Start (mms_start); Stop (never); Extra (ue, notify_status, send_status); }; Gog mms { Member mmse_over_http (trx); Member mmse_over_wsp (trx); Extra (ue, notify_status, send_status, resp, host, trx); Expiration 60.0; }; ---- [[ChMateConfigurationLibrary]] === MATE's configuration library The MATE library (will) contains GoP definitions for several protocols. Library protocols are included in your MATE config using: ++*Action=Include; Lib=proto_name;*++. For Every protocol with a library entry, we'll find defined what from the PDU is needed to create a GoP for that protocol, eventually any criteria and the very essential GoP definition (i.e. ++*GopDef*++, +*GopStart*+ and +*GopStop*+). [NOTE] ==== It seems that this code is written in the old syntax of MATE. So far it has not been transcribed into the new format. It may still form the basis to recreate these in the new format. ==== ==== General use protocols ===== TCP It will create a GoP for every TCP session, If it is used it should be the last one in the list. And every other proto on top of TCP should be declared with +*Stop=TRUE;*+ so the a TCP PDU is not created where we got already one going on. ---- Action=PduDef; Name=tcp_pdu; Proto=tcp; Transport=ip; addr=ip.addr; port=tcp.port; tcp_start=tcp.flags.syn; tcp_stop=tcp.flags.fin; tcp_stop=tcp.flags.reset; Action=GopDef; Name=tcp_session; On=tcp_pdu; addr; addr; port; port; Action=GopStart; For=tcp_session; tcp_start=1; Action=GopStop; For=tcp_session; tcp_stop=1; ---- ===== DNS will create a GoP containing every request and it's response (eventually retransmissions too). ---- Action=PduDef; Name=dns_pdu; Proto=dns; Transport=udp/ip; addr=ip.addr; port=udp.port; dns_id=dns.id; dns_rsp=dns.flags.response; Action=GopDef; Name=dns_req; On=dns_pdu; addr; addr; port!53; dns_id; Action=GopStart; For=dns_req; dns_rsp=0; Action=GopStop; For=dns_req; dns_rsp=1; ---- ===== RADIUS A Gop for every transaction. ---- Action=PduDef; Name=radius_pdu; Proto=radius; Transport=udp/ip; addr=ip.addr; port=udp.port; radius_id=radius.id; radius_code=radius.code; Action=GopDef; Name=radius_req; On=radius_pdu; radius_id; addr; addr; port; port; Action=GopStart; For=radius_req; radius_code|1|4|7; Action=GopStop; For=radius_req; radius_code|2|3|5|8|9; ---- ===== RTSP ---- Action=PduDef; Name=rtsp_pdu; Proto=rtsp; Transport=tcp/ip; addr=ip.addr; port=tcp.port; rtsp_method=rtsp.method; Action=PduExtra; For=rtsp_pdu; rtsp_ses=rtsp.session; rtsp_url=rtsp.url; Action=GopDef; Name=rtsp_ses; On=rtsp_pdu; addr; addr; port; port; Action=GopStart; For=rtsp_ses; rtsp_method=DESCRIBE; Action=GopStop; For=rtsp_ses; rtsp_method=TEARDOWN; Action=GopExtra; For=rtsp_ses; rtsp_ses; rtsp_url; ---- ==== VoIP/Telephony Most protocol definitions here will create one Gop for every Call Leg unless stated. ===== ISUP ---- Action=PduDef; Name=isup_pdu; Proto=isup; Transport=mtp3; mtp3pc=mtp3.dpc; mtp3pc=mtp3.opc; cic=isup.cic; isup_msg=isup.message_type; Action=GopDef; Name=isup_leg; On=isup_pdu; ShowPduTree=TRUE; mtp3pc; mtp3pc; cic; Action=GopStart; For=isup_leg; isup_msg=1; Action=GopStop; For=isup_leg; isup_msg=16; ---- ===== Q931 ---- Action=PduDef; Name=q931_pdu; Proto=q931; Stop=TRUE; Transport=tcp/ip; addr=ip.addr; call_ref=q931.call_ref; q931_msg=q931.message_type; Action=GopDef; Name=q931_leg; On=q931_pdu; addr; addr; call_ref; Action=GopStart; For=q931_leg; q931_msg=5; Action=GopStop; For=q931_leg; q931_msg=90; ---- ===== H225 RAS ---- Action=PduDef; Name=ras_pdu; Proto=h225.RasMessage; Transport=udp/ip; addr=ip.addr; ras_sn=h225.RequestSeqNum; ras_msg=h225.RasMessage; Action=PduExtra; For=ras_pdu; guid=h225.guid; Action=GopDef; Name=ras_leg; On=ras_pdu; addr; addr; ras_sn; Action=GopStart; For=ras_leg; ras_msg|0|3|6|9|12|15|18|21|26|30; Action=GopStop; For=ras_leg; ras_msg|1|2|4|5|7|8|10|11|13|14|16|17|19|20|22|24|27|28|29|31; Action=GopExtra; For=ras_leg; guid; ---- ===== SIP ---- Action=PduDef; Proto=sip_pdu; Transport=tcp/ip; addr=ip.addr; port=tcp.port; sip_method=sip.Method; sip_callid=sip.Call-ID; calling=sdp.owner.username; Action=GopDef; Name=sip_leg; On=sip_pdu; addr; addr; port; port; Action=GopStart; For=sip; sip_method=INVITE; Action=GopStop; For=sip; sip_method=BYE; ---- ===== MEGACO Will create a Gop out of every transaction. To "tie" them to your call's GoG use: +*Action=GogKey; Name=your_call; On=mgc_tr; addr!mgc_addr; megaco_ctx;*+ ---- Action=PduDef; Name=mgc_pdu; Proto=megaco; Transport=ip; addr=ip.addr; megaco_ctx=megaco.context; megaco_trx=megaco.transid; megaco_msg=megaco.transaction; term=megaco.termid; Action=GopDef; Name=mgc_tr; On=mgc_pdu; addr; addr; megaco_trx; Action=GopStart; For=mgc_tr; megaco_msg|Request|Notify; Action=GopStop; For=mgc_tr; megaco_msg=Reply; Action=GopExtra; For=mgc_tr; term^DS1; megaco_ctx!Choose one; ---- [[ChMateReferenceManual]] === MATE's 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: * <> +*=*+ test for equality, that is: either the value strings are identical or the match will fail. * <> +*!*+ will match only if the value strings aren't equal. * <> +*{}*+ 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. * <> +*^*+ will match if the configuration value string matches the first characters of the data AVP's value string. * <> +*$*+ will match if the configuration value string matches the last characters of the data AVP's value string. * <> +*~*+ will match if the configuration value string matches a substring of the characters of the data AVP's value string. * <> +*<*+ will match if the data AVP's value string is semantically lower than the configuration value string. * <> +*>*+ will match if the data AVP's value string is semantically higher than the configuration value string. * <> +*?*+ (can be omitted) will match if the AVP name matches, regardless what the value string is. [[Equal]] ====== Equal AVP Operator 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 [[NotEqual]] ====== Not equal AVP operator 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 [[OneOf]] ====== "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. Example:: attrib=1 matches attrib{1|2|3} + attrib=2 matches attrib{1|2|3} + attrib=4 does not match attrib{1|2|3} [[StartsWith]] ====== "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. 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 + [[EndsWith]] ====== "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. Example:: attrib=wxyz matches attrib$xyz + attrib=yz does not match attrib$xyz + attrib=abc...wxyz does not match attrib$abc [[Contains]] ====== Contains operator 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 [[LowerThan]] ====== "Lower than" operator The "lower than" operator will match if the data AVP value is semantically lower than the configuration AVP value. Example:: attrib=abc matches attribabc + 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]] ====== 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 just an alternative notation of 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 <> 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'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 <>. 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 <>s, 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 <> is <> to the data AVPL of the Pdu/GoP/GoG. * <>: 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. * <>: 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. * <>: 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. [[Loose]] ====== Loose Match 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 <>'s AVPL to merge the result into <>'s AVPL, and against <>'s AVPL to merge the result into <>'s AVPL. They may also be used in <> and <>s. [NOTE] ==== As of current (2.0.1), Loose Match does not work as described here, see https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=12184[Bug 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! [[Every]] ====== Every 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 <> and <>s. [NOTE] ==== As of current (2.0.1), Loose Match does not work as described here, see https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=12184[Bug 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! [[Strict]] ====== Strict 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 <> and <>s. 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! [[Merge]] ====== AVPL Merge 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 <> 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) [[Transform]] ====== Transforms 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 <> 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. [[Config]] === Configuration AVPLs [[Pdu]] ==== Pdsu's configuration actions The following configuration AVPLs deal with PDU creation and data extraction. ===== 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 }; ---- ===== 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. ====== 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). ====== 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 choosen 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. ====== 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). ====== 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. [[Criteria]] ====== 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. ====== 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. ====== 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. ====== 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. [[Gop]] ===== 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 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. ====== On clause The +name+ of Pdus which this type of Gop is supposed to be groupping. It is mandatory. ====== 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. ====== 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. ====== 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. ====== 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. ====== 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. ====== 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. ====== 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. ====== 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. ====== 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. ====== 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 ====== 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. [[Gog]] ===== 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 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. ====== 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. ====== 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. ====== 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. ====== 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. ====== TreeMode clause Controls the display of Gops subtree of the Gog: * +NoTree+: completely suppresses showing the tree * +BasicTree+: needs investigation * +FullTree+: needs investigation ====== 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. ===== 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 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. ====== 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 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. ====== 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). ====== 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). ====== 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). ====== 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). ====== 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.