NetPDL Visualization Extension

A tool that has to inspect network packets for visualizing its hex dump in a human-readable form can choose between two different views:

  • a summary view, in which the most important fields of each packet are shown (for example source and destination address)
  • a detailed view, in which all the fields are shown, each one with the most detailed information available.

The NetPDL Visualization Extension supports both these views.

Note: the NetPDL Visualization Extension is not a mandatory part of the NetPDL Specification. This document will define new elements and new attributes that can be used to display decoded packets; the NetPDL engines that do not support this specification will simply ignore these new items.

Defining visualization primitives: the <visualization> element

This section presents the general structure of the NetPDL Visualization Extension.

Most of the times, the additional information needed to print some protocol field does not have any meaning outside the current protocol. For instance, the fact that a value of ”1” of the opcode field in an ARP packet corresponds to a Request command is not of interest of other protocols. It follows that this information can be placed locally to the ARP protocol.

However, sometimes there is the need to make some information available to more than one protocol. This is, for example, for the information related to the vendor of a NIC card, which can be derived from the MAC address. This information can be useful for all the protocols that have one field that transports MAC addresses: link layer protocols (Ethernet, Token Ring, …), but also ARP, DHCP, and others. It follows that this information should be shared among several protocols.

The <visualization> element can be present in two positions:

  • as a child of the root <netpdl> element: this solution allows the visualization primitives to be used from several protocols; the visualization information is defined once and it is accessible from any protocol inside the NetPDL document.
  • as a child of the <protocol> element: in this case the information will be visible only within the current protocol. This solution is more appropriate for “exoteric” visualization primitives that are used only by a given protocol.

This element does not have any attributes and it can have the following child elements:

ElementsDescription
<showtemplate>It defines the template that has to be used to format properly a given protocol field. For instance, a template can be display this field as an IP address.
<showsumtemplate>It defines the template that has to be used to display the most important information for a protocol or a block (i.e. the summary view). For instance, a template can be display the protocol name and its version number.

The <netpdlshow> element can be placed into a piece of XML code that looks like:

  <netpdl>
    <protocol...>

      ...
      <visualization>
        <!-- Definitions local to the current protocol -->
        <showtemplate ... />
        <showtemplate ... />
          ...
        <showsumtemplate ... />

    </visualization>
    </protocol>
    ...

    <visualization>
      <!-- Definitions valid for the entire NetPDL document -->
      <showtemplate ... />
      <showtemplate ... />

        ...
      <showsumtemplate ... />
      <showsumtemplate ... />
        ...
        ...
    </visualization>
  </netpdl>

Data associated to each NetPDL field

When visualization extension is used, a NetPDL engine must create the following internal variables (that are completely different from the ones defined in NetPDL expressions) associated to each NetPDL field (<field>):

Visualization Internal VariableDescription
name (always present)It contains the value associated to the name attribute of the NetPDL field.
longname (always present)It contains the value associated to the longname attribute of the NetPDL field.
value (always present)It contains the field value as an hex string. In other words, the content of the value attribute in case of a 16 bit field whose value is 0800 (hex) is the string 0800. This value is exactly the same as written in the hex file, i.e. it does not change in case of little-endian or big-endian fields. Please note that for bitmasked fields, this value corresponds to the 'unmasked' value (i.e. the real field value must be derived from a bitwise AND operation between the mask and the value).
showvalue (always present)It contains the field value in a “printable” form. For instance, field value ffffffffffff (related to a MAC address) can be associated to value ffffff-ffffff and assigned to this attribute.
mask (may be missing)It contains the mask that has to be applied to the value field in order to get the real value of the field. This variable is used only in case of 'bit' fields, which do not span over byte boundaries, and it contains the value as an hex string.
size (always present)It contains the actual size (in byte) of the current NetPDL element (either a field or a protocol).
pos (always present)It contains the starting position (in byte) of the current NetPDL element (either a field or a protocol).
showmap (may be missing)It contains a (possibile) mapping for this field. For instance, the field code of an ICMP packet can be associated with the type of ICMP message: Echo Request, Echo Reply, and more. The showmap attribute keeps this kind of association: the value of this attribute will be a literal string that indicates the meaning of this field. This attribute may be missing because most of the fields do not have such a mapping.
showdtl (may be missing)There are some fields that require a more detailed explanation about their value. For instance, a MAC address can be a unicast address (and then we would like to know the vendor of the NIC card) or a multicast/broadcast address. The showdtl is an attribute that specify which description has to be associated to this field in case the standard description (basically the value of the field) is not enough. This attribute is optional because usually a field does not need such a detailed view.

These variable are stored internally by the NetPDL engine and are made available only to the visualization module that can use their value to define how a field/protocol has to be visualized.

Detailing the content of a decoded field: the showtemplate attribute and the <showtemplate> element

This section details how the NetPDL can be used to define the detailed view of the packet. For instance, there is not an unique way to print the value of each field; its value can be numeric or ASCII, some fields can require some special formatting options (for example IP addresses are 32 bit numbers, but are usually visualized by means of the dotted-decimal notation), and more.

The NetPDL language defines a set of additional information that are useful to print the information contained into network packets; in other words, it defines a set of tags that specify how a decoded field (for instance the field_value part of the example above) has to be visualized. This is done through the showtemplate attribute and the <showtemplate> element

Extending the attributes of a standard NetPDL field: the showtemplate attribute

This is a new attribute that applies to NetPDL <field>. The value of this attribute defines a template that contains the instructions needed to display this field properly. For instance:

  <field type="fixed" name="ipsrc" size="4"... showtemplate="ipaddress"/>

defines a field named ”ipsrc”, 4-bytes long, whose visualization format is specified in the ipaddress template. A template with this name will be found within a <visualization> tag, either locally to the current protocol or globally:

  <protocol name="ip">
    <format>
      <fields>
        <field type="fixed" name="ipsrc" size="4"... showtemplate="ipaddress"/>
        ...
      </fields>

    </format>
    ...
    <visualization>
      <showtemplate name="ipaddress" ..../>
    </visualization>
  </proto>

The template whose name is ipaddress contains a set of attributes (or elements) that defines how the field must be printed. The structure of this element is shown in the next section.

Defining the visualization of a field: the <showtemplate> element

The <showtemplate> element defines a set of attributes that can be used to determine the way a field is shown:

AttributeDescription
showtype (required)It defines if the content of the field must be shown using decimal numbers, hexadecimal numbers, ASCII values, and so on. Allowed values are:
- hex: it prints the value as an hexadecimal number, pre-pending the string ”0x” before the printable value (e.g. 0x1234).
- hexnox: it prints the value as an hexadecimal number without prepending the string ”0x” before the printable value; this can be useful, for example, for some fields (like MAC addresses) which are always expressed as hex numbers, hence there is no ambiguity.
- dec: it prints the value as a decimal number.
- bin: it prints the value in binary. The number will be prepended with the ”0b” string; in case of a bit field, the number is printed with dots in the positions in which the field has no valid digits (for instance, a bit field of 2 bits within a field of one byte, with value ”10” will be printed as ”0b10……”).
- ascii: it prints the value as a string. Special characters like string terminators (0x00), and carriage return / line feed (0x0A and 0x0D) are ignored; other non-printable characters (like ”bksp”) are replaced by a dot (”.”).
- float: it prints the value as a float (4 bytes, single precision).
- double: it prints the value as a double (8 bytes, double precision).
showgrp (optional)It defines if the field has to be displayed using a single group of data (e.g. “0000”) or more groups (e.g. “00-00”). Its value is a positive integer indicating the number of bytes that must be grouped together (default: the length of the field). Warning: please note that this attribute should always be “1” when the showtype is equal to ascii; otherwise, the field will not be printed as an ascii string.
showsep (optional)It defines the string that has to be used between different groups of data in case the previous parameter (showgrp) is being used. It can be any character (default: none).
showplg (optional)It is the “last resort” attribute in case the field cannot be properly shown using previous primitives. This attribute is a pointer to an external plug-in (hence the name, show plugin) that takes care of the visualization. The content of this attribute selects which external plug-in has to be called. This attribute makes the visualization code application dependent because the NetPDL engine will look for an external plug-in that will format the field appropriately. This code can be embedded in the NetPDL engine in some way, or it can be implemented in an external library. The NetPDL visualization extension does not specify how this plug-in is called; hence, this attribute makes the NetPDL document application dependent. Warning: in case this attribute is defined, all the previous attributes are ignored.

The showtype, showgrp and showsep attributes are called Standard Visualization Attributes and are the most common attributes for visualizing field values. The output of these standard attributes is associated to the showvalue Field Visualization Variable.

Some examples of usage are given below:

<showtemplate> attributesData valueData displayed (showvalue)
<… showtype=“hex” showgrp=“1” showsep=”:”ffffffffffffff:ff:ff:ff:ff:ff
<… showtype=“hex” showgrp=“3” showsep=”-”>ffffffffffffffffff-ffffff
<… showtype=“dec” showgrp=“1” showsep=”.”>ffffffff255.255.255.255
<… showtype=“ascii” showgrp=“1” showsep=””>40545450HTTP

In addition to previous attributes, the <showtemplate> element can have the following child elements:

ElementDescription
<showmap> (optional)(Default: no mapping available) It defines a mapping table that must be used to map the value of the field to its meaning. For instance, let's consider the opcode field of an ARP packet: a value of '1' means ”Request” and '2' means ”Reply”. This command tells the decoding engine that there is a table that keeps such this mapping. More details will be presented into the <showmap> section. By default, visualization templates do not include <showmap> elements. The output of this element is associated to the showmap Field Visualization Data.
<showdtl> (optional)(Default: no custom view is available) It defines the most powerful way to specify how a field looks like. This element includes an extended set of elements that specify how a field has to be shown. For instance, this can be the case of MAC addresses, in which we want to display not only their value, but also if it is a unicast or multicast/broadcast address. More details will be presented into the <showdtl> Section. By default, visualization templates do not include <showdtl> elements. The output of this element is associated to the showdtl Field Visualization Variable.

Some tips for standard visualization attributes

Applying standard settings for fields that are more than 32 bits wide

It is worthy to remind that fields that are more than 32bits wide cannot be printed as a single number. Therefore, attributes showgrp and showsep should be used in this case in order to create group of fields which are ⇐ 32bits. For this reason, it is strongly suggested to specify explicitly the visualization format for all fields whose length greater than 32 bits and for all variable-length fields, because their size can be arbitrarily long.

The this special protocol field

In expressions defined in the visualization section, a special protocol field named '''this''' is available: this special field name is used when there is no need to indicate which is the field we are referring to. This keyword is used mostly in the NetPDL Visualization Extension. Being a field name (although with a special meaning), it supports partial access through the ”[]” operator. For instance, the following expression:

buf2int(this[0:3]) == 0x0008BD

returns the first 3 bytes of the current field.

Mapping a field value to its meaning: the <showmap> element

The <showmap> element keeps the mapping between field values and meanings. When a <showmap> element is invoked, it needs a value (the key) that has to be matched against several choices. This value can be both numeric (32 bits max) and string (of whatever lenght). The key is an expression that is often derived from the value of the field under examination.

A <showmap> element includes a [netpdl:core_specs#Making more compact the code needed for several similar choices: the switch - case elements|<switch>] element for determining the correct branch. An example can be seen below:

<fields>
  <field type="fixed" name="demofield" size="4" longname="Demo" showtemplate="demotemplate"/>

  ...
</fields
...

<showtemplate name="demotemplate" showtype="hex" showgrp="1" showsep=":">
  <showmap>
    <switch expr="buf2int(this[0:1])">
      ...
      <case value="a" show="First code"/>
      <default show="No mapping available"/>

    </switch>
  </showmap>
</showtemplate>

This example defines a mapping table that will compare the value of the field to the ones defined into the mapping table. Before proceeding in the mapping, the value is extracted by means of a string expression: only the first byte (in front of the string) is selected and compared to the matching instructions.

Note: in case of a <showmap> element, there is no ambiguity about the field we are referring to, therefore we can use the “this” keyword, which indicated a reference to the current field. In case we are referring to the numeric value of the field, we have to use “int(this)”.

The <case> and <default> elements

Some minor modifications are needed for the <case> and <default> elements that are used within <showmap>. In these elements, there is a new attribute show, which contains the text that has to be associated to the showmap entry. In addition, they do not contain child elements.

AttributeDescription
show (required)The string that has to be associated to the NetPDL element, which usually depends on the value of the field itself. This string will be copied in the showmap Field Visualization Variable associated to this field.

Summarizing the most important difference related to <case> and <default> elements (as the have been defined in the NetPDL base language) is that they do not have any child elements; they have an additional attribute (show) instead.

Example: assigning a description to the commands carried by the ARP protocol

The ARP protocol is very simple and it has two commands: Request and Reply. This is the fragment of code that can be used to associates the commands to the field value:

<protocol name="ARP" longname="ARP (Address Resolution Protocol)">
  <format>
    <fields>

      ...
      <field type="fixed" name="opcode" longname="Operation code" size="2" showtemplate="ARPCode"/>
      ...
    </fields>
  </format>

  ...
  <visualization>
    <showtemplate name="ARPCode" showtype="hex">

      <showmap>
        <switch expr="buf2int(this)">
          <case value="1" show="Request"/>
          <case value="2" show="Reply"/>
          <default show="Error in ARP code lookup"/>
        <switch>

      </showmap>
    </showtemplate>
  </visualization>
</protocol>

Since a <showmap> element is present within the <showtemplate> related to the given NetPDL field, the NetPDL engine will take the value of this field (in the numeric form) and compare against the <case> elements of the matching table. In case the key (i.e. the value of the field, decoded at run-time by the NetPDL engine) is equal to attribute value of a <case> element, the content of the showmap Visualization Variable will contain this value. In case a matching has not been found, the string ”Error in ARP code lookup” will be copied instead.

For instance, if the value of the opcode field is '1', the showmap Visualization Variable will contain the string ”Request”.

Example: determining the manufacturer of a NIC card

This example looks similar to the previous one; however, the MAC address is 48 bits but only the first 24 bits are meaningful to determine the manufacturer of the NIC card. The first operation will be consider only the first 24 bits of the MAC address; then, the resulting value will be compared until the vendor code is found.

<showmap expr="buf2int(this[0:3])">
  <!-- Extracts the first 3 bytes of the MAC address (i.e. the OUI portion) -->
  <case value="ffffff" show="Broadcast address"/>
  <case value="000001" show="SuperLAN-2U"/>
  <case value="000002" show="BBN"/>

  ...
</showmap>
Comparing as a string or comparing as a number

Be careful that values ”01” and ”1” are equal if compared as number, but they are different if compared as strings. In order to avoid confusion, it is strongly suggested to “compare as numbers”; be careful in case you want to “compare as strings”.

Defining a custom string to be printed with the field: the <showdtl> element

Sometimes, the elements presented in the previous Sections could not be enough. For instance, they are able to change the way the field value is visualized (showtype, showgrp and showsep attributes), they can associate a value with a meaning, but we are still unable to print a special string in case we have a MAC multicast address, or print a modified value compared to the actual content of a field; for instance there are protocols that keep their length in multiple of 32 bits, while the user might be interested in visualizing the length in bytes.

The information that needs to be visualized can be the following:

  • simple text strings (for example “destination address”)
  • derived text strings, i.e. a value that can be found from the elaboration the current field; for example, we can be interested in visualizing the total length in bytes of the current header, while this information could be stored in 32 bit words multiples
  • any visualization data associated to the NetPDL field, usually the value or showvalue data.

Additionally, we need some conditional constructs (basically, an “if-then”) in order to manage some situations in which the shown text could vary according to some conditions. For example, we would like to print the vendor of the network card in case of a standard MAC address, but we want to print the string ”multicast address” in case it is a multicast MAC address.

For these situations, the <showdtl> element provides a way to customize the way a field is shown. An example can be seen below:

<fields
  <field type="fixed" name="demofield" size="4" longname="Demo" showtemplate="demotemplate"
  ...
</fields>
...
<showtemplate name="demotemplate" showtype="hex" showgrp="1" showsep=":">
  <showdtl>
    ...
  </showdtl>
</showtemplate>

A <showdtl> element does not have any attribute and it has the following child elements:

ElementAttributesDescription
<protofield> It defines that we want to insert the value of a given Field Visualization Variable associated to the field itself.
showdata (required)It specifies the name of the Field Visualization Variable that has to be copied in the custom description. In other words, if the longname associated data is ”Ver-HLen”, and the NetPDL element in the template looks like:
  <protofield showdata="longname"/>

the NetPDL engine will append the value of the longname attribute (i.e. the string ”Ver-HLen”) to the showdtl Field Visualization Variable.

<text> This element can have two different behaviors: it places a simple text that has to be appended to the custom description it retrieves the value of an attribute of the current field, it performs some processing to it, and it appends the result to the showdtl Field Visualization Variable.
value (optional)This attribute defines a simple text that will be placed into the custom description. For instance, if the value of this attribute is ”Unicast Address”, the string ”Unicast Address” will be appended to the showdtl Field Visualization Variable.Warning: one among the value and the expr attributes must be present in the <text> element.
expr (optional)The <text> element can have a standard NetPDL expression as attribute. The expression is evaluated and the result is appended to the showdtl Field Visualization Variable. For instance, let's imagine to be willing to print the value of the ”Header Length” field of the IP protocol, expressed in bytes. Since this field keeps the length in multiple of 32 bits, we have to print the value timed by 4:
  <text expr="this * 4"/>

Like in the <showmap> element, the expression often contains the “this” special field reference because there is no ambiguity about the field we are referring to. Warning: in case a <text> element has both the value attribute and a child element specifying the expression, the content of the value attribute is always appended first to the showdtl Field Visualization Variable.Warning: one among the value and the expr attributes must be present in the <text> element.

<if> This element is used to evaluate a condition in order to create the showdtl Field Visualization Variable. It has the same syntax of the corresponding <if> element of the NetPDL Specification, i.e.: it must have the expr attribute; it must have at least an <if-true> node (and optionally an <if-false> one), which can contain one or more child nodes that define how to print some information. The allowed nodes are: <protofield> <text> <if> (i.e. conditions can be nested) The condition of the expression node is evaluated; if the result is true, all the visualization elements included into the <if-true> are executed, otherwise the <if-false> branch (if present) is selected.

The <showdtl> element allows to create a custom visualization template, i.e. it defines some instructions that customize how a field can be visualized. The output of these this element is associated to the showdtl Field Visualization Variable. Please note that the presence of the <showdtl> element does not replace other attributes (e.g. showtype, showsep, showgrp), even in this element is intended to generate a “better” visualization string than the one obtained by the above-mentioned attributes. In fact, these attributes must always present because they help generating the showvalue Visualization Variable, which must always be present in the NetPDL engine.

Example: visualizing the field "header length" of an IP packet

Since the header length field keeps the length of the IP header in multiple of 4 bytes, this the code prints a more detailed explanation of the field:

<showdtl>
  <text expr="this * 4"/>
  <text value=" (field value = "/>
  <protofield showdata="showvalue"/>

  <text value=")"/>
</showdtl>

This code stores in the showdtl Field Visualization Variable the following information:

  • the value of the field (expressed in bytes) and
  • the actual value of the field (i.e. the number that can be found into the hexadecimal dump of the packet, stored in the showvalue Visualization Variable).

The output looks like the following:

20 (field value = 5)
Example: visualizing the detailed information of a MAC address

This example makes use of the <if> element in order to print the detailed information of a MAC address. This template checks if the MAC address is multicast/broadcast: in this case it prints the string ”Multicast - Broadcast address”; otherwise, it prints the name of the vendor of the network interface card (which has been stored into the showmap visualization associated data).

<protocol name="Ethernet" longname="Ethernet 802.3" >
  <format>
    <fields>
      <field type="fixed" name="dst" longname="MAC Destination" size="6" showtemplate="MacAddress"/>
      <field type="fixed" name="src" longname="MAC Source" size="6" showtemplate="MacAddress"/>
      <field type="fixed" name="type-length" longname="Ethertype" size="2" showtemplate="ShortHex"/>

    </fields>
  </format>
  <visualization>
    <showtemplate name="MacAddress" showtype="hexnox" showgrp="3" showsep="-">
      <showdtl>
        <protofield showdata="showvalue"/>

        <if expr="(buf2int(this[0:1]) bitwand 0b00000001) == 0b00000001">
          <!-- It extracts the first byte of the MAC address, then it matches -->
          <!-- the result against the 'xxxxxxx1' and 'xxxxxxx0' patterns -->

          <if-true>
            <text value=" Multicast - Broadcast address"/>
          </if-true>

          <if-false>
            <text value=" Unicast address (Vendor "/>
            <protofield showdata="showmap"/>
            <text value=")"/>
          </if-false>
        </if>

      </showdtl>
      <showmap>
        <!-- This example requires also the 'showmap', omitted here for clarity -->
      </showmap>
    </showtemplate>
    <showtemplate name="ShortHex" showtype="hex"/>

  </visualization>
</protocol>

Custom visualization through external plug-ins

There are some cases in which even the <showdtl> element is not enough to print the field appropriately. Some examples are listed below:

  • IP/IPv6 network addresses (and other L3 protocols): the user could be willing to print the literal address (e.g. foo.bar.com) instead of the numeric one; additionally, this feature could be turned on upon request. For instance, the procedure that maps numeric address to their literal form can be quite slow and the user could not be interested in case the speed is an important issue.
  • NetBIOS names: the NetBIOS protocol is used to share resources (printers, disks, etc.) on a local network. For doing so, it includes the name of the NetBIOS machine in some packets that are sent through the network. However, the name is “encrypted” (some bytes are scrambled), making impossible to print the actual name from the NetPDL language, which is not powerful enough.

Although one solution could have been to extend the NetPDL language to handle such these cases, this could not be a good choice because the NetPDL will become more complex to handle exceptional situations. The solution implemented in the NetPDL Visualization Extension defines some external templates (plug-ins), included in the NetPDL engine, that can be called by the fields that need some special processing. This could look similar to the type=“plugin” NetPDL field, but it is valid only for visualization. This is done by the showplg attribute, described in the <showtemplate> Section.

The following code prints the canonical name instead of an IP address:

<protocol name="IP" longname="IPv4 (Internet Protocol version 4)">
  <format>
    <fields>
      ...
      <field type="fixed" name="src" longname="Source address" size="4" showtemplate="IPAddress"/>
      <field type="fixed" name="dst" longname="Destination address" size="4" showtemplate="IPAddress"/>
    </fields>

  </format>}}}
  <visualization>
    <showtemplate name="IPAddress" showgrp="1" showsep="." showplg="LiteralIPAddress"/>
  </visualization>
</protocol>

This code will tells the NetPDL engine that the external plug-in called ”LiteralIPAddress” must be used to display the value of the field.

Note: the user is encouraged to define the visualization default attributes also in case of plugins, since they can be used when the external plug-in cannot be found. In this case, the NetPDL engine can format the field according to the other directives.

The summary view

While the detailed view aims at visualizing all the information that are present into a decoded packet, the summary view tends to limit the visualized information to the most important fields. This provides a way to see how the information contained into the packet looks like; if the user is interested in that, it could switch to the detailed view for a more in-depth analysis.

The summary view looks like a custom template applied to the whole packet; therefore some of the elements will be similar to the ones defined into the <showdtl> section. The information that needs to be visualized can be the following:

  • simple text strings (for example ”destination address”)
  • derived text strings, i.e. a value that can be found from the elaboration of one or more fields of the protocol; for example, we can be interested in visualizing the total length of the protocol, which can be derived by adding the value of the protocol headers (defined into a field hlen) and the protocol payload (defined into a field plen)
  • some visualization variables associated to a decoded field, usually the value or showvalue associated data
  • some visualization variables associated to the current protocol, usually the name or longname associated data

In addition, an “if-then” element is needed to manage some situations in which the visualized text could vary according to some conditions.

The previous information is usually enough to print a summary view of the packet. However, often the summary view is structured within several sections. For instance, a quite common form for the summary view is the following:

N.TimeLink LayerNetworkApplication
114:12:22.4480080c7-cb439a ⇒ ffffff-ffffff ARP Request: who has 130.192.16.17 tell 130.192.16.81
214:12:22.49100e01e-ec3c84 ⇒ 0080c7-cb439a ARP Reply:130.192.16.81 is at 00e01e-ec3c84
314:12:22.5240080c7-cb439a ⇒ 00e01e-ec3c84IP: 130.192.16.81 ⇒ 130.192.16.17 (Len 60)ICMP Echo Request
414:12:22.57700e01e-ec3c84 ⇒ 0080c7-cb439aIP: 130.192.16.17 ⇒ 130.192.16.81 (Len 60)ICMP Echo Reply

Each Section is devoted to a particular set of information, for example the network-related ones (e.g. the IP source and address, and more). This means that we need an additional information in order to detect in which section the data has to be shown.

Defining the general format of a summary view: the <showsumstruct>-<sumsection> elements

These elements define the general structure on the summary view. Usually, the summary view is made up of several sections (the columns shown in the previous table): the NetPDL engine needs to know the total number of sections and their name.

This task is done by defining a <showsumstruct> element (with no attributes), which contains a set of <sumsection> elements that defines the list of sections that will appear in the summary view. The <showsumstruct> element is a child of the <netpdlshow> element and must be present only once in the NetPDL document.

The <sumsection> element will contain two attributes:

AttributeDescription
name (required)It defines the name of the section. This name will be used by <section> elements to define in which section the data has to be shown. More details in the <section> element (below).
longname (required)It defines the name of the section, in “human” form.

The collaborative approach for creating the summary view

The complete summary view includes the information of several protocols. For instance, the Ethernet protocol can insert its MAC addresses in the summary view, which is only a small part of the information the users expect to find. Each protocol adopts a “collaborative” approach to create the summary view: each one inserts the most important information it knows; furthermore it has to select the section in which this information has to be visualized. The summary view will be completed only when all the protocols contained into the packet inserted their data.

Example: defining a common structure for the summary view

This example defines a common structure for the summary view. The structure is made of six sections; it defines some common information like the number of the current packet and its timestamp, then it defines four sections for the most important information for each of the ISO OSI 2, 3,4 and 7 layers.

<visualization>

  <showsumstruct>
    <sumsection name="NUMBER" longname="Packet Number"/>
    <sumsection name="TIME" longname="Time"/>
    <sumsection name="L2" longname="Data Link"/>
    <sumsection name="L3" longname="Network"/>
    <sumsection name="L4" longname="Transport"/>

    <sumsection name="L7" longname="Application"/>
  </showsumstruct>
  ...
</visualization>

Extending the attributes of <protocol> and <block> elements: the showsumtemplate attribute

The showsumtemplate is a new attribute that applies to the <protocol> and <block> NetPDL elements. The value of this attribute defines a template that contains the instructions needed to create the summary view of this protocol / block. For instance:

<protocol name="ip" ... showsumtemplate="ipsummary"/>

defines a protocol named ”ip”, whose summary visualization is specified in the ipsummary template. A template with this name will be found within a <visualization> tag, either locally to the current protocol or globally.

In case a <protocol> or <block> element does not contain the showsumtemplate attribute, the summary view of the packet will not contain anything about this protocol / block.

Defining the information that each protocol wants to insert into the summary view: the showsumtemplate attribute and the <showsumtemplate> element

The summary view is defined by the <showsumtemplate> element, which is an optional child of the <visualization> element:

<protocol name="IP" showsumtemplate="ipsummary">
  <format>
    ...
  </format>

  <visualization>
    <showsumtemplate name="ipsummary">
      <!-- Here we define the summary view of this protocol -->
      ...
    </showsumtemplate>
  </visualization>
</protocol>

The <showsumtemplate> element can be used to print either a summary related to the current protocol, or a summary related to the current block. In case it is a child of the <block> field, it is executed only if the block is present within the current protocol.

The <showsumtemplate> element can be made up of the following elements:

ElementAttributesDescription
<section> It defines the section in which the data created by the following elements will be inserted. Warning: the section specified by this element is stored by the NetPDL engine and it becomes the default section in which the text is appended. This default section is maintained within the current packet. In other words, if the default section is ”S2” when decoding protocol ”P1”, the next protocol (let's say ”P2”) will insert its data in S2 as well, unless another <section> element is encountered.When a new packet is decoded, the default section becomes the first one.
name (required)It specifies the name of the section in which we want to insert the information. There can be two type of names: the name is equal to one of the section specified in the <sumsection> elements. This way is useful when we want to print some information into a predetermined section (for instance, the timestamp must not be visualized into the ”network level” section, but in the ”timestamp” one). the name is the 'next' keyword. This means that the information will be visualized in the next section according to the <sumsection> list. In case the next section does not exist (we are already visualizing in the last section), the information will be appended to the last section. This keyword is useful to: avoid that the information related to some protocol which is encapsulated into another one is placed in the wrong section (for instance, this tag avoids that the information related to the IP protocol in case we have an IP in IP packet will be visualized both in the ”network level” section) avoid that if the list of <sumsection> elements are being updated, we have to update all the information related to the summary view in all the protocols. In case more than one protocol wants to put data in the same section, the new text is simply appended to the existing one.
<pkthdr> This element is used to print the value of one of the attributes of the packet header (e.g. packet number, timestamp, etc).
value (required)This attribute defines the name of the packet header attribute that will be printed. Possible values are the following:
- timestamp: timestamp of the current packet
- caplen: number of bytes captured in the current packet
- len: actual length of the current packet
- num: ordinal number of the current packet ('1' for the first, etc.)
<protohdr> It specifies that we want to insert the value of a given Field Visualization Variable associated to the protocol header itself.
showdata (required)It specifies the name of the Field Visualization Variable that has to be copied in the summary view. In other words, if the longname associated data is ”IPv4”, and the NetPDL element in the template looks like:
  <protohdr showdata="longname"/>

the NetPDL engine will append the value of the longname Field Visualization Variable (i.e. the string ”IPv4”) to the summary view.

<protofield> It specify that we want to insert the value of a given Field Visualization Variable associated to the a protocol field.
name (required)It specifies the name of the field that has been selected for getting access to one of its Field Visualization Variable. In case more than one fields with that name exist, the NetPDL engine will select the one that appears last in the encountered list of fields.
showdata (required)It specifies the name of the Field Visualization Variable that has to be copied in the custom description. In other words, if the longname associated data is ”Ver-HLen”, and the NetPDL element in the template looks like:
  <protofield name="src" showdata="longname"/>

the NetPDL engine will append the value of the longname attribute (i.e. the string ”Ver-HLen”) to the showdtl Field Visualization Variable.

<text> This element can have two different behaviors: it can place a simple text that has to be inserted into the summary view it can retrieve the value of an existing field (within the current protocol), it performs some elaborations to it, and it inserts the result in the summary view.
value (optional)This attribute defines a simple text that will be placed in the summary view. For instance, if the value of this attribute is ”Unicast Address”, the string ”Unicast Address” will be appended to the current section of the summary view.
expr (optional)The <text> element can have a standard NetPDL expression as a attribute. The expression is evaluated and the result is appended to the current section of the summary view. For instance, let's imagine a fragmented IP packet, and that we want to print the starting point (in bytes) of the current fragment. The procedure needs to read the “fragment offset” field of the IP packet, and multiply its value by eight (the fragment offset is stored in multiple of 8 bytes):
  <text value="Fragment " expr="foffset * 8"/>

Warning: in case a <text> element has both the value attribute and a child element specifying the expression, the content of the value attribute is always appended first to the summary view.

<if> This element is used to evaluate a condition before visualizing some information in the summary view. It has the same syntax of the corresponding <if> element of the NetPDL Specification, i.e.: it must have an expr attribute containing an expression it must have at least an <if-true> node (and optionally an <if-false> one), which can contain one or more child nodes that define how to print some information. The allowed nodes are: <section> <protohdr> <protofield> <text> <if> (i.e. conditions can be nested) The condition of the expression node is evaluated; if the result is true, all the visualization elements included into the <if-true> are executed, otherwise the <if-false> branch (if present) is selected.

Example: a summary view for an Ethernet packet

In this example we want to show the MAC source and destination addresses. This is a fragment that does that:

<protocol name="Ethernet" showsumtemplate="ethsummary">
  <format>

  ...
  </format>
  ...
  <visualization>
    <showsumtemplate name="ethsummary">
      <section name="next"/>
      <text value="Eth : "/>

      <protofield name="src" showdata="showvalue"/>
      <text value=" => "/>
      <protofield name="dst" showdata="showvalue"/>
    </showsumtemplate>
  </visualization>

</protocol>

This fragment moves the “current section” pointer to the next section, then the string ”Eth: ” is appended to the visualization template. It follows the source MAC address in the printable form (the <protofield> element selects the showvalue associated data), the ” ” text string, then the destination MAC address in the printable form. An example of a possible output looks like:

Eth: 008048-BA6651 => FFFFFF:FFFFFF

Example: a more detailed summary view for an Ethernet packet

This example looks similar to the previous one. However, it prints a special string in case the destination address is a multicast/broadcast MAC address. The fragment of code that fulfills the previous requirement makes use of the <if> element:

  <protocol name="Ethernet" showsumtemplate="ethsummary">
    <format>

      ...
    </format>
    <visualization>
      <showsumtemplate name="ethsummary">
        <section name="next" />
        <protohdr showdata="name" />
        <text>: </text>

        <protofield name="src" showdata="show"/>
        <text> => </text>
        <protofield name="dst" showdata="show"/>

        <if expr="(buf2int(this[0:1]) bitwand 0b00000001) == 0b00000001">

          <!-- It extracts the first byte of the MAC address, then it matches -->
          <!-- the result against the 'xxxxxxx1' pattern -->
          <!-- Extract the first byte of the MAC address -->
          <!-- If it is a broadcast address, the last bit will be '1' -->

          <if-true>
            <text value=" Multicast - Broadcast address"/>

          </if-true>
        </if>
      </showsumtemplate>
    </visualization>
  </protocol>

Known issues

This section lists the most important limitations of the NetPDL visualization extension.

TLV blocks

The most important problem is related to the TLV blocks. Let us suppose the following NetPDL fragment:

  <loop type="times2repeat" expr="Count">
    <field type="fixed" name="Type" size="1"/>
    <field type="fixed" name="Length" size="2"/>

    <field type="variable" name="Value" expr="Length" showtemplate="VarField"/>
  </loop>

This block of fields is repeated several times, but there is not way to differentiate how the field Value has to be shown within different instances of the loop. For instance, in case Type has a given value, then the Value can be a field that should be visualized in ASCII form; in other cases it can be a standard number, or even an IP address. The current syntax does not allow defining a custom view for each case. This is quite a common problem because the TLV schema is used several times in protocol headers.

There is a workaround, which consists in defining the protocol in a different (less compact) way:

  <fields>
    <loop type="times2repeat" expr="Count">
        <field type="fixed" name="type" size="1"/>
        <field type="fixed" name="length" size="2"/>
        <switch expr="buf2int(type)">

          <case value="0">
            <field type="variable" name="value" expr="buf2int(length)" showtemplate="type0"/>
          </case>
          <case value="1">
            <field type="variable" name="value" expr="buf2int(length)" showtemplate="type1"/>
          </case>

          ...
        </switch>
    </loop>
  </fields>
  ...
  <visualization>
    <showtemplate name="type0" showtype="hex" showgrp="4" showsep=" "/>

    <showtemplate name="type1" showtype="ascii" showgrp="1"/>
  </visualization>

The <loop> block is maintained, but a <switch>-<case> block is being inserted that differentiates how the field value is shown.

 
netpdl/visualization_expression.txt · Last modified: 2010/12/21 17:45 by admin     Back to top