readme.unix.txt

ngrep strives to provide most of GNU grep s common features, applying them to the network layer. ngr

Program: ngrep
Author: Jordan Ritter <[e-mail]>
Version: 1.41 (8.9.2003)


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 TCP, UDP and ICMP 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 <-hXViwqpevxlDtT> <-IO pcap_dump> <-n num> <-d dev> <-A num>
                          <-s snaplen> <-S limitlen> <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
  -p  is don't go into promiscuous mode
  -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
  -s  is set the bpf caplen
  -S  is set the limitlen on matched packets
  -O  is dump matched packets in pcap format to pcap_dump
  -I  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 )


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.

  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://winpcap.polito.it/install/


Known Working Platforms:

  o Linux 2.0 - 2.4
     (RH6+, SuSE, TurboLinux, Debian)/x86
     RedHat/alpha
     Cobalt (Qube2) Linux/MIPS
     Slackware 7, 8.1
     Gentoo
  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