$Id: README.txt,v 1.5 2006/11/28 13:37:34 jpr5 Exp $ Program: ngrep Author: Jordan Ritter Version: 1.45 (11.18.2006) Goal: A program that mimicks as much functionality in GNU grep as possible, applied at the network layer. Description: ngrep strives to provide most of GNU grep's common features, applying them to the network layer. ngrep is a pcap-aware tool that will allow you to specify extended regular or hexadecimal expressions to match against data payloads of packets. It currently recognizes IPv4/6, TCP, UDP, ICMPv4/6, IGMP and Raw across Ethernet, PPP, SLIP, FDDI, Token Ring and null interfaces, and understands BPF filter logic in the same fashion as more common packet sniffing tools, such as tcpdump and snoop. Usage: ngrep <-IO pcap_dump> <-n num> <-d dev> <-A num> <-s snaplen> <-S limitlen> <-W normal|byline|single|none> <-c cols> <-P char> <-F file> -h is help/usage -V is version information -q is be quiet (don't print packet reception hash marks) -e is show empty packets -i is ignore case -v is invert match -R is don't do privilege revocation logic -x is print in alternate hexdump format -X is interpret match expression as hexadecimal -w is word-regex (expression must match as a word) -p is don't go into promiscuous mode -l is make stdout line buffered -D is replay pcap_dumps with their recorded time intervals -t is print timestamp every time a packet is matched -T is print delta timestamp every time a packet is matched -M is don't do multi-line match (do single-line match instead) -I is read packet stream from pcap format file pcap_dump -O is dump matched packets in pcap format to pcap_dump -n is look at only num packets -A is dump num packets after a match -s is set the bpf caplen -S is set the limitlen on matched packets -W is set the dump format (normal, byline, single, none) -c is force the column width to the specified size -P is set the non-printable display char to what is specified -F is read the bpf filter from the specified file -N is show sub protocol number On UNIX: -d is use specified device instead of the pcap default On Win32: -d is use specified device (index) instead of the pcap default -L is show the winpcap device list index Tips: o When the intention is to match all packets (i.e. blank regex), it is technically faster to use an empty regex (``'') than to use ``.*'' or ``*''. o When sniffing interfaces that are very busy or are seeing large amounts of packet traffic, make sure to craft a BPF filter to limit what PCAP has to deliver to ngrep. The ngrep parser takes a certain amount of time and while negligible on a slow interface, it can add up very quickly on a busy one. o Hexadecimal expressions can be in straight numeric form, 'DEADBEEF', or in symbolic form, '0xDEADBEEF'. A byte is the smallest unit of measure you can match against. o As of v1.28, ngrep doesn't require a match expression. However, there are cases where ngrep can be confused and think part of your bpf filter is the match expression, as in: % ngrep not port 80 interface: eth0 (192.168.1.0/255.255.255.0) filter: ip and ( port 80 ) match: not In cases like this, you will need to specify a blank match expression: % ngrep '' not port 80 interface: eth0 (192.168.1.0/255.255.255.0) filter: ip and ( not port 80 ) Please see http://ngrep.sourceforge.net/usage.html for more detailed examples describing ngrep usage. Miscellany: Please see the ``doc/CREDITS.txt'' file for a listing of the people who helped make ngrep what it is today. Also, please note that ngrep is released under a BSD-style license, though it currently relies upon the GNU regex library, which is protected under the GPL. Also, it is _highly recommended_ that you upgrade to the latest version of libpcap. All versions 0.5 and more recent fix really annoying and in some cases fatal problems with the packet capture library. If you happen to be using Windows, please check the WinPcap site to see if there are any updates. Useful sites: o Unix libpcap: http://www.tcpdump.org/release/ o Windows libpcap: http://www.winpcap.org/install/ Known Working Platforms: o Linux 2.0 - 2.6 (RH6+, SuSE, TurboLinux, Debian, Gentoo, Ubuntu, Mandrake, Slackware)/x86 RedHat/alpha Cobalt (Qube2) Linux/MIPS o Solaris 2.5.1, 2.6/SPARC, Solaris 7, Solaris 8/SPARC, Solaris 9/SPARC o FreeBSD 2.2.5, 3.1, 3.2, 3.4-RC, 3.4-RELEASE, 4.0, 5.0 o OpenBSD 2.4 (after upgrading pcap from 0.2), 2.9, 3.0, 3.1 o NetBSD 1.5/SPARC o Digital Unix V4.0D (OSF/1), Tru64 5.0, Tru64 5.1A o HPUX 11 o IRIX o AIX 4.3.3.0/PowerPC o BeOS R5 o Mac OS X 10.2, 10.2.6, 10.3x, 10.4 o Windows 95, 98, NT, 2000, XP, 2003/x86 In other words, pretty much everything. Support, Feedback, & Patches If you need help, have constructive feedback, or would like to submit a patch, please visit ngrep's project at SourceForge and use the online tools there. It will help the author better manage the various requests and patches so that nothing is lost or missed (as has been the case in the past, unfortunately). ngrep Project Website: http://sourceforge.net/projects/ngrep/