1NGREP(8) User Manuals NGREP(8)
3
7 ngrep - network grep
8
11 ngrep <-hNXViwqpevxlDtTRM> <-IO pcap_dump > < -n num > < -d dev > < -A
12 num > < -s snaplen > < -S limitlen > < -W normal|byline|single|none > <
13 -c cols > < -P char > < -F file > < match expression > < bpf filter >
14
17 ngrep strives to provide most of GNU grep's common features, applying
18 them to the network layer. ngrep is a pcap-aware tool that will allow
19 you to specify extended regular expressions to match against data pay‐
20 loads of packets. It currently recognizes TCP, UDP and ICMP across
21 Ethernet, PPP, SLIP, FDDI and null interfaces, and understands bpf fil‐
22 ter logic in the same fashion as more common packet sniffing tools,
23 such as tcpdump(8) and snoop(1).
24
28 -h Display help/usage information.
29 -N Show sub-protocol number along with single-character identifier
32 (useful when observing raw or unknown protocols).
33 -X Treat the match expression as a hexadecimal string. See the
36 explanation of match expression below.
37 -V Display version information.
40 -i Ignore case for the regex expression.
43 -w Match the regex expression as a word.
46 -q Be quiet; don't output any information other than packet headers
49 and their payloads (if relevant).
50 -p Don't put the interface into promiscuous mode.
53 -e Show empty packets. Normally empty packets are discarded
56 because they have no payload to search. If specified, empty
57 packets will be shown, regardless of the specified regex expres‐
58 sion.
59 -v Invert the match; only display packets that don't match.
62 -x Dump packet contents as hexadecimal as well as ASCII.
65 -l Make stdout line buffered.
68 -D When reading pcap_dump files, replay them at their recorded time
71 intervals (mimic realtime).
72 -t Print a timestamp in the form of YYYY/MM/DD HH:MM:SS.UUUUUU
75 everytime a packet is matched.
76 -T Print a timestamp in the form of +S.UUUUUU, indicating the delta
79 between packet matches.
80 -R Do not try to drop privileges to the DROPPRIVS_USER.
83 ngrep makes no effort to validate input from live or offline
85 sources as it is focused more on performance and handling large
86 amounts of data than protocol correctness, which is most often a
87 fair assumption to make. However, sometimes it matters and thus
88 as a rule ngrep will try to be defensive and drop any root priv‐
89 ileges it might have.
90 There exist scenarios where this behaviour can become an obsta‐
92 cle, so this option is provided to end-users who want to disable
93 this feature, but must do so with an understanding of the risks.
94 Packets can be randomly malformed or even specifically designed
95 to overflow sniffers and take control of them, and revoking root
96 privileges is currently the only risk mitigation ngrep employs
97 against such an attack. Use this option and turn it off at your
98 own risk.
99 -c cols
102 Explicitly set the console width to ``cols''. Note that this is
103 the console width, and not the full width of what ngrep prints
104 out as payloads; depending on the output mode ngrep may print
105 less than ``cols'' bytes per line (indentation).
106 -F file
109 Read in the bpf filter from the specified filename. This is a
110 compatibility option for users familiar with tcpdump. Please
111 note that specifying ``-F'' will override any bpf filter speci‐
112 fied on the command-line.
113 -P char
116 Specify an alternate character to signify non-printable charac‐
117 ters when displayed. The default is ``.''.
118 -W normal|byline|single|none
121 Specify an alternate manner for displaying packets, when not in
122 hexadecimal mode. The ``byline'' mode honors embedded line‐
123 feeds, wrapping text only when a linefeed is encountered. The
124 ``none'' mode doesn't wrap under any circumstance (entire pay‐
125 load is displayed on one line). The ``single'' mode is concep‐
126 tually the same as ``none'', except that everything including IP
127 and source/destination header information is all on one line.
128 ``normal'' is the default mode and is only included for com‐
129 pleteness. This option is incompatible with ``-x''.
130 -s snaplen
133 Set the bpf caplen to snaplen (default 65536).
134 -S limitlen
137 Set the upper limit on the size of packets that ngrep will look
138 at. Useful for looking at only the first N bytes of packets
139 without changing the BPF snaplen.
140 -I pcap_dump
143 Input file pcap_dump into ngrep. Works with any pcap-compatible
144 dump file format. This option is useful for searching for a
145 wide range of different patterns over the same packet stream.
146 -O pcap_dump
149 Output matched packets to a pcap-compatible dump file. This
150 feature does not interfere with normal output to stdout.
151 -n num Match only num packets total, then exit.
154 -d dev By default ngrep will select a default interface to listen on.
157 Use this option to force ngrep to listen on interface dev.
158 -A num Dump num packets of trailing context after matching a packet.
161 -W normal|byline|none
164 Alter the method by which ngrep displays packet payload. ``nor‐
165 mal'' mode represents the standard behaviour, ``byline''
166 instructs ngrep to respect embedded linefeeds (useful for
167 observing HTTP transactions, for instance), and ``none'' results
168 in the payload on one single line (useful for scripted process‐
169 ing of ngrep output).
170 -c cols
173 Ignore the detected terminal width and force the column width to
174 the specified size.
175 -P char
178 Change the non-printable character from the default ``.'' to the
179 character specified.
180 match expression
183 A match expression is either an extended regular expression, or
184 if the -X option is specified, a string signifying a hexadecimal
185 value. An extended regular expression follows the rules as
186 implemented by the GNU regex library. Hexadecimal expressions
187 can optionally be preceded by `0x'. E.g., `DEADBEEF', `0xDEAD‐
188 BEEF'.
189 bpf filter
192 Selects a filter that specifies what packets will be dumped. If
193 no bpf filter is given, all IP packets seen on the selected
194 interface will be dumped. Otherwise, only packets for which bpf
195 filter is `true' will be dumped.
196 The bpf filter consists of one or more primitives. Primitives usually
198 consist of an id (name or number) preceded by one or more qualifiers.
199 There are three different kinds of qualifier:
200 type qualifiers say what kind of thing the id name or number refers
202 to. Possible types are host, net and port. E.g., `host blort',
203 `net 1.2.3', `port 80'. If there is no type qualifier, host is
204 assumed.
205 dir qualifiers specify a particular transfer direction to and/or
207 from id. Possible directions are src, dst, src or dst and src
208 and dst. E.g., `src foo', `dst net 1.2.3', `src or dst port
209 ftp-data'. If there is no dir qualifier, src or dst is assumed.
210 For `null' link layers (i.e. point to point protocols such as
211 slip) the inbound and outbound qualifiers can be used to specify
212 a desired direction.
213 proto qualifiers are restricted to ip-only protocols. Possible protos
215 are: tcp , udp and icmp. e.g., `udp src foo' or `tcp port 21'.
216 If there is no proto qualifier, all protocols consistent with
217 the type are assumed. E.g., `src foo' means `ip and ((tcp or
218 udp) src foo)', `net bar' means `ip and (net bar)', and `port
219 53' means `ip and ((tcp or udp) port 53)'.
220 In addition to the above, there are some special `primitive' keywords
222 that don't follow the pattern: gateway, broadcast, less, greater and
223 arithmetic expressions. All of these are described below.
224 More complex filter expressions are built up by using the words and, or
226 and not to combine primitives. E.g., `host blort and not port ftp and
227 not port ftp-data'. To save typing, identical qualifier lists can be
228 omitted. E.g., `tcp dst port ftp or ftp-data or domain' is exactly the
229 same as `tcp dst port ftp or tcp dst port ftp-data or tcp dst port
230 domain'.
231 Allowable primitives are:
233 dst host host
236 True if the IP destination field of the packet is host, which
237 may be either an address or a name.
238 src host host
241 True if the IP source field of the packet is host.
242 host host
245 True if either the IP source or destination of the packet is
246 host. Any of the above host expressions can be prepended with
247 the keywords, ip, arp, or rarp as in:
248 ip host host
249 which is equivalent to:
250 ether dst ehost
254 True if the ethernet destination address is ehost. Ehost may be
255 either a name from /etc/ethers or a number (see ethers(3N) for
256 numeric format).
257 ether src ehost
259 True if the ethernet source address is ehost.
260 ether host ehost
262 True if either the ethernet source or destination address is
263 ehost.
264 gateway host
267 True if the packet used host as a gateway. I.e., the ethernet
268 source or destination address was host but neither the IP source
269 nor the IP destination was host. Host must be a name and must
270 be found in both /etc/hosts and /etc/ethers. (An equivalent
271 expression is
272 ether host ehost and not host host
273 which can be used with either names or numbers for host /
274 ehost.)
275 dst net net
278 True if the IP destination address of the packet has a network
279 number of net. Net may be either a name from /etc/networks or a
280 network number (see networks(4) for details).
281 src net net
284 True if the IP source address of the packet has a network number
285 of net.
286 net net
289 True if either the IP source or destination address of the
290 packet has a network number of net.
291 net net mask mask
294 True if the IP address matches net with the specific netmask.
295 May be qualified with src or dst.
296 net net/len
299 True if the IP address matches net a netmask len bits wide. May
300 be qualified with src or dst.
301 dst port port
304 True if the packet is ip/tcp or ip/udp and has a destination
305 port value of port. The port can be a number or a name used in
306 /etc/services (see tcp(4P) and udp(4P)). If a name is used,
307 both the port number and protocol are checked. If a number or
308 ambiguous name is used, only the port number is checked (e.g.,
309 dst port 513 will print both tcp/login traffic and udp/who traf‐
310 fic, and port domain will print both tcp/domain and udp/domain
311 traffic).
312 src port port
315 True if the packet has a source port value of port.
316 port port
319 True if either the source or destination port of the packet is
320 port. Any of the above port expressions can be prepended with
321 the keywords, tcp or udp, as in:
322 tcp src port port
323 which matches only tcp packets whose source port is port.
324 less length
327 True if the packet has a length less than or equal to length.
328 This is equivalent to:
329 len <= length.
330 greater length
333 True if the packet has a length greater than or equal to length.
334 This is equivalent to:
335 len >= length.
336 ip proto protocol
339 True if the packet is an ip packet (see ip(4P)) of protocol type
340 protocol. Protocol can be a number or one of the names tcp, udp
341 or icmp. Note that the identifiers tcp and udp are also key‐
342 words and must be escaped via backslash (\), which is \\ in the
343 C-shell.
344 ip broadcast
347 True if the packet is an IP broadcast packet. It checks for
348 both the all-zeroes and all-ones broadcast conventions, and
349 looks up the local subnet mask.
350 ip multicast
353 True if the packet is an IP multicast packet.
354 ip Abbreviation for:
357 ether proto ip
358 tcp, udp, icmp
360 Abbreviations for:
361 ip proto p
362 where p is one of the above protocols.
363 expr relop expr
365 True if the relation holds, where relop is one of >, <, >=, <=,
366 =, !=, and expr is an arithmetic expression composed of integer
367 constants (expressed in standard C syntax), the normal binary
368 operators [+, -, *, /, &, |], a length operator, and special
369 packet data accessors. To access data inside the packet, use
370 the following syntax:
371 proto [ expr : size ]
372 Proto is one of ip, tcp, udp or icmp, and indicates the protocol
373 layer for the index operation. The byte offset, relative to the
374 indicated protocol layer, is given by expr. Size is optional
375 and indicates the number of bytes in the field of interest; it
376 can be either one, two, or four, and defaults to one. The
377 length operator, indicated by the keyword len, gives the length
378 of the packet.
379 For example, `ether[0] & 1 != 0' catches all multicast traffic.
381 The expression `ip[0] & 0xf != 5' catches all IP packets with
382 options. The expression `ip[6:2] & 0x1fff = 0' catches only
383 unfragmented datagrams and frag zero of fragmented datagrams.
384 This check is implicitly applied to the tcp and udp index opera‐
385 tions. For instance, tcp[0] always means the first byte of the
386 TCP header, and never means the first byte of an intervening
387 fragment.
388 Primitives may be combined using:
390 A parenthesized group of primitives and operators (parentheses
392 are special to the Shell and must be escaped).
393 Negation (`!' or `not').
395 Concatenation (`&&' or `and').
397 Alternation (`||' or `or').
399 Negation has highest precedence. Alternation and concatenation have
401 equal precedence and associate left to right. Note that explicit and
402 tokens, not juxtaposition, are now required for concatenation.
403 If an identifier is given without a keyword, the most recent keyword is
405 assumed. For example,
406 not host vs and ace
407 is short for
408 not host vs and host ace
409 which should not be confused with
410 not ( host vs or ace )
411 Expression arguments can be passed to ngrep as either a single argument
413 or as multiple arguments, whichever is more convenient. Generally, if
414 the expression contains Shell metacharacters, it is easier to pass it
415 as a single, quoted argument. Multiple arguments are concatenated with
416 spaces before being parsed.
417
420 Errors from ngrep, libpcap, and the GNU regex library are all output to
421 stderr.
422
425 Written by Jordan Ritter <jpr5@darkridge.com>.
426
429 Please report bugs to the ngrep's Sourceforge Bug Tracker, located at
430 http://sourceforge.net/projects/ngrep/
432 Non-bug, non-feature-request general feedback should be sent to the
434 author directly by email.
435
438 ALL YOUR BASE ARE BELONG TO US.
439*nux November 2006 NGREP(8)