ProtoSpecs XML Writing Guidelines

Doc version 5.5.0.2
Last revised 04/30/2004

for AiroPeek/AiroPeek NX v2.0 or higher, EtherPeek v5.1 or higher, EtherPeek NX v2.1 or higher, GigaPeek NX v1.0 or higher,
Omni� v1.0 or higher, WANPeek NX v1.0 or higher

The file of interest for adding protocols to the ProtoSpec protocol hierarchy is PSpecs.xml. The location of this file is dependent on the LiveAction product being used. For the Peek applications, which include AiroPeek, AiroPeek NX, EtherPeek, EtherPeek NX, GigaPeek NX, Omnipeek local captures, and WANPeek NX, this file is located in a language specific folder (by language ID, for instance the 1033 folder for the English version) in the program's installation folder. The default location of this program installation folder is C:\Program Files\LiveAction\[product]. For Omni�, which includes Omnipeek remote captures and the Omni� Engine, this file is located in a common file folder. The default location of this common file folder is C:\Program Files\Common Files\LiveAction.

Before opening or modifying these files, it is recommended that you make a backup copy of the PSpecs.xml file, in case your modified copy becomes unusable by your Peek application or Omni� Engine.

In order to add a protocol to the ProtoSpec hierarchy, you will need to add specifically formatted information to the PSpecs.xml file. This PSpecs.xml file for the Peek application must remain in the language specific folder corresponding to your system's language settings. This file must remain in its original location for the Omni� Engine.

Once you have made a backup copy of the PSpecs.xml file, familiarize yourself with the format of a ProtoSpec definition by examining the XML file.

General format of PSpecs.xml:

<PSpec Name="IEEE 802.3">
<PSpecID>1</PSpecID>
<LName>IEEE 802.3 CSMA/CD Ethernet</LName>
<SName>802.3</SName>
<Desc>802.3 is a comprehensive standard for Local Area Networks employing the Carrier Sense Multiple Access with Collision Detection (CSMA/CD) access method. Under the International Standards Organization (ISO) the 10 megabits per second transmission speed is specified by ISO/DIS 8802/3. The definition of Ethernet under 802.3 supersedes the previous Ethernet standard known as Ethernet Type 2. In terms of data bytes in the protocol stack, 802.3 uses bytes 13 and 14 as a length field, whereas the earlier standard used these bytes as a protocol definition field.</Desc>
<Color>color_1</Color>
<CondExp><![CDATA[ MLD16[12] <= 1500 ]]></CondExp>
<NextLayer>
<Exp><![CDATA[ 14 ]]></Exp>
</NextLayer>
<Link Name="802.2 LLC"/>
</PSpec>

Each PSpec element block is made up of the following items:

PSpec - starts a new ProtoSpec node. This element can contain the following attributes:
- Name - Hierarchical name for the ProtoSpec.
- Type - used at the root level only. Type="CommonTable" implies that this node contains common elements for sharing with other nodes.
- Sort - Setting Sort="First" forces this element to be created first in the protocol list. Sort="Last" does the opposite. No attribute implies that the given order should be used.
PSpecID - a 16-bit identifier for the ProtoSpec, in most cases a unique number throughout the file. This may be shared between different definitions when the definitions should be considered the same protocol. See the IPv6 definitions for an example.
LName - Long name of the protocol.
SName - Short name of the protocol.
Desc - [optional] Description for the protocol.
DescID - [optional] Protocol ID from which to obtain the description.
Color - [optional] Color for the protocol. If not specified the application will use the parent's color.
CondExp - [optional] A conditional expression to evaluate if a packet matches this protocol definition. The expression is evaluated to true (or != 0) or false (== 0). See the description of expressions below for more details.
NextLayer - [optional] An element with the following children:
- Exp - A numeric expression used to determine the size of the protocol's header. See the description of expressions below for more details.
- Special - Instructs the ProtoSpecs library to use one of its internal functions to determine where the next layer starts. Currently, these functions are:
  - MPLS - determines the bottom-of-stack assuming that the current layer is MPLS data.
Definitions - [optional] An element with the following children:
- Define - Defines a literal substitution for sub protocol expressions, much like a C #define. Define has 2 children:
  - Name - The name of the definition.
  - Value - The expression to substitute for in expressions containing Name.
NotChild - [optional] used to prevent recursive protocol definitions. This element can contain the following attribute:
- Name - the hierarchical name of the protocol to not include as a subprotocol.
Link - [optional] An element with the following children:
- Name - the hierarchical name of a CommonTable to include as children of this protocol.

Expressions

Expressions are C style mathematical expressions geared toward analyzing packets. In addition to C style mathematical operators (+, -, <, etc.), there are special operations that examine packet data:

PLDX[Y] - ParentLayerData; starting from the header layer of the parent protocol, examine "X" bits at byte offset Y in network byte order. Possible values for X are 8, 16, 24, and 32. For example, PLD8[3] evaluates to the value of the byte at offset 3 from the start of the parent layer's header.
MLDX[Y] - MyLayerData; starting from the payload layer of the parent protocol, examine "X" bits at byte offset Y in network byte order. Possible values for X are 8, 16, 24, and 32. For example, MLD8[3] evaluates to the value of the byte at offset 3 from the start of the parent layer's payload.

ProtoSpec Tree Generation

The ProtoSpec tree is generated from the XML by walking the tree from each root element and adding each element, element's children, and the children of any links included in any element. A 32-bit ProtoSpec instance ID is generated for each element in the tree; the lower 16 bits consist of the PSpecID value, and the upper 16 bits are an instance counter, incremented for each time an element is included in the tree. All ProtoSpec IDs passed to Peek Analysis Modules are 32 bit instance IDs. Peek Analysis Modules generally examine the lower 16 bits to determine the actual protocol, and list the 16 bit PSpecIDs in the Supported ProtoSpecs array. The 32 bit ID is used for determining the parent protocol list, determining the header and payload locations for each protocol, etc. ProtoSpec IDs are used in a similar manner for Omni� Distributed Analysis Modules.

Notes and Tips

MPLS and VLAN
MPLS over VLAN and VLAN over MPLS are disabled by default in the shipping PSpecs.xml file. As VLAN and MPLS protocols can encapsulate many different kinds of protocols, including entire Ethernet packets, including them will inhibit load time performance, as well as increase the overall memory required for the ProtoSpecs library. To enable you must remove the appropriate NotChild tag under either MPLS or VLAN PSpec definitions. For instance, if you wish to enable MPLS over VLAN, remove or comment out the <NotChild Name="VLAN"> text in the MPLS PSpec definition.
Omni� Engine and Omnipeek
Both the Omni� Engine and Omnipeek make use of the PSpecs.xml file. There can be two or three different copies of this file for Omni�, depending on the Omni� configuration. If the Omni� Engine and Omnipeek are running on the same computer, there are two copies of the file: the first copy is for Omnipeek local captures and the second copy is for Omnipeek remote captures and the Omni� Engine (located in a different folder from the first copy). If the Omni� Engine and Omnipeek are running on different computers, there are three copies of the file: the first copy is for Omnipeek local captures, the second copy is for Omnipeek remote captures (located on the same computer but in a different folder from the first copy), and the third copy is for the Omni� Engine (located on a different computer from Omnipeek). Any changes made to one of these files should be made to the other files. There is no automatic synchronization of changes made to any of these files, you must manually make the changes to all the files separately. The location of these files is specified at the beginning of this document.