
Program: ngrep 
Author: Jordan Ritter <jpr5@darkridge.com>
Version: 1.38 (6.21.2000)


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 expressions to match
  against data payloads of packets.  It currently recognizes TCP, UDP
  and ICMP across Ethernet, PPP, SLIP 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 <-hXViwqevxlDtT> <-IO pcap_dump> <-n num> <-d dev> <-A num>
			 <match expression> <bpf filter>

  -h  is help/usage
  -X  is interpret match expression as hexadecimal
  -V  is version information
  -i  is ignore case
  -w  is word-regex (expression must match as a word)
  -q  is be quiet
  -e  is show empty packets
  -v  is invert match
  -x  is print in alternate hexdump format
  -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
  -I  is dump matched packets in pcap format to pcap_dump
  -O  is read packet stream from pcap format file pcap_dump 
  -n  is look at only num packets
  -d  is use a device different from the default (pcap)
  -A  is dump num packets after a match

  <match expression>   is either an extended regular expression or a
                       hexadecimal string.  see the man page for more
                       information. 
                       
  <bpf filter>         is any bpf filter statement.


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 Always try to craft a BPF filter; this is doubly important on
    interfaces that are very busy and are seeing large amounts of
    packets.  The 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.  There are
    cases where it will 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 )


Known Working Platforms:

  o Linux 2.0, 2.2, 2.3 --
     (RH6+, SuSE, TurboLinux, Debian)/x86
     RedHat/alpha
     Debian/powerpc
     Cobalt (Qube2) Linux/MIPS
  o Solaris 2.5.1, 2.6/SPARC, Solaris 7
  o FreeBSD 2.2.5, 3.1, 3.2, 3.4-RC, 3.4-RELEASE, 4.0
  o OpenBSD 2.4 (after upgrading pcap from 0.2)
  o Digital Unix V4.0D (OSF/1)


Miscellany:

  Please see the CREDITS 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.
