NGREP(8)		   User Manuals			 NGREP(8)


NAME
       ngrep - network grep


SYNOPSIS
       ngrep  <-hXViwqpevxlDtT>	 <-IO pcap_dump > < -n num > < -d
       dev > < -A num > < -s snaplen > < match expression > < bpf
       filter >


DESCRIPTION
       ngrep  strives  to  provide most of GNU grep's common fea-
       tures, 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, FDDI and null interfaces, and  under-
       stands bpf filter logic in the same fashion as more common
       packet sniffing tools, such as tcpdump(8) and snoop(1).



OPTIONS
       -h     Display help/usage information.


       -X     Treat the match expression as a hexadecimal string.
	      See the explanation of match expression below.


       -V     Display version information.


       -i     Ignore case for the regex expression.


       -w     Match the regex expression as a word.


       -q     Be  quiet;  don't output any information other than
	      packet headers and their payloads (if relevant).


       -p     Don't put the interface into promiscuous mode.


       -e     Show empty packets.   Normally  empty  packets  are
	      discarded	 because  they have no payload to search.
	      If specified, empty packets will be shown,  regard-
	      less of the specified regex expression.


       -v     Invert  the  match; only display packets that don't
	      match.



Linux			    June 2001				1





NGREP(8)		   User Manuals			 NGREP(8)


       -x     Dump packet contents  as	hexadecimal  as	 well  as
	      ASCII.


       -l     Make stdout line buffered.


       -D     When  reading pcap_dump files, replay them at their
	      recorded time intervals (mimic realtime).


       -t     Print  a	timestamp  in  the  form  of   YYYY/MM/DD
	      HH:MM:SS.UUUUUU everytime a packet is matched.


       -T     Print  a	timestamp in the form of +S.UUUUUU, indi-
	      cating the delta between packet matches.


       -s snaplen
	      Set the bpf caplen to snaplen (default 65536).


       -I pcap_dump
	      Input file pcap_dump into ngrep.	 Works	with  any
	      pcap-compatible  dump  file format.  This option is
	      useful for searching for a wide range of	different
	      patterns over the same packet stream.


       -O pcap_dump
	      Output  matched  packets	to a pcap-compatible dump
	      file.  This feature does not interfere with  normal
	      output to stdout.


       -n num Match only num packets total, then exit.


       -d dev By default ngrep will select a default interface to
	      listen on.  Use this option to force ngrep to  lis-
	      ten on interface dev.


       -A num Dump num packets of trailing context after matching
	      a packet.


	match expression
	      A match expression is either  an	extended  regular
	      expression,  or  if  the	-X option is specified, a
	      string signifying a hexadecimal value.  An extended
	      regular expression follows the rules as implemented
	      by the GNU regex library.	 Hexadecimal  expressions



Linux			    June 2001				2





NGREP(8)		   User Manuals			 NGREP(8)


	      can  optionally  be preceded by `0x'.  E.g., `DEAD-
	      BEEF', `0xDEADBEEF'.


	bpf filter
	      Selects a filter that specifies what  packets  will
	      be dumped.  If no bpf filter is given, all IP pack-
	      ets seen on the selected interface will be  dumped.
	      Otherwise,  only	packets	 for  which bpf filter is
	      `true' will be dumped.

       The bpf filter consists of one or more primitives.  Primi-
       tives  usually  consist of an id (name or number) preceded
       by one or more  qualifiers.   There  are	 three	different
       kinds of qualifier:

       type   qualifiers  say  what  kind of thing the id name or
	      number refers to.	 Possible types are host, net and
	      port.   E.g., `host blort', `net 1.2.3', `port 80'.
	      If there is no type qualifier, host is assumed.

       dir    qualifiers specify a particular transfer	direction
	      to  and/or  from	id.  Possible directions are src,
	      dst, src or dst and src and dst.	E.g., `src  foo',
	      `dst  net	 1.2.3',  `src or dst port ftp-data'.  If
	      there is no dir qualifier, src or dst  is	 assumed.
	      For  `null' link layers (i.e. point to point proto-
	      cols such as slip) the inbound and outbound  quali-
	      fiers can be used to specify a desired direction.

       proto  qualifiers  are  restricted  to  ip-only protocols.
	      Possible protos are: tcp ,  udp  and  icmp.   e.g.,
	      `udp  src	 foo'  or  `tcp port 21'.  If there is no
	      proto qualifier, all protocols consistent with  the
	      type  are	 assumed.   E.g., `src foo' means `ip and
	      ((tcp or udp) src foo)', `net bar'  means	 `ip  and
	      (net  bar)',  and	 `port 53' means `ip and ((tcp or
	      udp) port 53)'.

       In addition to the above, there are some	 special  `primi-
       tive'  keywords	that  don't  follow the pattern: gateway,
       broadcast, less, greater and arithmetic expressions.   All
       of these are described below.

       More  complex filter expressions are built up by using the
       words and, or and not to combine primitives.  E.g.,  `host
       blort  and  not	port ftp and not port ftp-data'.  To save
       typing, identical qualifier lists can be	 omitted.   E.g.,
       `tcp  dst  port	ftp or ftp-data or domain' is exactly the
       same as `tcp dst port ftp or tcp dst port ftp-data or  tcp
       dst port domain'.

       Allowable primitives are:




Linux			    June 2001				3





NGREP(8)		   User Manuals			 NGREP(8)


       dst host host
	      True  if	the IP destination field of the packet is
	      host, which may be either an address or a name.


       src host host
	      True if the IP source field of the packet is  host.


       host host
	      True  if either the IP source or destination of the
	      packet is host.  Any of the above host  expressions
	      can  be  prepended  with	the keywords, ip, arp, or
	      rarp as in:
		   ip host host
	      which is equivalent to:



       ether dst ehost
	      True if the ethernet destination address is  ehost.
	      Ehost  may  be  either a name from /etc/ethers or a
	      number (see ethers(3N) for numeric format).

       ether src ehost
	      True if the ethernet source address is ehost.

       ether host ehost
	      True if either the ethernet source  or  destination
	      address is ehost.


       gateway host
	      True  if	the packet used host as a gateway.  I.e.,
	      the ethernet source or destination address was host
	      but  neither  the	 IP source nor the IP destination
	      was host.	 Host must be a name and must be found in
	      both  /etc/hosts	and  /etc/ethers.  (An equivalent
	      expression is
		   ether host ehost and not host host
	      which can be used with either names or numbers  for
	      host / ehost.)


       dst net net
	      True  if	the  IP destination address of the packet
	      has a network number of net. Net may  be	either	a
	      name  from  /etc/networks	 or a network number (see
	      networks(4) for details).


       src net net
	      True if the IP source address of the packet  has	a
	      network number of net.



Linux			    June 2001				4





NGREP(8)		   User Manuals			 NGREP(8)


       net net
	      True if either the IP source or destination address
	      of the packet has a network number of net.


       net net mask mask
	      True if the IP address matches net  with	the  spe-
	      cific netmask.  May be qualified with src or dst.


       net net/len
	      True  if	the  IP address matches net a netmask len
	      bits wide.  May be qualified with src or dst.


       dst port port
	      True if the packet is ip/tcp or ip/udp  and  has	a
	      destination  port value of port.	The port can be a
	      number or a name used in /etc/services (see tcp(4P)
	      and  udp(4P)).   If  a  name is used, both the port
	      number and protocol are checked.	If  a  number  or
	      ambiguous	 name  is  used,  only the port number is
	      checked  (e.g.,  dst  port  513  will  print   both
	      tcp/login	 traffic  and  udp/who	traffic, and port
	      domain will print both  tcp/domain  and  udp/domain
	      traffic).


       src port port
	      True if the packet has a source port value of port.


       port port
	      True if either the source or  destination	 port  of
	      the  packet is port.  Any of the above port expres-
	      sions can be prepended with the  keywords,  tcp  or
	      udp, as in:
		   tcp src port port
	      which matches only tcp packets whose source port is
	      port.


       less length
	      True if the packet has a length less than or  equal
	      to length.  This is equivalent to:
		   len <= length.


       greater length
	      True  if	the  packet  has a length greater than or
	      equal to length.	This is equivalent to:
		   len >= length.





Linux			    June 2001				5





NGREP(8)		   User Manuals			 NGREP(8)


       ip proto protocol
	      True if the packet is an ip packet (see ip(4P))  of
	      protocol	type  protocol.	 Protocol can be a number
	      or one of the names tcp, udp or  icmp.   Note  that
	      the  identifiers	tcp and udp are also keywords and
	      must be escaped via backslash (\), which is  \\  in
	      the C-shell.


       ip broadcast
	      True  if	the packet is an IP broadcast packet.  It
	      checks for both the all-zeroes and all-ones  broad-
	      cast  conventions,  and  looks  up the local subnet
	      mask.


       ip multicast
	      True if the packet is an IP multicast packet.


       ip     Abbreviation for:
		   ether proto ip

       tcp, udp, icmp
	      Abbreviations for:
		   ip proto p
	      where p is one of the above protocols.

       expr relop expr
	      True if the relation holds, where relop is  one  of
	      >,  <,  >=,  <=,	=,  !=, and expr is an arithmetic
	      expression composed of integer constants (expressed
	      in  standard C syntax), the normal binary operators
	      [+, -, *, /, &, |], a length operator, and  special
	      packet  data  accessors.	To access data inside the
	      packet, use the following syntax:
		   proto [ expr : size ]
	      Proto is one of ip, tcp, udp or icmp, and indicates
	      the  protocol  layer  for the index operation.  The
	      byte offset, relative  to	 the  indicated	 protocol
	      layer,  is  given	 by  expr.   Size is optional and
	      indicates the number  of	bytes  in  the	field  of
	      interest;	 it  can be either one, two, or four, and
	      defaults to one.	The length operator, indicated by
	      the keyword len, gives the length of the packet.

	      For example, `ether[0] & 1 != 0' catches all multi-
	      cast traffic.  The expression `ip[0] &  0xf  !=  5'
	      catches all IP packets with options. The expression
	      `ip[6:2] & 0x1fff = 0'  catches  only  unfragmented
	      datagrams	 and  frag  zero of fragmented datagrams.
	      This check is implicitly applied to the tcp and udp
	      index  operations.   For	instance,  tcp[0]  always
	      means the first byte of the TCP header,  and  never



Linux			    June 2001				6





NGREP(8)		   User Manuals			 NGREP(8)


	      means the first byte of an intervening fragment.

       Primitives may be combined using:

	      A	 parenthesized	group of primitives and operators
	      (parentheses are special to the Shell and	 must  be
	      escaped).

	      Negation (`!' or `not').

	      Concatenation (`&&' or `and').

	      Alternation (`||' or `or').

       Negation has highest precedence.	 Alternation and concate-
       nation have equal precedence and associate left to  right.
       Note  that explicit and tokens, not juxtaposition, are now
       required for concatenation.

       If an identifier is given  without  a  keyword,	the  most
       recent keyword is assumed.  For example,
	    not host vs and ace
       is short for
	    not host vs and host ace
       which should not be confused with
	    not ( host vs or ace )

       Expression  arguments  can  be passed to ngrep as either a
       single argument or as  multiple	arguments,  whichever  is
       more  convenient.   Generally,  if the expression contains
       Shell metacharacters, it is easier to pass it as a single,
       quoted argument.	 Multiple arguments are concatenated with
       spaces before being parsed.




DIAGNOSTICS
       Errors from ngrep, libpcap, and the GNU regex library  are
       all output to stderr.


AUTHOR
       Written by Jordan Ritter <jpr5@darkridge.com>.


REPORTING BUGS
       Send bug reports to the author.


NOTES
       ALL YOUR BASE ARE BELONG TO US.

Linux			    June 2001				7


