README for tremashark
*********************

  Copyright (C) 2008-2012 NEC Corporation

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved. This file is offered as-is,
  without warranty of any kind.

What is tremashark?
===================

"tremashark" provides a wireshark (http://www.wireshark.org/) plugin and a
bridge between the Trema world and wireshark to display various events on
wireshark. You can monitor any IPC events among Trema modules, packets on
network interfaces/links, or log messages in realtime. It should be useful
for learning the Trema world and debugging your OpenFlow controller
applications.


How to build and install?
=========================

Pre-requirements
----------------

You need to download the source code of wireshark before you start to build
tremashark. We have tested with wireshark 1.4.4. Note that the package
"wireshark-dev" included in Ubuntu or Debian will not work for building the
wireshark plugin. You can get the source code from the following site:

  http://www.wireshark.org/download.html

Also, you may need to install several software packages.

  $ sudo apt-get install wireshark flex bison libgtkmm-2.4-dev

Build and install
-----------------

Before building tremashark, you should compile Trema (see INSTALL) first.
Then build the plugin as follows:

  $ cd [trema]/src/tremashark/plugin
  $ tar xvf /somewhere/wireshark-X.Y.Z.tar.bz2
  $ ln -s wireshark-X.Y.Z wireshark
  $ cd wireshark
  $ ./configure
  $ cd ../packet-trema
  $ make
  $ mkdir -p ~/.wireshark/plugins
  $ cp packet-trema.so ~/.wireshark/plugins
  $ cp ../user_dlts ~/.wireshark/


How to run?
===========

1. Add `use_tremashark' directive in your Trema configuration. e.g.,

  use_tremashark

  vswitch {
    datapath_id "0x1"
  }
  ...

2. Send SIGUSR2 to processes to be monitored by tremashark. e.g.,

  $ sudo kill -USR2 `cat tmp/learning_switch.pid`
  $ sudo kill -USR2 `cat tmp/switch.1.pid`

Known issue
===========

- Wireshark plugin would not correctly reassemble messages when plural
  fragments are on a single packet.