IPEX(1)

NAME
ipex - packet examination utility

SYNOPSIS
ipex
[ -hvnqbLHxXGdO ] [ -f config ] [ -o outfile ]
[ -r pattern ] [ -c count ] [ -i interface ]
[ -u uid ] [ -P op=arg ] [ -t time ] [ -F file ]
[ -w file ] [ expression ]

DESCRIPTION
The ipex program is similar to ngrep or tcpdump. It allows you to dump packet contents in hexidecimal or plaintext. A very handy tool for debugging network protocols. ipex also gives you the option of running in daemon mode while dumping contents to a specified file. It also allows you to supply a regex RC pattern for printing packets wich contain specific patterns. This man page comes with some fairly descriptive examples.

OPTIONS

-f config
    Pathname to the config to be used to configure pcap. This file would contain pcap filter logic. This option can not be used with -p.

-o outfile
    Pathname to output file. The ipex utility will write to standard out by default. If the file does not exist, then ipex will create it.

-D  Dump ENTIRE packet in hex, including link layer.

-L  Display data link headers with packets.

-r pattern
    Dump packet contents wich only match the supplied regex pattern. See the examples section for a better idea on how this flag works. The REG_EXTENDED bit is set. (Compile modern (``extended'') RE's). This routine implements IEEE Std 1003.2 POSIX.2 regular expression RE's.

-H  Display just the IP headers and nothing else.

-d  When pcap_compile is called, it takes the supplied (``pcap expression'') and generates something called a (``struct bpf_program''). This struct is intern fed to bpf via an ioctl. One of this structure's elements is (``struct bpf_insn''). This determains which packets are to be captured and which are to be ignored. To view the contents of this struct use -d. This is handy for debugging pcap or /dev/bpf.

-X  Display the IP addresses in hexidecimal. This flag comes in handy when you are wanting high speed dumps. Less cpu time is taken converting, formating and displaying the IP addresses this way.

-x  Dump the packet contents in formated hexidecimal. This flag is very handy when debugging protocols.

-u uid
    When running ipex in daemon mode you can set the UID that ipex runs as. This flag requires the numerical ID of the prefered user.

-h  Dump the packet contents in hexidecimal, useful when debugging protcols wich use invisible characters to terminate transmissions. This option is turned off by default.

-c count
    Capture count number of packets then exit. Default is 0 (capture until interrupted)

-i device
    Use the supplied interface to capture packets. If no interface is specified ipex will attempt to locate one by itself.

-v  Dump ipex version and exit

-n  Insert newline \n character in between packets. This option is off by default.

-q  Alert syslog that the interface has gone into promiscuous mode. By default it does not inform syslog.

WARNING: Interface will go into promiscuous mode regardless of this option. The only difference is -q will be noisey about it by notifying syslogd(8).

-b  This will cause ipex to launch itself into the background. It's PID will be written to standard out and to /var/run/ipex.pid. Because its running in the background, it needs a file to dump to. -o MUST be run with -b.

-P op=arg
    ipex will open /dev/mem and scan for a process given op using arg as the ops key. Once it has matched a process, it will compile a pcap expr specifc to -P instructions specified. The following ops are supported:

uid scan processes where the uid is equal to arg.

ruid scan processes where ruid is equal to arg.

pid scan processes where pid is equal to arg.

-G  This will instruct the internal regexp handler to NOT use EXTENDED regexps.

-t time
    Capture packets for time amount of time. time can be suffixed by d for day, h for hour, m for minute, or s for seconds. If no suffix is given, seconds is assumed. The default for this is an unlimited amount of time.

-F file
    Write raw packets to file rather than parsing and printing them out. They can later be printed with the -w option. Standard output is used if file is ``-''. The output generated is reverse compatible with tcpdump's -r option

-w file
    Instead of opening the network interface, read raw packets in from file. This file could be generated with ipex's -F option. It is also reverse compatible with tcpdump's -w option. Standard input is used if file is ``-''.

-O  Run the pcap code optimizer.

SIGNALS
The signal subsystem for ipex is usefull for when the -b flag is used. Signals can be used to send various messages to a daemonized ipex process. The two main messages that are sent are ''rehash'' & ''dump statistics''.

HUP Will cause ipex to rehash it's configuration. This requires that the -f flag be supplied at the command line when ipex is invoked. This feature is most handly when ipex is running continuously in the background or daemonized.

USR1
    Will cause ipex to write the current pcap statistics to ipex.stats in it's current working directory

INT Will cause ipex to dump some statistics about the session and exit returning 0. (successful completion status) Process will recieve this signal upon pressing Ctrl+C.

EXAMPLES

ipex -i ed0 -P 1335

Would cause ipex to open /dev/ed0 as its primary interface and capture packets going to and coming from the process who's pid is 1335.

ipex src port 21 or dst port 21

The above example will filter for all packets coming from or going to port 21 (ftp) and dump them in plaintext meaning, no hexidecimal dumps.

ipex -b -o ipex.dump -x -u1001 tcp

This example will launch ipex into the background filtering all tcp packets and writing them to the file "ipex.dump". Packet dump would be in hexidecimal. The daemonized ipex process would write its pid to "/var/run/ipex.pid". The -u flag will tell ipex to run as the specified uid, in this case 1001.

ipex -f ipex.rules -i lo0 -Xx

This example would cause ipex to read in its ruleset from the file "ipex.rules". It would be reading packets from /dev/lo0 (loop-back). The packet dumps would be in hex, and the src & dst IP addresses would be in hex. The -X flag is usually used for high performance monitoring. (This flag essentially prevents ipex from doing any IP address conversion).

ipex -r'user|pass' src port 6667 or dst port 6667

Filter & capture all packets coming from or going to port 6667, however we only want to print the packets wich contain the strings: "user" OR "pass". ipex's pattern matching is NOT case sensitive.

ipex -p -c 15 icmp

Capture 15 icmp packets & exit.

ipex icmp[0] == 8 or icmp[0] == 0

Print icmp echo requests OR replies.

ipex -t '3d 1m 43' tcp

Capture all TCP packets for 3 days, 1 minute, and 43 seconds.

ipex -F packet.dump

Capture all packets, write the packets to the file (``packet.dump''). Packet dump can be later processed with tcpdump or ipex's -w option.

ipex -w packet.dump udp

Dont open the network interface, read udp packets from (``packet.dump''). This file can be created from tcpdump's -w option or ipex's -F option.

FILES

ipex.stats
    Upon recieving SIGUSR1 ipex will dump the current statistics pertaining to the session in plaintext to this file.

/usr/local/share/doc/ipex
    Various different docs pertaining to the use of pcap filter logic and valid matching regex patterns. Also contains more examples for different packet capturing scenarios.

/var/run/ipex.pid
    Contains current PID of daemonized ipex process.

SEE ALSO
pcap(3), tcpdump(1), bpf(4), re_format(7), regex(3),
kill(1), syslogd(8), ascii(7), ioctl(2)

AUTHORS

 o Founder - C.S. Peron (maneo@bsdpro.com)
 o Lead Developer - C.S. Peron
 o Developer - Daniel B. Hemmerich (code@psu.edu)
 o
 o Development site: http://ipex.sourceforge.net

LIBPCAP
The original libpcap can be downloaded from ftp://ftp.ee.lbl.gov/libpcap.tar.Z)

The current version of libpcap can be downloaded from http://www.tcpdump.org/

BUGS
None known.

Send bugs or source code patches to (maneo@bsdpro.com)