NETSNOOP(1M)NETSNOOP(1M)NAMEnetsnoop - capture and decode network traffic
SYNOPSIS
/usr/sbin/netsnoop [-L protocols] [-b buffer] [-c count] [-d] [-e flags]
[-h hexprotos] [-i interface] [-l length] [-n nullprotos] [-o tracefile]
[-p protopts] [-q limit] [-t interval] [-rsvxy] [filter ...]
DESCRIPTION
Netsnoop captures packets which match an optional filter from a network
interface or saved tracefile. If filter is omitted and no -e option is
given, it captures packets promiscuously. For each packet, netsnoop
prints decoded frames of protocol data on standard output. It stores
captured packets in a buffer before decoding them; the default buffer
size is one. After decoding buffered packets, netsnoop resumes
capturing. Only the superuser can run netsnoop on a local network
interface. Users accepted by the snoopd(1M) authorization file on a
NetVisualyzer station can netsnoop from interfaces on that host.
Options
-L protocols List information on standard output about the symbols and
options defined by protocols, a comma-separated list of
protocol names. List information defined by all
protocols if protocols is all. If protocols or a part of
it has the form protocol.name, list information about
name only. -L causes netsnoop to ignore other options
and to exit after listing protocol information.
-b buffer Set the capture buffer size to buffer packets.
-c count Stop capturing after receiving count packets that match
filter. All count packets are buffered before they are
decoded; that is, -c count implies -b count.
-d Dump entire packets in hexadecimal rather than decoding
them symbolically. This option overrides the partial hex
dump options -h and -x.
-e flags Capture packets received with the data link errors
specified by flags, a comma-separated list of flag names.
The following flags are supported: any, frame, checksum,
toobig, toosmall, nobufs, overflow, and memory. See
snoop(7P) for more about netsnoop error flags. If the
filter argument is omitted, netsnoop captures only
packets received non-promiscuously with the specified
errors. Otherwise it captures both packets matching
filter and packets received with errors.
-h hexprotos Dump the frames for the protocols named in the comma-
separated hexprotos list in hexadecimal rather than
decoding them symbolically.
Page 1
NETSNOOP(1M)NETSNOOP(1M)-i interface Snoop on the network associated with interface. By
default, netsnoop captures packets from a host's primary
interface. Interface may name a network interface, a
host that addresses a configured interface, an interface
on a host (host:ifname) running snoopd, or a tracefile
created by the -o option. Invoke netstat(1M) with the -i
option to list configured interfaces and their hostnames.
-l length Set the length in bytes of packet data to capture. By
default, netsnoop captures all bytes of packet data.
-n nullprotos Do not decode or dump frames for the protocols named in
the comma-separated nullprotos list.
-o tracefile Output undecoded packets to tracefile. By deferring
packet decoding until a subsequent netsnoop invocation,
this option improves capture effectiveness. It typically
produces a smaller tracefile than would result from
redirecting decoded output.
-p protopts Set protocol options. Each option in the comma-separated
protopts list has one of these forms:
protocol.option
protocol.nooption
protocol.option=value
Use netsnoop-L protocol to list a protocol's options.
-q limit Reserve limit bytes for packet buffering in netsnoop's
kernel input queue. The default reservation is 60000
bytes.
-r Decode received sequence numbers rather than numbers
rewritten to count only matches against filter and
reception gaps.
-s After decoding, print statistics telling how many packets
were received by the network interface, and how many were
subsequently dropped due to kernel resource limits.
-t interval Capture for interval seconds. This option may be used
with -c to capture at most count packets in a given
interval.
-v Verbose decoding: decode more packet fields. This option
accumulates, so -vv causes netsnoop to show a very
verbose representation of protocol data.
-x Dump packet data not interpreted by protocol decoders in
hexadecimal.
Page 2
NETSNOOP(1M)NETSNOOP(1M)-y Consult the NIS name service when translating numbers to
names. By default, netsnoop uses local databases such as
/etc/hosts and /etc/services.
Filter Syntax
Netsnoop concatenates all filter arguments after the last option and
interprets the resulting string as an expression of operands joined by
operators. Operands are sub-expressions, path expressions, C integer
constants, or protocol-specific strings. All C operators except the
assignment operators and ?: are supported. The keywords and and or may
be used in place of && and ||, respectively. A single = may be used in
place of ==. The keyword not may be used in place of !. Operators that
are shell metawords must be quoted if netsnoop is invoked from a shell.
The subtraction operator - must be preceded by white space; otherwise it
is taken to be part of a protocol-specific string (an IP hostname, for
example).
A path expression is a period-separated sequence of components, of which
all but the last must be well-formed C identifiers. Each identifier
except the last must name a protocol encapsulated by the preceding
component's protocol, or a structured field in the last protocol. The
first identifier in a path names a field in the network interface's data
link protocol, or a network protocol encapsulated by the data link
protocol. Supported data link protocols include 10 Mb/s Ethernet, 100
Mb/s FDDI, Serial Line IP, and the loopback pseudo-protocol.
If the last identifier in a path expression names a protocol, then the
expression evaluates to 1 given a packet containing the listed protocols'
frames, nested in the expressed order; otherwise it evaluates to 0. If
the last identifier names a protocol field of structure or array type,
then the expression evaluates to 1 given a packet containing such a
field, and to 0 otherwise. If the last identifier names a protocol field
of scalar type, then the expression evaluates to the field's contents in
host order, given a packet that contains the field and that matches the
path preceding the field. If the last identifier names a protocol macro,
netsnoop parses the macro's definition in the preceding protocol's
context. Otherwise the last component in a path must be a protocol-
specific string, for example, the name of a well-known port.
Netsnoop decodes a packet only if filter evaluates to a non-zero value.
Error Correction
A filter may lack = (==) and and (&&) operators in many cases.
Netsnoop's filter parser will correct such errors by inserting the
appropriate operator, based on the type of the operand to the left of the
insertion point. For example, the filter
ip.dst fergie udp.dport 1023
will be corrected as follows. First, the parser inserts == after ip.dst,
because the latter is not a comparison:
Page 3
NETSNOOP(1M)NETSNOOP(1M)
ip.dst == fergie udp.dport 1023
Then, because no operator was found after the comparison ip.dst ==
fergie, the parser inserts &&:
ip.dst == fergie && udp.dport 1023
Finally, == is inserted after udp.dport, for the same reason that == was
inserted after ip.dst, above:
ip.dst == fergie && udp.dport == 1023
Netsnoop prints the corrected filter enclosed by brackets ([]) before it
starts capturing, so that the user can verify the correction.
Protocol Strings
Each protocol name in a path opens a scope containing resolved strings,
such as hostnames and addresses. For example, the Internet Protocol (IP)
resolves ip.broadcast to the IP broadcast address configured for the
network interface being snooped, ip.netmask to the configured IP netmask,
and 192.26.75.12 to a four-byte IP address in host order.
If a string occurs in an expression without a qualifying protocol path,
netsnoop tries to resolve it in the scope of the last protocol to its
left in the expression's parse tree. If that fails, it tries the data
link protocol's scope. Thus ip.dst=broadcast matches packets destined
for the local network's IP broadcast address, while broadcast=ip.dst
applied to an Ethernet interface cannot be parsed, because broadcast is
unresolved in Ethernet's scope (but ip.broadcast=ip.dst parses).
Macros
Protocols define macros in their own scopes to provide manifest names for
magic numbers and to provide shorthand for common lengthy expressions.
For example, the Ethernet protocol defines BROADCAST as the Ethernet
broadcast address, ff:ff:ff:ff:ff:ff. Protocols also define macros in
encapsulating protocol scopes to provide nicknames for long protocol path
expressions. For example, IP defines nfs as a nickname for
ip.udp.sunrpc.nfs in all data link protocols that contain ip. Macros may
have arguments, which follow the macro name either separated by white
space, or in a parenthesized, comma-separated list containing arbitrary
white space.
To define a macro in the subject interface's data link protocol, use
define(name, def). Calls to define may be preceded by a protocol path,
to define macros in higher-level protocols. Strings of the form $N
within def represent formal arguments to name. Each such formal is
replaced by the Nth actual argument supplied when name is called. The
number of formal and actual arguments must agree. Calls to define expand
to 1, so the , (comma) or && (and) operator must be used to join
Page 4
NETSNOOP(1M)NETSNOOP(1M)
definitions with expressions in a complex filter argument.
Output Format
Each decoded packet begins with a header telling its sequence number,
length in bytes, and reception time. The sequence number starts with
zero and counts only packets that match filter and packets dropped by the
kernel, which are assumed to match (use the -r option to decode
reception, rather than matched, sequence numbers). The reception time is
displayed in hours, minutes, seconds, and microseconds. For packets
received with errors, netsnoop prints an exclamation point after the
sequence number and prints error flag mnemonics after the reception time.
After the header come lines containing decoded protocol data. Data are
grouped into frames labeled by protocol names. Each frame consists of
field names and field contents. Field names are as in filter
expressions. By default, netsnoop decodes only interesting fields within
a frame. The -v option increases the level of decoding detail. With the
-x option, any data not interpreted by protocol decoders is dumped in
lines of hexadecimal (with ASCII), labeled by byte offset from the
beginning of the packet. For example, below is the output of netsnoop-vxc 1 tcp:
0000: len 102 time 11:40:31.925
ether: src 8:0:69:2:c:a7/SGI dst 8:0:69:2:31:30/SGI
ip: len 44 id 6393 off 0
src twilight.wpd.sgi.com dst england.wpd.sgi.com
tcp: sport 1023 dport 1021
seq 627,392,000 ack 0 flags SYN
win 16,384 urp 0
maxseg 1460
00058: 00 00 00 00 00 06 ......
00064: 00 14 7f 00 00 01 7f 00 00 01 00 6f 13 49 00 00 ...........o.I..
00080: 00 00 00 00 00 00 50 00 00 00 00 00 00 00 00 00 ......P.........
00096: 00 00 ff eb ....
Environment
By default, netsnoop maps names to numbers using local database files
such as /etc/hosts. The ip.hostresorder protocol option governs IP
hostname/address resolution. See sethostresorder(3N) and resolver(4) for
the format of this option's value. Netsnoop caches name/number
associations in protocol-specific files in /tmp, so that subsequent
invocations can more quickly map numbers that occur frequently in network
traffic. Cache entries have a cache-specific ``time-to-live'' - older
cache files are unlinked at startup, and reconstituted to contain new-
found associations upon termination.
When netsnoop is started, it tries to read a file named .netsnooprc in
the user's home directory. A valid .netsnooprc file consists of blank
lines, comment lines beginning with #, macro definitions, default command
options, and protocol option settings. Macro definition have the form
Page 5
NETSNOOP(1M)NETSNOOP(1M)
define ip.udst ip.dst == $1 && udp.dport == $2
Default options may be set as follows:
option -x -n ether
Protocol options are set as with the -p option (white space may be used
as well as commas to separate options):
set ip.noetherupdate arpip.noetherupdate
Netsnoop's command line overrides .netsnooprc.
EXAMPLES
To capture all packets received without errors and decode every byte in
each packet, issue:
netsnoop-vvvx
To capture rlogin(1) traffic between jake and elwood, issue:
netsnoop ip.between jake elwood and tcp.port login
The following invocation captures all packets, good or bad:
netsnoop-e any 1
A constant non-zero filter expression must be used with -e in order to
capture all packets. Without the 1, only bad packets destined for the
snooping host would be captured.
To capture 10 UDP broadcast packets from host jake, issue:
netsnoop-c 10 udp and ip.src=jake and ip.dst=broadcast
To capture all IPv6 packets sent by host rosewood-v6, issue:
netsnoop ipv6.src==rosewood-v6
The following invocation captures NFS traffic from elwood to jake, and
makes use of error correction:
netsnoop nfs ip.src elwood ip.dst jake
[nfs && ip.src == elwood && ip.dst == jake]
Page 6
NETSNOOP(1M)NETSNOOP(1M)FILES
.netsnooprc
$HOME/.netsnooprc User customization file
/tmp/.*.cache Protocol-dependent caches
/usr/sbin/netsnoop Executable
SEE ALSOanalyzer(1M), snoopd(1M), ypfiles(4), ethernet(7), snoop(7P),
NetVisualyzer User's Guide.
BUGS
You cannot start capturing based on match, interval, or count; nor is
there an option to stop capturing based on match.
Page 7
