Wireshark plugin
================

This directory contains code that can be built as a plugin for wireshark, enabling OSPL packets to be decoded.

1. Building the plugin

1.1 Linux

The included makefiles are for RedHat 6 but will also work with Fedora 14+ and probably other linuxes or gcc-based unixlike development environments with minor modifications.

1.1.1 Requirements

The wireshark and glib header files and libraries must be available. On RedHat 6 systems these are provided by the wireshark-devel and glib2-devel packages.

1.1.2 Compiling the plugin

Choose an appropriate Makefile.defs.* file and rename it as Makfile.defs
Then running 'make' will build the shared library object. If this is placed in a .wireshark/plugins directory in the users home directory, it will be loaded at startup by wireshark.

1.2 Windows

1.2.1 Acquiring the plugin

PrismTech no longer provide instructions on how to build the Wireshark Tool on Windows. Instead, there are now pre-built plugins available via the PrismTech website which are distributed under the General Public License (GPL). The plugin can still be built manually using the provided makefile, however this will be unsupported due to the complex setup requirements and procedures for building from source. 

The plugin is built against Visual Studio 2010 and requires that the redist pack is installed prior to use, this has been provided in the redist folder of the plugin package.

2. Using the plugin

2.1 Installing the plugin

It may then be installed by copying packet-ospl.dll to %APPDATA%\Wireshark\Plugins (typically C:\Documents and Settings\username\Application Data\Wireshark\Plugins). You can find this path by echoing %APPDATA% at a command line.

2.2 Wireshark preferences and capture options

In order to receive fewer packets you can enable or disable protocols in the Analyze -> Enabled protocols menu. For example, you can enable only IP, Ethernet and UDP protocols.

In the Edit -> Preferences -> Protocols -> OSPL menu you can change the port numbers for OpenSplice packets. Default port numbers are 54100,54110,54120. You can also specify ranges like "54100-54120".

In the Capture->Options menu you can :

   Disable "promiscuous mode" in order to get only packets sent to/from your machine.
   Choose "Stop capturing after ... kilobytes".
   Start capturing data.

These options are displayed for the default interface (eth2). In Capture -> Interfaces you can see the list of available interfaces and choose the right one (eth2).

If you restart wireshark the settings in "Enabled Protocols", in "Preferences" are saved from the last run, but "Capture -> Options" are reset to default values.

2.3 Displayed data for OpenSplice packets

2.3.1 Info column ("Packet List" pane):

In the packet list there is a short description of the packet: control packet or data packet, flags, packet length, number of messages, packet number (if RELIABLE flag is set).  If you select a packet in the packet list, its details are displayed in "Packet Details" pane.

Here you can sort packets by values in different columns.

2.3.2 Protocol tree ("Packet Details" pane)

In the protocol tree you can see the structure of the packet and the values of all protocol header fields. If you select a field in the protocol tree normally you can see the corresponding bytes in the "Packet Bytes" pane, and in the bottom panel you can see the field description.

2.3.3 Error handling

In some cases an error message is displayed in the protocol tree, for example if message length is greater than the remaining packet length.

If an OpenSplice packet is too short, only flags field are displayed (packets shorter than 8 bytes are ignored).

2.4 Display filters

During the capturing (or after it) you can use the filter field in order to display only some special kinds of packets, for example:

   ospl - display only OSPL packets

   udp - only UDP packets (and not recognized as OpenSplice packets, for example if the port number is not specified in the preferences for OpenSplice protocol

   ospl.fl_control == 1 - OSPL control packets

   ospl.messages > 1 && ospl.error - OSPL packets containing multiple messages and with a dissector error

   ospl && !ospl.error - OSPL packets without dissector errors

   ospl_flags == 0xa - OSPL packets with flags = 0xa (RELIABLE and TERMINATOR)

In the bottom pane you can see how many packets are there and how many of them are displayed.

Field names in OpenSplice protocol which can be used for display filter:

   ospl.flags
   ospl.fl_control
   ospl.fl_reliable
   ospl.fl_fragmented
   ospl.fl_terminator
   ospl.fl_p2p
   ospl.snode       (sending node id )
   ospl.plength     (packet length)
   ospl.rnode       (receiving node id)
   ospl.partition   (network partition id)
   ospl.crc         (crc checksum of the packet (optional))
   ospl.messages    (number of messages in the packet)
   ospl.error       (dissector error)

In data packets:

   ospl.packet      (packet number)
   ospl.message     (fragmented message number)
   ospl.fragment    (fragment number)
   ospl.tmessage    (terminating message number)
   ospl.tfragment   (terminating fragment number)
   ospl.mlength     (message length)
   ospl.data

In control packets:

   ospl.chstatus    (channel status)
   ospl.apartition  (network partition id of acked messages)
   ospl.astart      (starting packet number of acked range)
   ospl.aend        (closing packet number of acked range)

2.5 Saving captured data

After capturing packets you can save the captured data in a file and reuse it. You can save all packets or only displayed (filtered) packets.

Wireshark can also export captured data in xml format.

