1
2NGREP(8) User Manuals NGREP(8)
3
4
5
7 ngrep - network grep
8
9
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
15
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
25
26
28 -h Display help/usage information.
29
30
31 -N Show sub-protocol number along with single-character identifier
32 (useful when observing raw or unknown protocols).
33
34
35 -X Treat the match expression as a hexadecimal string. See the
36 explanation of match expression below.
37
38
39 -V Display version information.
40
41
42 -i Ignore case for the regex expression.
43
44
45 -w Match the regex expression as a word.
46
47
48 -q Be quiet; don't output any information other than packet headers
49 and their payloads (if relevant).
50
51
52 -p Don't put the interface into promiscuous mode.
53
54
55 -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
60
61 -v Invert the match; only display packets that don't match.
62
63
64 -x Dump packet contents as hexadecimal as well as ASCII.
65
66
67 -l Make stdout line buffered.
68
69
70 -D When reading pcap_dump files, replay them at their recorded time
71 intervals (mimic realtime).
72
73
74 -t Print a timestamp in the form of YYYY/MM/DD HH:MM:SS.UUUUUU
75 everytime a packet is matched.
76
77
78 -T Print a timestamp in the form of +S.UUUUUU, indicating the delta
79 between packet matches.
80
81
82 -R Do not try to drop privileges to the DROPPRIVS_USER.
83
84 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
91 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
100
101 -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
107
108 -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
114
115 -P char
116 Specify an alternate character to signify non-printable charac‐
117 ters when displayed. The default is ``.''.
118
119
120 -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
131
132 -s snaplen
133 Set the bpf caplen to snaplen (default 65536).
134
135
136 -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
141
142 -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
147
148 -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
152
153 -n num Match only num packets total, then exit.
154
155
156 -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
159
160 -A num Dump num packets of trailing context after matching a packet.
161
162
163 -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
171
172 -c cols
173 Ignore the detected terminal width and force the column width to
174 the specified size.
175
176
177 -P char
178 Change the non-printable character from the default ``.'' to the
179 character specified.
180
181
182 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
190
191 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
197 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
201 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
206 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
214 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
221 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
225 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
232 Allowable primitives are:
233
234
235 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
239
240 src host host
241 True if the IP source field of the packet is host.
242
243
244 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
251
252
253 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
258 ether src ehost
259 True if the ethernet source address is ehost.
260
261 ether host ehost
262 True if either the ethernet source or destination address is
263 ehost.
264
265
266 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
276
277 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
282
283 src net net
284 True if the IP source address of the packet has a network number
285 of net.
286
287
288 net net
289 True if either the IP source or destination address of the
290 packet has a network number of net.
291
292
293 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
297
298 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
302
303 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
313
314 src port port
315 True if the packet has a source port value of port.
316
317
318 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
325
326 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
331
332 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
337
338 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
345
346 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
351
352 ip multicast
353 True if the packet is an IP multicast packet.
354
355
356 ip Abbreviation for:
357 ether proto ip
358
359 tcp, udp, icmp
360 Abbreviations for:
361 ip proto p
362 where p is one of the above protocols.
363
364 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
380 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
389 Primitives may be combined using:
390
391 A parenthesized group of primitives and operators (parentheses
392 are special to the Shell and must be escaped).
393
394 Negation (`!' or `not').
395
396 Concatenation (`&&' or `and').
397
398 Alternation (`||' or `or').
399
400 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
404 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
412 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
418
420 Errors from ngrep, libpcap, and the GNU regex library are all output to
421 stderr.
422
423
425 Written by Jordan Ritter <jpr5@darkridge.com>.
426
427
429 Please report bugs to the ngrep's Sourceforge Bug Tracker, located at
430
431 http://sourceforge.net/projects/ngrep/
432
433 Non-bug, non-feature-request general feedback should be sent to the
434 author directly by email.
435
436
438 ALL YOUR BASE ARE BELONG TO US.
439
440
441
442*nux November 2006 NGREP(8)