trema/trema-edge

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

  Copyright (C) 2008-2013 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.6.10 and 1.8.2. 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

If you want to dissect OpenFlow messages, you may additionally need to
install OpenFlow Wireshark dissector:

  https://github.com/CPqD/ofdissector

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. Run controller with '-s' option

  $ trema run /somewhere/learning_switch -c learning_switch.conf -s

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

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

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

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