Packet-o-matic : the modular network packet processor.
Author : Guy Martin <[email protected]>
Homepage : http://www.packet-o-matic.org
Additional documentation : http://wiki.packet-o-matic.org


What it is :
------------
Packet-o-matic is a modular network sniffer and packet processor. The modules consists of input, match, conntrack, helper and target.
It is designed to be as protocol independant as possible. Each protocol has it's own module for match, conntrack and helper (if applicable).


Building from svn :
-------------------
You need at least autoconf-2.61. First run "autoreconf -f -i" to create ./configure and then follow the instructions as if you fetched from a tarball.


Building from tarball :
-----------------------
Run these commands in order :
./configure
make
make install


Running it :
------------
If you make install, you are fine. The program will be able to find the libraries using automatic resolving or hardcoded library path.
If you did not run make install, you have to `export LD_LIBRARY_PATH=path/to/libdir`. By default, libtool creates the libs into the src/.libs directory.

Some modules such as input_pcap requires root privileges in order to perform their operation.


Dependencies :
--------------
 - libpcap : required to build input_pcap, target_pcap, target_inject and target_tcpkill
 - libxml2 : mandatory to parse the configuration
 - xmlrpc-c : required to build XML-RPC interface and web interface
 - MySQL : required to build datastore_mysql
 - PostgreSQL : required to build datastore_postgres
 - SQLite3 : required to build datastore_sqlite


How it works :
--------------
Packets are read from the input.
We check against each match of each rule if we should make that packet processed by the targets of the rule.
At the same time we check if a helper is needed and for example put all the ipv4 fragments into a single packet.
We check if the packet has some conntrack information attached to it.
If the packet has conntrack info, it is processed by the coresponding targets which saved the conntrack info.
It the match result is positive, we process the packet with the targets defined for this rule.


Getting started :
-----------------
First, start packet-o-matic by running `packet-o-matic` in the console.
Once started, it will listen on port 4655. Simply telnet to that port and start issuing commands.
You have to perform the following tasks to get a running configuration :
 - choose an input type and configure it
 - add the rules you need
 - add the targets you need
 - save the config

The following example start an input pcap on eth0 (the default) and dump all the images that goes over HTTP on port 80 :

// we use input pcap
pom> input type set pcap

// we want to match everything destinated to the port 80
pom> rule add tcp.dport == 80
Added rule with id 0

// the rule needs to be enabled
pom> rule enable 0

// target_http will dump part of the http traffic into files
pom> target add 0 http
Added target with id 0 to rule 0

// enable dumping the images
pom> target parameter set 0 0 dump_img yes

// start the target
pom> target start 0 0

// finaly start the input to capture packets and start dumping
pom> input start

// to save our changes we simply write the configuration
pom> config write
Configuration written in pom.xml.conf


The inputs :
------------
The input modules read packet from a certain source and give the packets to the rule processor.
A input has one or multiple mode. Each mode has its own set of parameters.

- pcap : allow you to read from one or all network device or from a pcap file saved by tcpdump or ethereal for example
- docsis : allow you to read fron a docsis stream using a dvb-c card and the linux-dvb api


The matchs :
------------
The match modules are used to specify the network traffic that you want to match and pass to the targets.

IMPORTANT : You'll have to specify the full header chain to match a packet. For example to match tcp traffic (on IPv4), you have to match in order ethernet, ipv4, tcp.

- docsis : match the docsis protocol used by cable modems
- ethernet : match the ethernet protocol
- ipv4 : match the IPv4 protocol commonly known as ip
- ipv6 : match the IPv6 protocol
- icmp : match the ICMP protocol
- icmpv6 : match the ICMPv6 protocol
- linux_cooked : match linux cooked protocol used by pcap
- rtp : match the RTP protocol used to carry real time voice and video
- tcp : match the TCP protocol
- udp : match the UDP protocol
- undefined : used internaly. do not use in your config !
- vlan : match 802.1Q aka vlan frames


The targets :
-------------
The target modules process the packet and most of the time, saves it or resend it.

- display : display usefull information about the packets being matched
- dump_payload : saves the payload of the last matching protocol into a file
- inject : reinject the matched packets on an specific interface
- irc : dump IRC connection into separate files with irssi-like log format
- pcap : save the packets in a pcap file
- pop : save emails and logins from POP connections into maildir
- rtp : save RTP payload into .au files. Supported payload types are G.711U, G711A, G.721 and G.722
- tap : open a tap interface and send the packets trough it
- tcpkill : works only with tcp packets. Send a TCP RST packet to any matched tcp packet
- tftp : dump files downloaded/uploaded via TFTP
- msn : dump conversations and avatar out of msn conversations
- null : does nothing, used for debugging or as a template


The conntracks :
----------------
The conntrack modules make the application able to recognize different connections among all the packets that it process.
It makes it easy to follow a connection and do something specific with that connection or save some information related to that connection.
The conntrack modules are automatically loaded if found, when the corresponding match is loaded.


The helpers :
-------------
The helper modules are used to recompose part of network packets which were splitted or modified by the network.
Helpers are processed before any matching is done with the rules.
The helper module currently implemented are ipv4, tcp and rtp. TODO : ipv6.
 
- ipv4 : perform ip fragment reassembly
- tcp : perform tcp reordering
- rtp : perform rtp reordering


Bugs :
------
Please report bugs to <[email protected]> with version info and os + architercture.
If it's a crash, please provide a backtrace or a corefile.


License :
--------
packet-o-matic : modular network traffic processor
Copyright (C) 2007 Guy Martin <[email protected]>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA