

                L   I   B   N   E   T   D   U   D   E


	      The NETwork DUmp data Displayer and Editor
                      Packet Manipulation Library

                       Flow Demultiplexer Plugin

                     http://netdude.sourceforge.net
         Christian Kreibich <christian.kreibich-AT-cl.cam.ac.uk>

------------------------------------------------------------------------

This plugin scans a set of input traces and demultiplexes the flows
contained in the input traffic into an output directory tree, at various
granularities.

Per-destination port (--dest-ports):
====================================

 <root> +-- IP proto 1 +-- a.trace
        |              +-- b.trace
        |              '-- ...
        |
        +-- IP proto 2 +-- n.trace
        |              +-- m.trace
        |              '-- ...

a,b,...,n,m,... are the destination port numbers encountered.


Per-destination host + port (--dest-hostports):
===============================================

 <root> +-- IP proto 1 +-- IP dst 1 +-- a.trace
        |              |            +-- b.trace
        |              |            '-- ...
        |              |
        |              +-- IP dst 2 +-- n.trace
        |              |            +-- m.trace
        |              |            '-- ...
        |              '-- ...
        |
        +-- IP proto 2 +-- ...

a,b,...,n,m,... are the destination port numbers encountered.

Per source/dest IP pair (--host-pairs):
=======================================

The output is placed in a directory tree whose first level differentiates
by IP protocol, the second by source IP address, and the third by
destination IP address like this:

 <root> +-- IP proto 1 +-- IP src 1 +-- IP dst 1 +-- output trace 1
        |              |            |            +-- output trace 2
        |              |            |            '-- ...
        |              |            |
        |              |            +-- IP dst 2 +-- output trace 1
        |              |            |            +-- output trace 2
        |              |            |            '-- ...
        |              |            +-- ...
        |              |
        |              +-- IP src 2 +-- ...
        |
        +-- IP proto 2 +-- ...

"IP proto" refers the numerical number of the IP payload as listed
in /etc/protocols. Arbitrarily many input traces are supported.

Each file name looks like this:

	<start of flow in sec.usecs>-<src port>-<dst port>.trace

Non-IP packets are placed into a trace called "non-ip.trace" in the
<root> directory. Fragmented IP packets end up in the correct direc-
tory, but since it is not possible to see which ports are involved,
they end up in a trace whose name ends in "-0-0.trace".

You can limit the number of *flows* (not packets) written to any one
output pcap file using the --max-flows option.

For easier grepping through lists of the resulting output files and
directories, you can use --mark|-M so that IPs, ports, and protocol
numbers are prefixed with unique strings as follows:

 - src IP:   'S'          - dst IP:   'D'
 - src port: 's'          - dst port: 'd'
 - protocol number: 'p'

The performance of this plugin is highly I/O-bound, so demuxing large
traces can take a bit. Use the --progress|-p option to get a progress
meter at the command line.

To build this plugin from source, do the following:

- make sure you have the following plugins installed:
    - Conntrack
    - Trace-Set
- run ./autogen.sh.
- run ./configure, adding --enable-debugging for debugging output.
- run make install.

Enjoy.

------------------------------------------------------------------------
  Yet another SRG production -- http://www.cl.cam.ac.uk/Research/SRG/
------------------------------------------------------------------------
