tcpreplay/man/.svn/text-base/tcpprep.1.svn-base

.\" yo there.
.TH TCPPREP 1  "22 April 2004"
.SH NAME
tcpprep \- create a tcpreplay cache file from a saved capture file
.SH SYNOPSIS
.na
.B tcpprep
[
.B \-a
.B \-n
[
.I bridge
|
.I router
|
.I client
|
.I server
] |
.B \-c
.I CIDR,...
|
.B \-r 
.I regex
|
.B \-p
] [
.B \-h 
|
.B \-V
] [
.B \-i
.I pcapfile
] [
.B \-v
] [
.B \-m
.I minmask
] [
.B \-M
.I maxmask
] [
.B \-N
.I client
|
.I server
] [
.B \-R
.I ratio
] [
.B \-x
.I include
|
.B \-X
.I exclude
] [
.B \-C 
.I comment
]
.B \-o
|
.B \-P
.I cachefile
.br
.ad
.SH DESCRIPTION
.LP
.I Tcpprep
is a program for creating a cache file for later use with \fItcpreplay(8)\fP.  By
using tcpprep to pre-process a pcap, tcpreplay in dual-nic mode can
match the performance of the traditional tcpreplay single-nic mode.
.LP
The basic operation of
.I tcpprep
is to compare each packet from it's \fIinput file\fP and compare it to either 
a \fIregular expression\fP or against a list of \fICIDR\fP's.  It then writes the 
result of this comparison to the \fIcache file\fP for later use with \fItcpreplay\fP.
This \fIcache file\fP is a string of characters, with each bit representing 
a single packet.  This provides an efficent and portable means of storing the 
necessary data.
.SH OPTIONS
.LP
.TP
.B \-a
Auto mode.  Tcpprep will try to learn the roles of systems on the
network, and split traffic between the two interfaces based upon whether a
system is classified as a "server" or "client".  Servers are sent out the
primary interface, clients out the secondary.  Requires the use of -n and 
excludes the use of -c, -p and -r.
.TP
.B \-c
CIDR mode. Specify a list of CIDR's (network1/masklen1,network2/masklen2,...) 
to match against the source IP of each packet.  Packets matching any of the 
CIDR's are sent out the primary interface; remaining packets are sent out 
the secondary interface.  Can't be used with -r or -a.
.TP
.B \-C 
Imbed a comment in the tcpprep cache file which can be later viewed via -P.
.TP
.B \-h
Help.
.TP
.B \-i
Input file (pcap format)
.TP
.B \-m
Minimum mask length.  Used in auto/router mode to set the minimum valid
network size.  Defaults to 30 (bits).
.TP
.B \-M
Maximum mask length.  Used in auto/router mode to set the maximum valid
network size.  Defaults to 8 (bits).
.TP
.B \-n
Network type.  Used to specify the network type in auto mode as either bridge,
client, server or router.  Required with -a.

Bridge mode processes each packet to try to determine if the sender is a 
client or server.  Once all the packets are processed, the results are weighed
according to the server/client ratio (-R) and systems are assigned an
interface.  If tcpprep is unable to determine what role a system plays, tcpprep
will abort.

Client mode works just like bridge mode, except that unclassified systems are
treated as clients.

Server mode works just like bridge mode, except that unclassified systems are
treated as servers.

Router mode works just like bridge mode, except that after weighing is done, 
systems which are undetermined are considered a server if they fall inside a 
network known to contain other servers.  Router mode will never abort on
systems which can't be determined.

Router mode trys to build a list of networks containing only servers
and unknown IP's.  It starts out with very large networks (8 bit netmask by 
default, change with -M) and works it's way down to the minimum mask len (-m).
If tcpprep is unable to determine one or more networks which only contains
servers and unknowns, tcpprep will abort.

Port mode looks at the source/destination port of the TCP or UDP packet.
Client traffic goes out the primary interface, and server traffic out the
secondary interface.  Non-TCP and UDP traffic goes out the same interface
as non-IP traffic does.  Note that this mode does not track IP addresses;
so an IP may appear to jump between interfaces depending on if it is the
client or server.

In all cases, servers are sent out the primary interface, and clients out the 
secondary.
.TP
.B \-N
Non-IP packet classification.  Non-IP datagrams (such as arp) currently aren't
handled by tcpprep.  This option allows you to define an interface to send them
out.  Default is client.
.TP
.B \-o
Output file (tcpreplay cache file)
.TP
.B \-p
Port mode.  Split TCP/UDP traffic based on the destination port.
.TP
.B -P
Print the embeded tcpprep cache file comment.
.TP
.B \-r
Regex mode.  Specifies a regular expression to match against the source ip 
of each packet.  Packets matching are sent out the primary interface; 
remaining packets are sent out the secondary interface.  Can't be used 
with -a or -c.
.TP
.B \-R
The ratio of server connections to client connections necessary to be 
classified as a server in auto mode.  A system is classified as a server if
[# server connections] >= ([# client connections] * [ratio]).  Default is:
2.0
.TP
.B \-x
Specifies which packets from the capture file(s) to send.  Can be one of:
.br
.br
S:<CIDR1>,... - Src IP must match specified CIDR(s)
.br
D:<CIDR1>,... - Dst IP must match specified CIDR(s)
.br
B:<CIDR1>,... - Both src and dst addresses must match
.br
E:<CIDR1>,... - Either src or dst address must match
.br
P:<list>      - Must be one of the listed packets where the list corresponds to the
packet number in the capture file.  Ex: -x P:1-5,9,15 would only send packets 1 
through 5, 9 and 15.
.br
F:"<filter>"  - BPF filter.  See the tcpdump(8) man page for syntax.
.TP
.B \-X
Specifies which packets from the capture file(s) to NOT send.  Can be one of:
.br
S:<CIDR1>,... - Src IP must match specified CIDR(s)
.br
D:<CIDR1>,... - Dst IP must match specified CIDR(s)
.br
B:<CIDR1>,... - Both src and dst addresses must match
.br
E:<CIDR1>,... - Either src or dst address must match
.br
P:<list>      - Must be one of the listed packets where the list corresponds to the
packet number in the capture file.  Ex: -X P:1-5,9,15 would send all packets except 1 
through 5, 9 and 15.
.TP
.B \-v
Enable verbose status printing to stderr. (Probably only interesting 
for large input files.)
.TP
.B \-V
Print version info and exit.
.SH "SEE ALSO"
tcpdump(8), tcpreplay(8), capinfo(1), editcap(1)
.SH AUTHOR
Aaron Turner
.LP
The current version is packaged with tcpreplay which is available via HTTP:
.LP
.RS
.I http://www.sourceforge.net/projects/tcpreplay/
.RE
.SH BUGS
There may be a memory leak in the auto mode portion of the code.  I'm seeing
tcpprep growing to almost 15MB on a 900MB input file.
.LP
Accuracy in auto modes and handling of non-IP datagrams could be improved by
various means.
.LP
It would be nice to support compressed files and other file formats than just libpcap.
.LP
Please send bug reports to aturner@pobox.com.