Starting with release 2.1.1, OpenDDS provides support for Wireshark.
The OpenDDS DCPS dissector provides a Wireshark 1.2.x/1.3.x compatible 
dissector which supports the TCP/IP, UDP/IP, and IP multicast transports.
Dissection of transport headers and encapsulated sample headers are fully
supported.


======================================================================
* See also

  - Wireshark Project Page
      <http://www.wireshark.org/>
  - Wireshark Download Page
      <http://www.wireshark.org/download.html>
  - Wireshark Developer's Guide
      <http://www.wireshark.org/docs/wsdg_html_chunked/>
  - Wireshark User's Guide
      <http://www.wireshark.org/docs/wsug_html_chunked/>


======================================================================
* Building the OpenDDS DCPS dissector

These instructions assume you have completed the installation steps in
the $DDS_ROOT/INSTALL document, including having the various environment
variables defined.

In addition, the Wireshark sources must be available and built locally
according to the Wireshark Developer's Guide (see above).

1. Define environment variables

   Linux and Solaris:
     export GLIB_ROOT=<full path to the GLib root directory>
     export WIRESHARK_SRC=<full path to the Wireshark source directory>

   Windows:
     set GLIB_ROOT=<full path to the Wireshark win32-libs/gtk2 directory>
     set WIRESHARK_SRC=<full path to the Wireshark source directory>
     set WIRETAP_VERSION=<version of the wiretap DLL built by Wireshark>

2. Update platform_macros.GNU (optional)

   For Linux and Solaris, the platform_macros.GNU file must be modified
   to contain the following:
     versioned_so=0
     wireshark=1

3. Generate MPC workspace

   Linux and Solaris:
     cd $DDS_ROOT/tools/dissector/
     perl $ACE_ROOT/bin/mwc.pl -type gnuace -features wireshark=1

   Windows:
     cd %DDS_ROOT%\tools\dissector\
     perl %ACE_ROOT%\bin\mwc.pl -type [CompilerType] -features wireshark=1
       "CompilerTypes" tested includes vc71, vc8, vc9, and nmake

4. Build

   Build normally as described in the $DDS_ROOT/INSTALL document.

5. Install plugin

   Linux and Solaris:
     export WIRESHARK_ROOT=<full path to the Wireshark root directory>
     cp OpenDDS_Dissector.so $WIRESHARK_ROOT/lib/wireshark/plugins/<version>/

   Windows:
     The default Wireshark install directory is the wireshark-gtk2
     subdirectory of the WIRESHARK_ROOT (top of the source tree).
     copy OpenDDS_Dissector.dll <full path to the Wireshark install>\plugins\<version>\
     -or-
     copy OpenDDS_Dissectord.dll <full path to the Wireshark install>\plugins\<version>\

6. Run Wireshark

   You may verify the plugin is installed correctly by clicking on the
   Help -> Supported Protocols menu item and looking for "OpenDDS" under
   the Protocols tab.

   NOTE: You may need to define LD_LIBRARY_PATH (for Linux and Solaris)
         or PATH (for Windows) to resolve dependent libraries when running
         Wireshark once the plugin is installed.


======================================================================
* Available Display Filters

A number of display filters are supported by the OpenDDS DCPS dissector:

1. Transport header display filters

   opendds.version
     Revision of the DCPS protocol.

   opendds.byte_order
     Byte order of transport header contents.

   opendds.length
     Total length of payload, including sample headers.

   opendds.sequence
     Sequence number of transmitted PDU.

   opendds.source
     Source identifier; only used by the multicast transport.

2. Sample header display filters

   opendds.sample.id
     Message ID of sample (i.e. SAMPLE_DATA).

   opendds.sample.sub_id
     Sub-Message ID of sample (i.e. MULTICAST_SYN).

   opendds.sample.flags
     Flags field (see below).

   opendds.sample.flags.byte_order
     Indicates byte order of sample data.

   opendds.sample.flags.coherent
     Indicates sample belongs to a coherent change group.

   opendds.sample.flags.historic
     Indicates sample is historic; resent by DataWriter.

   opendds.sample.flags.lifespan
     Indicates sample defines a lifespan.

   opendds.sample.length
     Total length of sample data, not including sample header.

   opendds.sample.sequence
     Sequence number of transmitted SAMPLE_DATA.

   opendds.sample.timestamp
     Source timestamp of sample.

   opendds.sample.lifespan
     Lifespan duration of sample (iff lifespan flag is set).

   opendds.sample.publication
     Publication ID of transmitting DataWriter.


======================================================================
* Available Color Filters

A set of color filters are included in the source distribution which may
be imported to highlight DCPS protocol packets.

To import these filters, click on the View -> Coloring Rules menu item,
followed by the the Import button.  Select the colorfilters file in the
$DDS_ROOT/tools/dissector/ directory and click the Open button.

NOTE: Coloring rules are applied on a first match basis; you may need to
      move the imported rules above the "tcp" and "udp" rules using the
      Order buttons on the right-hand side of the dialog.  If ordering is
      changed, you must ensure the "OpenDDS (Important)" rule appears
      before the "OpenDDS" rule.


======================================================================
* Known Limitations

  - OpenDDS only maintains wire compatibility with the current revision
    of the DCPS protocol.  This dissector is effective for the compiled
    protocol version only.

  - Dissection of marshaled sample data is not currently supported.


