| blob | ca969e22b4b6051072242837d374fa16cab1225f |
1 '\" te
2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SNOOP 1M "Feb 18, 2009"
7 .SH NAME
8 snoop \- capture and inspect network packets
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBsnoop\fR [\fB-aqrCDINPSvV\fR] [\fB-t\fR [r | a | d]] [\fB-c\fR \fImaxcount\fR]
13 [\fB-d\fR \fIdevice\fR] [\fB-i\fR \fIfilename\fR] [\fB-n\fR \fIfilename\fR] [\fB-o\fR \fIfilename\fR]
14 [\fB-p\fR \fIfirst\fR [, \fIlast\fR]] [\fB-s\fR \fIsnaplen\fR] [\fB-x\fR \fIoffset\fR [, \fIlength\fR]]
15 [\fIexpression\fR]
16 .fi
18 .SH DESCRIPTION
19 .sp
20 .LP
21 From a datalink or IP interface, \fBsnoop\fR captures packets and displays
22 their contents. If the datalink or IP interface is not specified, \fBsnoop\fR
23 will pick a datalink to use, giving priority to datalinks that have been
24 plumbed for IP traffic. \fBsnoop\fR uses the \fBpfmod\fR(7M) and
25 \fBbufmod\fR(7M) STREAMS modules to provide efficient capture of packets from
26 the network. Captured packets can be displayed as they are received or saved to
27 a file (which is \fIRFC 1761\fR-compliant) for later inspection.
28 .sp
29 .LP
30 \fBsnoop\fR can display packets in a single-line summary form or in verbose
31 multi-line forms. In summary form, with the exception of certain VLAN packets,
32 only the data pertaining to the highest level protocol is displayed. If a
33 packet has a VLAN header and its VLAN ID is non-zero, then \fBsnoop\fR will
34 show that the packet is VLAN tagged. For example, an \fBNFS\fR packet will have
35 only \fBNFS\fR information displayed. Except for VLAN information under the
36 condition just described, the underlying \fBRPC\fR, \fBUDP\fR, \fBIP\fR, and
37 Ethernet frame information is suppressed, but can be displayed if either of the
38 verbose options are chosen.
39 .sp
40 .LP
41 In the absence of a name service, such as LDAP or NIS, \fBsnoop\fR displays
42 host names as numeric IP addresses.
43 .sp
44 .LP
45 \fBsnoop\fR requires an interactive interface.
46 .SH OPTIONS
47 .sp
48 .ne 2
49 .na
50 \fB\fB-C\fR\fR
51 .ad
52 .sp .6
53 .RS 4n
54 List the code generated from the filter expression for either the kernel packet
55 filter, or \fBsnoop\fR's own filter.
56 .RE
58 .sp
59 .ne 2
60 .na
61 \fB\fB-D\fR\fR
62 .ad
63 .sp .6
64 .RS 4n
65 Display number of packets dropped during capture on the summary line.
66 .RE
68 .sp
69 .ne 2
70 .na
71 \fB\fB-N\fR\fR
72 .ad
73 .sp .6
74 .RS 4n
75 Create an \fBIP\fR address-to-name file from a capture file. This must be set
76 together with the \fB-i\fR option that names a capture file. The
77 address-to-name file has the same name as the capture file with \fB\&.names\fR
78 appended. This file records the \fBIP\fR address to hostname mapping at the
79 capture site and increases the portability of the capture file. Generate a
80 \fB\&.names\fR file if the capture file is to be analyzed elsewhere. Packets
81 are not displayed when this flag is used.
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fB-I\fR \fIinterface\fR\fR
88 .ad
89 .sp .6
90 .RS 4n
91 Capture IP packets from the network using the IP interface specified by
92 \fIinterface\fR, for example, \fBlo0\fR. The \fBifconfig\fR(1M) command can be
93 used to list available IP interfaces. The \fB-I\fR and \fB-d\fR options are
94 mutually exclusive.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fB-P\fR\fR
101 .ad
102 .sp .6
103 .RS 4n
104 Capture packets in non-promiscuous mode. Only broadcast, multicast, or packets
105 addressed to the host machine will be seen.
106 .RE
108 .sp
109 .ne 2
110 .na
111 \fB\fB-S\fR\fR
112 .ad
113 .sp .6
114 .RS 4n
115 Display size of the entire link layer frame in bytes on the summary line.
116 .RE
118 .sp
119 .ne 2
120 .na
121 \fB\fB-V\fR\fR
122 .ad
123 .sp .6
124 .RS 4n
125 Verbose summary mode. This is halfway between summary mode and verbose mode in
126 degree of verbosity. Instead of displaying just the summary line for the
127 highest level protocol in a packet, it displays a summary line for each
128 protocol layer in the packet. For instance, for an \fBNFS\fR packet it will
129 display a line each for the \fBETHER\fR, \fBIP\fR, \fBUDP\fR, \fBRPC\fR and
130 \fBNFS\fR layers. Verbose summary mode output may be easily piped through
131 \fBgrep\fR to extract packets of interest. For example, to view only \fBRPC\fR
132 summary lines, enter the following: \fBexample#\fR \fBsnoop -i rpc.cap -V |
133 grep RPC\fR
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fB-a\fR\fR
140 .ad
141 .sp .6
142 .RS 4n
143 Listen to packets on \fB/dev/audio\fR (warning: can be noisy).
144 .RE
146 .sp
147 .ne 2
148 .na
149 \fB\fB-c\fR \fImaxcount\fR\fR
150 .ad
151 .sp .6
152 .RS 4n
153 Quit after capturing \fImaxcount\fR packets. Otherwise keep capturing until
154 there is no disk space left or until interrupted with Control-C.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fB-d\fR \fIdatalink\fR\fR
161 .ad
162 .sp .6
163 .RS 4n
164 Capture link-layer packets from the network using the DLPI datalink specified
165 by \fIdatalink\fR, for example, \fBbge0\fR or \fBnet0\fR. The \fBdladm\fR(1M)
166 \fBshow-link\fR subcommand can be used to list available datalinks. The
167 \fB-d\fR and \fB-I\fR options are mutually exclusive.
168 .RE
170 .sp
171 .ne 2
172 .na
173 \fB\fB-i\fR \fIfilename\fR\fR
174 .ad
175 .sp .6
176 .RS 4n
177 Display packets previously captured in \fIfilename\fR. Without this option,
178 \fBsnoop\fR reads packets from the network interface. If a
179 \fIfilename\fR\fB\&.names\fR file is present, it is automatically loaded into
180 the \fBsnoop\fR \fBIP\fR address-to-name mapping table (See \fB-N\fR flag).
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fB-n\fR \fIfilename\fR\fR
187 .ad
188 .sp .6
189 .RS 4n
190 Use \fIfilename\fR as an \fBIP\fR address-to-name mapping table. This file must
191 have the same format as the \fB/etc/hosts\fR file (IP address followed by the
192 hostname).
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fB-o\fR \fIfilename\fR\fR
199 .ad
200 .sp .6
201 .RS 4n
202 Save captured packets in \fIfilename\fR as they are captured. (This
203 \fIfilename\fR is referred to as the "capture file".) The format of the capture
204 file is RFC 1761-compliant. During packet capture, a count of the number of
205 packets saved in the file is displayed. If you wish just to count packets
206 without saving to a file, name the file \fB/dev/null\fR.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fB-p\fR \fIfirst\fR [ , \fBlast\fR ]\fR
213 .ad
214 .sp .6
215 .RS 4n
216 Select one or more packets to be displayed from a capture file. The \fIfirst\fR
217 packet in the file is packet number 1.
218 .RE
220 .sp
221 .ne 2
222 .na
223 \fB\fB-q\fR\fR
224 .ad
225 .sp .6
226 .RS 4n
227 When capturing network packets into a file, do not display the packet count.
228 This can improve packet capturing performance.
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fB\fB-r\fR\fR
235 .ad
236 .sp .6
237 .RS 4n
238 Do not resolve the \fBIP\fR address to the symbolic name. This prevents
239 \fBsnoop\fR from generating network traffic while capturing and displaying
240 packets. However, if the \fB-n\fR option is used, and an address is found in
241 the mapping file, its corresponding name will be used.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fB-s\fR \fIsnaplen\fR\fR
248 .ad
249 .sp .6
250 .RS 4n
251 Truncate each packet after \fIsnaplen\fR bytes. Usually the whole packet is
252 captured. This option is useful if only certain packet header information is
253 required. The packet truncation is done within the kernel giving better
254 utilization of the streams packet buffer. This means less chance of dropped
255 packets due to buffer overflow during periods of high traffic. It also saves
256 disk space when capturing large traces to a capture file. To capture only
257 \fBIP\fR headers (no options) use a \fIsnaplen\fR of 34. For \fBUDP\fR use 42,
258 and for \fBTCP\fR use 54. You can capture \fBRPC\fR headers with a
259 \fIsnaplen\fR of 80 bytes. \fBNFS\fR headers can be captured in 120 bytes.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fB-t\fR [ \fBr\fR | \fBa\fR | \fBd\fR ]\fR
266 .ad
267 .sp .6
268 .RS 4n
269 Time-stamp presentation. Time-stamps are accurate to within 4 microseconds. The
270 default is for times to be presented in \fBd\fR (delta) format (the time since
271 receiving the previous packet). Option \fBa\fR (absolute) gives wall-clock
272 time. Option \fBr\fR (relative) gives time relative to the first packet
273 displayed. This can be used with the \fB-p\fR option to display time relative
274 to any selected packet.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fB-v\fR\fR
281 .ad
282 .sp .6
283 .RS 4n
284 Verbose mode. Print packet headers in lots of detail. This display consumes
285 many lines per packet and should be used only on selected packets.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fB\fR\fB-x\fR\fIoffset\fR [ , \fIlength\fR]\fR
292 .ad
293 .sp .6
294 .RS 4n
295 Display packet data in hexadecimal and \fBASCII\fR format. The \fIoffset\fR and
296 \fIlength\fR values select a portion of the packet to be displayed. To display
297 the whole packet, use an \fIoffset\fR of 0. If a \fIlength\fR value is not
298 provided, the rest of the packet is displayed.
299 .RE
301 .SH OPERANDS
302 .sp
303 .ne 2
304 .na
305 \fB\fIexpression\fR\fR
306 .ad
307 .sp .6
308 .RS 4n
309 Select packets either from the network or from a capture file. Only packets for
310 which the expression is true will be selected. If no expression is provided it
311 is assumed to be true.
312 .sp
313 Given a filter expression, \fBsnoop\fR generates code for either the kernel
314 packet filter or for its own internal filter. If capturing packets with the
315 network interface, code for the kernel packet filter is generated. This filter
316 is implemented as a streams module, upstream of the buffer module. The buffer
317 module accumulates packets until it becomes full and passes the packets on to
318 \fBsnoop\fR. The kernel packet filter is very efficient, since it rejects
319 unwanted packets in the kernel before they reach the packet buffer or
320 \fBsnoop\fR. The kernel packet filter has some limitations in its
321 implementation; it is possible to construct filter expressions that it cannot
322 handle. In this event, \fBsnoop\fR tries to split the filter and do as much
323 filtering in the kernel as possible. The remaining filtering is done by the
324 packet filter for \fBsnoop\fR. The \fB-C\fR flag can be used to view generated
325 code for either the packet filter for the kernel or the packet filter for
326 \fBsnoop\fR. If packets are read from a capture file using the \fB-i\fR option,
327 only the packet filter for \fBsnoop\fR is used.
328 .sp
329 A filter \fIexpression\fR consists of a series of one or more boolean
330 primitives that may be combined with boolean operators (\fBAND\fR, \fBOR\fR,
331 and \fBNOT\fR). Normal precedence rules for boolean operators apply. Order of
332 evaluation of these operators may be controlled with parentheses. Since
333 parentheses and other filter expression characters are known to the shell, it
334 is often necessary to enclose the filter expression in quotes. Refer to for
335 information about setting up more efficient filters.
336 .sp
337 The primitives are:
338 .sp
339 .ne 2
340 .na
341 \fB\fBhost\fR \fIhostname\fR\fR
342 .ad
343 .sp .6
344 .RS 4n
345 True if the source or destination address is that of \fBhostname\fR. The
346 \fIhostname\fR argument may be a literal address. The keyword \fBhost\fR may be
347 omitted if the name does not conflict with the name of another expression
348 primitive. For example, \fBpinky\fR selects packets transmitted to or received
349 from the host \fBpinky\fR, whereas \fBpinky and dinky\fR selects packets
350 exchanged between hosts \fBpinky AND dinky\fR.
351 .sp
352 The type of address used depends on the primitive which precedes the \fBhost\fR
353 primitive. The possible qualifiers are \fBinet\fR, \fBinet6\fR, \fBether\fR, or
354 none. These three primitives are discussed below. Having none of the primitives
355 present is equivalent to "inet host hostname or inet6 host hostname". In other
356 words, snoop tries to filter on all IP addresses associated with hostname.
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fIinet\fR or \fIinet6\fR\fR
363 .ad
364 .sp .6
365 .RS 4n
366 A qualifier that modifies the \fBhost\fR primitive that follows. If it is
367 \fIinet\fR, then \fBsnoop\fR tries to filter on all IPv4 addresses returned
368 from a name lookup. If it is \fIinet6\fR, \fBsnoop\fR tries to filter on all
369 IPv6 addresses returned from a name lookup.
370 .RE
372 .sp
373 .ne 2
374 .na
375 \fB\fIipaddr\fR, \fIatalkaddr\fR, or \fIetheraddr\fR\fR
376 .ad
377 .sp .6
378 .RS 4n
379 Literal addresses, \fBIP\fR dotted, AppleTalk dotted, and Ethernet colon are
380 recognized. For example,
381 .RS +4
382 .TP
383 .ie t \(bu
384 .el o
385 "\fB172.16.40.13\fR" matches all packets with that \fBIP\fR
386 .RE
387 .RS +4
388 .TP
389 .ie t \(bu
390 .el o
391 "\fB2::9255:a00:20ff:fe73:6e35\fR" matches all packets with that IPv6 address
392 as source or destination;
393 .RE
394 .RS +4
395 .TP
396 .ie t \(bu
397 .el o
398 "\fB65281.13\fR" matches all packets with that AppleTalk address;
399 .RE
400 .RS +4
401 .TP
402 .ie t \(bu
403 .el o
404 "\fB8:0:20:f:b1:51\fR" matches all packets with the Ethernet address as source
405 or destination.
406 .RE
407 An Ethernet address beginning with a letter is interpreted as a hostname. To
408 avoid this, prepend a zero when specifying the address. For example, if the
409 Ethernet address is \fBaa:0:45:23:52:44\fR, then specify it by add a leading
410 zero to make it \fB0aa:0:45:23:52:44\fR.
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fBfrom\fR or \fBsrc\fR\fR
417 .ad
418 .sp .6
419 .RS 4n
420 A qualifier that modifies the following \fBhost\fR, \fBnet\fR, \fIipaddr\fR,
421 \fIatalkaddr\fR, \fIetheraddr\fR, \fBport\fR or \fBrpc\fR primitive to match
422 just the source address, port, or \fBRPC\fR reply.
423 .RE
425 .sp
426 .ne 2
427 .na
428 \fB\fBto\fR or \fBdst\fR\fR
429 .ad
430 .sp .6
431 .RS 4n
432 A qualifier that modifies the following \fBhost\fR, \fBnet\fR, \fIipaddr\fR,
433 \fIatalkaddr\fR, \fIetheraddr\fR, \fBport\fR or \fBrpc\fR primitive to match
434 just the destination address, port, or \fBRPC\fR call.
435 .RE
437 .sp
438 .ne 2
439 .na
440 \fB\fBether\fR\fR
441 .ad
442 .sp .6
443 .RS 4n
444 A qualifier that modifies the following \fBhost\fR primitive to resolve a name
445 to an Ethernet address. Normally, \fBIP\fR address matching is performed. This
446 option is not supported on media such as IPoIB (IP over InfiniBand).
447 .RE
449 .sp
450 .ne 2
451 .na
452 \fB\fBethertype\fR \fInumber\fR\fR
453 .ad
454 .sp .6
455 .RS 4n
456 True if the Ethernet type field has value \fInumber\fR. If \fInumber\fR is not
457 0x8100 (VLAN) and the packet is VLAN tagged, then the expression will match the
458 encapsulated Ethernet type.
459 .RE
461 .sp
462 .ne 2
463 .na
464 \fB\fBip\fR, \fBip6\fR, \fBarp\fR, \fBrarp\fR, \fBpppoed\fR, \fBpppoes\fR\fR
465 .ad
466 .sp .6
467 .RS 4n
468 True if the packet is of the appropriate ethertype.
469 .RE
471 .sp
472 .ne 2
473 .na
474 \fB\fBvlan\fR\fR
475 .ad
476 .sp .6
477 .RS 4n
478 True if the packet has \fBethertype\fR VLAN and the VLAN ID is not zero.
479 .RE
481 .sp
482 .ne 2
483 .na
484 \fB\fBvlan-id\fR \fIid\fR\fR
485 .ad
486 .sp .6
487 .RS 4n
488 True for packets of ethertype VLAN with the id \fIid\fR.
489 .RE
491 .sp
492 .ne 2
493 .na
494 \fB\fBpppoe\fR\fR
495 .ad
496 .sp .6
497 .RS 4n
498 True if the ethertype of the packet is either \fBpppoed\fR or \fBpppoes\fR.
499 .RE
501 .sp
502 .ne 2
503 .na
504 \fB\fBbroadcast\fR\fR
505 .ad
506 .sp .6
507 .RS 4n
508 True if the packet is a broadcast packet. Equivalent to \fBether[2:4] =
509 0xffffffff\fR for Ethernet. This option is not supported on media such as IPoIB
510 (IP over InfiniBand).
511 .RE
513 .sp
514 .ne 2
515 .na
516 \fB\fBmulticast\fR\fR
517 .ad
518 .sp .6
519 .RS 4n
520 True if the packet is a multicast packet. Equivalent to "\fBether[0] & 1 =
521 1\fR" on Ethernet. This option is not supported on media such as IPoIB (IP over
522 InfiniBand).
523 .RE
525 .sp
526 .ne 2
527 .na
528 \fB\fBbootp\fR, \fBdhcp\fR\fR
529 .ad
530 .sp .6
531 .RS 4n
532 True if the packet is an unfragmented IPv4 UDP packet with either a source port
533 of \fBBOOTPS (67)\fR and a destination port of \fBBOOTPC (68)\fR, or a source
534 port of \fBBOOTPC (68)\fR and a destination of \fBBOOTPS (67)\fR.
535 .RE
537 .sp
538 .ne 2
539 .na
540 \fB\fBdhcp6\fR\fR
541 .ad
542 .sp .6
543 .RS 4n
544 True if the packet is an unfragmented IPv6 UDP packet with either a source port
545 of \fBDHCPV6-SERVER\fR (547) and a destination port of \fBDHCPV6-CLIENT\fR
546 (546), or a source port of \fBDHCPV6-CLIENT\fR (546) and a destination of
547 \fBDHCPV6-SERVER\fR (547).
548 .RE
550 .sp
551 .ne 2
552 .na
553 \fB\fBapple\fR\fR
554 .ad
555 .sp .6
556 .RS 4n
557 True if the packet is an Apple Ethertalk packet. Equivalent to "\fBethertype
558 0x809b or ethertype 0x80f3\fR".
559 .RE
561 .sp
562 .ne 2
563 .na
564 \fB\fBdecnet\fR\fR
565 .ad
566 .sp .6
567 .RS 4n
568 True if the packet is a \fBDECNET\fR packet.
569 .RE
571 .sp
572 .ne 2
573 .na
574 \fB\fBgreater\fR \fIlength\fR\fR
575 .ad
576 .sp .6
577 .RS 4n
578 True if the packet is longer than \fIlength\fR.
579 .RE
581 .sp
582 .ne 2
583 .na
584 \fB\fBless\fR \fIlength\fR\fR
585 .ad
586 .sp .6
587 .RS 4n
588 True if the packet is shorter than \fIlength\fR.
589 .RE
591 .sp
592 .ne 2
593 .na
594 \fB\fBudp\fR, \fBtcp\fR, \fBicmp\fR, \fBicmp6\fR, \fBah\fR, \fBesp\fR\fR
595 .ad
596 .sp .6
597 .RS 4n
598 True if the \fBIP\fR or IPv6 protocol is of the appropriate type.
599 .RE
601 .sp
602 .ne 2
603 .na
604 \fB\fBnet\fR \fInet\fR\fR
605 .ad
606 .sp .6
607 .RS 4n
608 True if either the \fBIP\fR source or destination address has a network number
609 of \fInet\fR. The \fBfrom\fR or \fBto\fR qualifier may be used to select
610 packets for which the network number occurs only in the source or destination
611 address.
612 .RE
614 .sp
615 .ne 2
616 .na
617 \fB\fBport\fR \fIport\fR\fR
618 .ad
619 .sp .6
620 .RS 4n
621 True if either the source or destination port is \fIport\fR. The \fIport\fR may
622 be either a port number or name from \fB/etc/services\fR. The \fBtcp\fR or
623 \fBudp\fR primitives may be used to select \fBTCP\fR or \fBUDP\fR ports only.
624 The \fBfrom\fR or \fBto\fR qualifier may be used to select packets for which
625 the \fIport\fR occurs only as the source or destination.
626 .RE
628 .sp
629 .ne 2
630 .na
631 \fB\fBrpc\fR \fIprog\fR [ , \fIvers\fR [ , \fBproc\fR ] ]\fR
632 .ad
633 .sp .6
634 .RS 4n
635 True if the packet is an \fBRPC\fR call or reply packet for the protocol
636 identified by \fIprog\fR. The \fIprog\fR may be either the name of an \fBRPC\fR
637 protocol from \fB/etc/rpc\fR or a program number. The \fIvers\fR and \fBproc\fR
638 may be used to further qualify the program \fIversion\fR and \fIprocedure\fR
639 number, for example, \fBrpc nfs,2,0\fR selects all calls and replies for the
640 \fBNFS\fR null procedure. The \fBto\fR or \fBfrom\fR qualifier may be used to
641 select either call or reply packets only.
642 .RE
644 .sp
645 .ne 2
646 .na
647 \fB\fBzone\fR \fIzoneid\fR\fR
648 .ad
649 .sp .6
650 .RS 4n
651 True if \fIzoneid\fR matches either the source or destination \fIzoneid\fR of a
652 packet received on an \fBipnet\fR device.
653 .RE
655 .sp
656 .ne 2
657 .na
658 \fB\fBldap\fR\fR
659 .ad
660 .sp .6
661 .RS 4n
662 True if the packet is an \fBLDAP\fR packet on port 389.
663 .RE
665 .sp
666 .ne 2
667 .na
668 \fB\fBgateway\fR \fIhost\fR\fR
669 .ad
670 .sp .6
671 .RS 4n
672 True if the packet used \fIhost\fR as a gateway, that is, the Ethernet source
673 or destination address was for \fIhost\fR but not the \fBIP\fR address.
674 Equivalent to "\fBether host\fR \fIhost\fR and not host \fIhost\fR".
675 .RE
677 .sp
678 .ne 2
679 .na
680 \fB\fBnofrag\fR\fR
681 .ad
682 .sp .6
683 .RS 4n
684 True if the packet is unfragmented or is the first in a series of \fBIP\fR
685 fragments. Equivalent to \fBip[6:2] & 0x1fff = 0\fR.
686 .RE
688 .sp
689 .ne 2
690 .na
691 \fB\fIexpr\fR \fIrelop\fR \fIexpr\fR\fR
692 .ad
693 .sp .6
694 .RS 4n
695 True if the relation holds, where \fIrelop\fR is one of \fB>\fR, \fB<\fR,
696 \fB>=\fR, \fB<=\fR, \fB=\fR, \fB!=\fR, and \fBexpr\fR is an arithmetic
697 expression composed of numbers, packet field selectors, the \fBlength\fR
698 primitive, and arithmetic operators \fB+\fR, \fB\(mi\fR, \fB*\fR, \fB&\fR,
699 \fB|\fR, \fB^\fR, and \fB%\fR. The arithmetic operators within \fBexpr\fR are
700 evaluated before the relational operator and normal precedence rules apply
701 between the arithmetic operators, such as multiplication before addition.
702 Parentheses may be used to control the order of evaluation. To use the value of
703 a field in the packet use the following syntax:
704 .sp
705 .in +2
706 .nf
707 \fIbase\fR[\fBexpr\fR [\fB:\fR \fBsize\fR ] ]
708 .fi
709 .in -2
710 .sp
712 where \fBexpr\fR evaluates the value of an offset into the packet from a
713 \fIbase\fR offset which may be \fBether\fR, \fBip\fR, \fBip6\fR, \fBudp\fR,
714 \fBtcp\fR, or \fBicmp\fR. The \fBsize\fR value specifies the size of the field.
715 If not given, 1 is assumed. Other legal values are 2 and 4. For example,
716 .sp
717 .in +2
718 .nf
719 ether[0] & 1 = 1
720 .fi
721 .in -2
723 is equivalent to \fBmulticast\fR
724 .sp
725 .in +2
726 .nf
727 ether[2:4] = 0xffffffff
728 .fi
729 .in -2
731 is equivalent to \fBbroadcast\fR.
732 .sp
733 .in +2
734 .nf
735 ip[ip[0] & 0xf * 4 : 2] = 2049
736 .fi
737 .in -2
739 is equivalent to \fBudp[0:2] = 2049\fR
740 .sp
741 .in +2
742 .nf
743 ip[0] & 0xf > 5
744 .fi
745 .in -2
747 selects \fBIP\fR packets with options.
748 .sp
749 .in +2
750 .nf
751 ip[6:2] & 0x1fff = 0
752 .fi
753 .in -2
755 eliminates \fBIP\fR fragments.
756 .sp
757 .in +2
758 .nf
759 udp and ip[6:2]&0x1fff = 0 and udp[6:2] != 0
760 .fi
761 .in -2
763 finds all packets with \fBUDP\fR checksums.
764 .sp
765 The \fBlength\fR primitive may be used to obtain the length of the packet. For
766 instance "\fBlength > 60\fR" is equivalent to "\fBgreater 60\fR", and
767 "\fBether[length \(mi 1]\fR" obtains the value of the last byte in a packet.
768 .RE
770 .sp
771 .ne 2
772 .na
773 \fB\fBand\fR\fR
774 .ad
775 .sp .6
776 .RS 4n
777 Perform a logical \fBAND\fR operation between two boolean values. The \fBAND\fR
778 operation is implied by the juxtaposition of two boolean expressions, for
779 example "\fBdinky pinky\fR" is the same as "\fBdinky AND pinky\fR".
780 .RE
782 .sp
783 .ne 2
784 .na
785 \fB\fBor\fR or \fB,\fR\fR
786 .ad
787 .sp .6
788 .RS 4n
789 Perform a logical \fBOR\fR operation between two boolean values. A comma may be
790 used instead, for example, "\fBdinky,pinky\fR" is the same as "\fBdinky OR
791 pinky\fR".
792 .RE
794 .sp
795 .ne 2
796 .na
797 \fB\fBnot\fR or \fB!\fR\fR
798 .ad
799 .sp .6
800 .RS 4n
801 Perform a logical \fBNOT\fR operation on the following boolean value. This
802 operator is evaluated before \fBAND\fR or OR.
803 .RE
805 .sp
806 .ne 2
807 .na
808 \fB\fBslp\fR\fR
809 .ad
810 .sp .6
811 .RS 4n
812 True if the packet is an \fBSLP\fR packet.
813 .RE
815 .sp
816 .ne 2
817 .na
818 \fB\fBsctp\fR\fR
819 .ad
820 .sp .6
821 .RS 4n
822 True if the packet is an \fBSCTP\fR packet.
823 .RE
825 .sp
826 .ne 2
827 .na
828 \fB\fBospf\fR\fR
829 .ad
830 .sp .6
831 .RS 4n
832 True if the packet is an \fBOSPF\fR packet.
833 .RE
835 .RE
837 .SH EXAMPLES
838 .LP
839 \fBExample 1 \fRUsing the \fBsnoop\fR Command
840 .sp
841 .LP
842 Capture all packets and display them as they are received:
844 .sp
845 .in +2
846 .nf
847 example# \fBsnoop\fR
848 .fi
849 .in -2
850 .sp
852 .sp
853 .LP
854 Capture packets with host \fBfunky\fR as either the source or destination and
855 display them as they are received:
857 .sp
858 .in +2
859 .nf
860 example# \fBsnoop funky\fR
861 .fi
862 .in -2
863 .sp
865 .sp
866 .LP
867 Capture packets between \fBfunky\fR and \fBpinky\fR and save them to a file.
868 Then inspect the packets using times (in seconds) relative to the first
869 captured packet:
871 .sp
872 .in +2
873 .nf
874 example# \fBsnoop -o cap funky pinky\fR
875 example# \fBsnoop -i cap -t r | more\fR
876 .fi
877 .in -2
878 .sp
880 .sp
881 .LP
882 To look at selected packets in another capture file:
884 .sp
885 .in +2
886 .nf
887 example# \fBsnoop -i pkts -p 99,108\fR
888 99 0.0027 boutique -> sunroof NFS C GETATTR FH=8E6
889 100 0.0046 sunroof -> boutique NFS R GETATTR OK
890 101 0.0080 boutique -> sunroof NFS C RENAME FH=8E6C MTra00192 to .nfs08
891 102 0.0102 marmot -> viper NFS C LOOKUP FH=561E screen.r.13.i386
892 103 0.0072 viper -> marmot NFS R LOOKUP No such file or directory
893 104 0.0085 bugbomb -> sunroof RLOGIN C PORT=1023 h
894 105 0.0005 kandinsky -> sparky RSTAT C Get Statistics
895 106 0.0004 beeblebrox -> sunroof NFS C GETATTR FH=0307
896 107 0.0021 sparky -> kandinsky RSTAT R
897 108 0.0073 office -> jeremiah NFS C READ FH=2584 at 40960 for 8192
898 .fi
899 .in -2
900 .sp
902 .sp
903 .LP
904 To look at packet 101 in more detail:
906 .sp
907 .in +2
908 .nf
909 example# \fBsnoop -i pkts -v -p101\fR
910 ETHER: ----- Ether Header -----
911 ETHER:
912 ETHER: Packet 101 arrived at 16:09:53.59
913 ETHER: Packet size = 210 bytes
914 ETHER: Destination = 8:0:20:1:3d:94, Sun
915 ETHER: Source = 8:0:69:1:5f:e, Silicon Graphics
916 ETHER: Ethertype = 0800 (IP)
917 ETHER:
918 IP: ----- IP Header -----
919 IP:
920 IP: Version = 4, header length = 20 bytes
921 IP: Type of service = 00
922 IP: ..0. .... = routine
923 IP: ...0 .... = normal delay
924 IP: .... 0... = normal throughput
925 IP: .... .0.. = normal reliability
926 IP: Total length = 196 bytes
927 IP: Identification 19846
928 IP: Flags = 0X
929 IP: .0.. .... = may fragment
930 IP: ..0. .... = more fragments
931 IP: Fragment offset = 0 bytes
932 IP: Time to live = 255 seconds/hops
933 IP: Protocol = 17 (UDP)
934 IP: Header checksum = 18DC
935 IP: Source address = 172.16.40.222, boutique
936 IP: Destination address = 172.16.40.200, sunroof
937 IP:
938 UDP: ----- UDP Header -----
939 UDP:
940 UDP: Source port = 1023
941 UDP: Destination port = 2049 (Sun RPC)
942 UDP: Length = 176
943 UDP: Checksum = 0
944 UDP:
945 RPC: ----- SUN RPC Header -----
946 RPC:
947 RPC: Transaction id = 665905
948 RPC: Type = 0 (Call)
949 RPC: RPC version = 2
950 RPC: Program = 100003 (NFS), version = 2, procedure = 1
951 RPC: Credentials: Flavor = 1 (Unix), len = 32 bytes
952 RPC: Time = 06-Mar-90 07:26:58
953 RPC: Hostname = boutique
954 RPC: Uid = 0, Gid = 1
955 RPC: Groups = 1
956 RPC: Verifier : Flavor = 0 (None), len = 0 bytes
957 RPC:
958 NFS: ----- SUN NFS -----
959 NFS:
960 NFS: Proc = 11 (Rename)
961 NFS: File handle = 000016430000000100080000305A1C47
962 NFS: 597A0000000800002046314AFC450000
963 NFS: File name = MTra00192
964 NFS: File handle = 000016430000000100080000305A1C47
965 NFS: 597A0000000800002046314AFC450000
966 NFS: File name = .nfs08
967 NFS:
968 .fi
969 .in -2
970 .sp
972 .sp
973 .LP
974 To view just the \fBNFS\fR packets between \fBsunroof\fR and \fBboutique\fR:
976 .sp
977 .in +2
978 .nf
979 example# \fBsnoop -i pkts rpc nfs and sunroof and boutique\fR
980 1 0.0000 boutique -> sunroof NFS C GETATTR FH=8E6C
981 2 0.0046 sunroof -> boutique NFS R GETATTR OK
982 3 0.0080 boutique -> sunroof NFS C RENAME FH=8E6C MTra00192 to .nfs08
983 .fi
984 .in -2
985 .sp
987 .sp
988 .LP
989 To save these packets to a new capture file:
991 .sp
992 .in +2
993 .nf
994 example# \fBsnoop -i pkts -o pkts.nfs rpc nfs sunroof boutique\fR
995 .fi
996 .in -2
997 .sp
999 .sp
1000 .LP
1001 To view encapsulated packets, there will be an indicator of encapsulation:
1003 .sp
1004 .in +2
1005 .nf
1006 example# \fBsnoop ip-in-ip\fR
1007 sunroof -> boutique ICMP Echo request (1 encap)
1008 .fi
1009 .in -2
1010 .sp
1012 .sp
1013 .LP
1014 If -V is used on an encapsulated packet:
1016 .sp
1017 .in +2
1018 .nf
1019 example# \fBsnoop -V ip-in-ip\fR
1020 sunroof -> boutique ETHER Type=0800 (IP), size = 118 bytes
1021 sunroof -> boutique IP D=172.16.40.222 S=172.16.40.200 LEN=104, ID=27497
1022 sunroof -> boutique IP D=10.1.1.2 S=10.1.1.1 LEN=84, ID=27497
1023 sunroof -> boutique ICMP Echo request
1024 .fi
1025 .in -2
1026 .sp
1028 .LP
1029 \fBExample 2 \fRSetting Up A More Efficient Filter
1030 .sp
1031 .LP
1032 To set up a more efficient filter, the following filters should be used toward
1033 the end of the expression, so that the first part of the expression can be set
1034 up in the kernel: \fBgreater\fR, \fBless\fR, \fBport\fR, \fBrpc\fR,
1035 \fBnofrag\fR, and \fBrelop\fR. The presence of \fBOR\fR makes it difficult to
1036 split the filtering when using these primitives that cannot be set in the
1037 kernel. Instead, use parentheses to enforce the primitives that should be
1038 \fBOR\fR'd.
1040 .sp
1041 .LP
1042 To capture packets between \fBfunky\fR and \fBpinky\fR of type \fBtcp\fR or
1043 \fBudp\fR on \fBport\fR 80:
1045 .sp
1046 .in +2
1047 .nf
1048 example# \fBsnoop funky and pinky and port 80 and tcp or udp\fR
1049 .fi
1050 .in -2
1051 .sp
1053 .sp
1054 .LP
1055 Since the primitive \fBport\fR cannot be handled by the kernel filter, and
1056 there is also an \fBOR\fR in the expression, a more efficient way to filter is
1057 to move the \fBOR\fR to the end of the expression and to use parentheses to
1058 enforce the \fBOR\fR between \fBtcp\fR and \fBudp\fR:
1060 .sp
1061 .in +2
1062 .nf
1063 example# \fBsnoop funky and pinky and (tcp or udp) and port 80\fR
1064 .fi
1065 .in -2
1066 .sp
1068 .SH EXIT STATUS
1069 .sp
1070 .ne 2
1071 .na
1072 \fB\fB0\fR\fR
1073 .ad
1074 .RS 5n
1075 Successful completion.
1076 .RE
1078 .sp
1079 .ne 2
1080 .na
1081 \fB\fB1\fR\fR
1082 .ad
1083 .RS 5n
1084 An error occurred.
1085 .RE
1087 .SH FILES
1088 .sp
1089 .ne 2
1090 .na
1091 \fB\fB/dev/audio\fR\fR
1092 .ad
1093 .RS 17n
1094 Symbolic link to the system's primary audio device.
1095 .RE
1097 .sp
1098 .ne 2
1099 .na
1100 \fB\fB/dev/null\fR\fR
1101 .ad
1102 .RS 17n
1103 The null file.
1104 .RE
1106 .sp
1107 .ne 2
1108 .na
1109 \fB\fB/etc/hosts\fR\fR
1110 .ad
1111 .RS 17n
1112 Host name database.
1113 .RE
1115 .sp
1116 .ne 2
1117 .na
1118 \fB\fB/etc/rpc\fR\fR
1119 .ad
1120 .RS 17n
1121 RPC program number data base.
1122 .RE
1124 .sp
1125 .ne 2
1126 .na
1127 \fB\fB/etc/services\fR\fR
1128 .ad
1129 .RS 17n
1130 Internet services and aliases.
1131 .RE
1133 .SH SEE ALSO
1134 .sp
1135 .LP
1136 \fBdladm\fR(1M), \fBifconfig\fR(1M), \fBnetstat\fR(1M), \fBhosts\fR(4),
1137 \fBrpc\fR(4), \fBservices\fR(4), \fBattributes\fR(5), \fBaudio\fR(7I),
1138 \fBipnet\fR(7D), \fBbufmod\fR(7M), \fBdlpi\fR(7P), \fBpfmod\fR(7M)
1139 .sp
1140 .LP
1141 Callaghan, B. and Gilligan, R. \fIRFC 1761, Snoop Version 2 Packet Capture File
1142 Format\fR. Network Working Group. February 1995.
1143 .SH WARNINGS
1144 .sp
1145 .LP
1146 The processing overhead is much higher for real-time packet interpretation.
1147 Consequently, the packet drop count may be higher. For more reliable capture,
1148 output raw packets to a file using the \fB-o\fR option and analyze the packets
1149 offline.
1150 .sp
1151 .LP
1152 Unfiltered packet capture imposes a heavy processing load on the host computer,
1153 particularly if the captured packets are interpreted real-time. This processing
1154 load further increases if verbose options are used. Since heavy use of
1155 \fBsnoop\fR may deny computing resources to other processes, it should not be
1156 used on production servers. Heavy use of \fBsnoop\fR should be restricted to a
1157 dedicated computer.
1158 .sp
1159 .LP
1160 \fBsnoop\fR does not reassemble \fBIP\fR fragments. Interpretation of higher
1161 level protocol halts at the end of the first \fBIP\fR fragment.
1162 .sp
1163 .LP
1164 \fBsnoop\fR may generate extra packets as a side-effect of its use. For example
1165 it may use a network name service (NIS or NIS+) to convert \fBIP\fR addresses
1166 to host names for display. Capturing into a file for later display can be used
1167 to postpone the address-to-name mapping until after the capture session is
1168 complete. Capturing into an NFS-mounted file may also generate extra packets.
1169 .sp
1170 .LP
1171 Setting the \fBsnaplen\fR (\fB-s\fR option) to small values may remove header
1172 information that is needed to interpret higher level protocols. The exact
1173 cutoff value depends on the network and protocols being used. For \fBNFS\fR
1174 Version 2 traffic using \fBUDP\fR on 10 Mb/s Ethernet, do not set \fBsnaplen\fR
1175 less than 150 bytes. For \fBNFS\fR Version 3 traffic using \fBTCP\fR on 100
1176 Mb/s Ethernet, \fBsnaplen\fR should be 250 bytes or more.
1177 .sp
1178 .LP
1179 \fBsnoop\fR requires information from an \fBRPC\fR request to fully interpret
1180 an \fBRPC\fR reply. If an \fBRPC\fR reply in a capture file or packet range
1181 does not have a request preceding it, then only the \fBRPC\fR reply header will
1182 be displayed.