Man Linux: Main Page and Category List


       ngrep - network grep


       ngrep  <-hNXViwqpevxlDtTRM> <-IO pcap_dump > < -n num > < -d dev > < -A
       num > < -s snaplen > < -S limitlen > < -W normal|byline|single|none > <
       -c cols > < -P char > < -F file > < match expression > < bpf filter >


       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,  FDDI  and  null interfaces, and understands bpf
       filter logic in the same fashion as more common packet sniffing  tools,
       such as tcpdump(8) and snoop(1).


       -h     Display help/usage information.

       -N     Show  sub-protocol number along with single-character identifier
              (useful when observing raw or unknown protocols).

       -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,  regardless  of  the  specified  regex

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

       -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, indicating the delta
              between packet matches.

       -R     Do not try to drop privileges to the DROPPRIVS_USER.

              ngrep makes no effort to validate input  from  live  or  offline
              sources  as it is focused more on performance and handling large
              amounts of data than protocol correctness, which is most often a
              fair assumption to make.  However, sometimes it matters and thus
              as a rule ngrep will try to  be  defensive  and  drop  any  root
              privileges it might have.

              There  exist  scenarios  where  this  behaviour  can  become  an
              obstacle, so this option is provided to end-users  who  want  to
              disable  this  feature,  but must do so with an understanding of
              the  risks.   Packets  can  be  randomly   malformed   or   even
              specifically  designed  to overflow sniffers and take control of
              them, and revoking root privileges is currently  the  only  risk
              mitigation  ngrep  employs  against  such  an  attack.  Use this
              option and turn it off at your own risk.

       -c cols
              Explicitly set the console width to ‘‘cols’’.  Note that this is
              the  console  width, and not the full width of what ngrep prints
              out as payloads; depending on the output mode  ngrep  may  print
              less than ‘‘cols’’ bytes per line (indentation).

       -F file
              Read  in  the bpf filter from the specified filename.  This is a
              compatibility option for users familiar  with  tcpdump.   Please
              note  that  specifying  ‘‘-F’’  will  override  any  bpf  filter
              specified on the command-line.

       -P char
              Specify  an  alternate  character   to   signify   non-printable
              characters when displayed.  The default is ‘‘.’’.

       -W normal|byline|single|none
              Specify  an alternate manner for displaying packets, when not in
              hexadecimal  mode.   The   ‘‘byline’’   mode   honors   embedded
              linefeeds,  wrapping  text  only  when a linefeed is encountered
              (useful for observing HTTP  transactions,  for  instance).   The
              ‘‘none’’  mode  doesn’t  wrap  under  any  circumstance  (entire
              payload is displayed on  one  line).   The  ‘‘single’’  mode  is
              conceptually  the  same  as  ‘‘none’’,  except  that  everything
              including IP and source/destination header information is all on
              one  line.   ‘‘normal’’ is the default mode and is only included
              for completeness.  This option is incompatible with ‘‘-x’’.

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

       -S limitlen
              Set the upper limit on the size of packets that ngrep will  look
              at.   Useful  for  looking  at only the first N bytes of packets
              without changing the BPF snaplen.

       -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 listen on interface dev.

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

       -c cols
              Ignore the detected terminal width and force the column width to
              the specified size.

       -P char
              Change the non-printable character from the default ‘‘.’’ to the
              character specified.

       -K num Kill matching  TCP  connections  (like  tcpkill).   The  numeric
              argument controls how many RST segments are sent.

        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
              can   optionally   be   preceded  by  ‘0x’.   E.g.,  ‘DEADBEEF’,

        bpf filter
              Selects a filter that specifies what packets will be dumped.  If
              no  bpf  filter  is  given,  all IP packets 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.  Primitives 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

       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  protocols  such  as
              slip) the inbound and outbound qualifiers 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 ‘primitive’ 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

       Allowable primitives are:

       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

       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  /

       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.

       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 specific 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 expressions 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.

       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  broadcast 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 multicast 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 means the first byte of an intervening

       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 concatenation 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.


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


       Written by Jordan Ritter <>.


       Please report bugs to the ngrep’s Sourceforge Bug Tracker, located at


       Non-bug,  non-feature-request  general  feedback  should be sent to the
       author directly by email.



*nux                             November 2006