netsnoop(1M)
netsnoop - capture and decode network traffic
As shipped in IRIX 6.5.19. Last changed in IRIX 6.5.19.
NAME netsnoop - 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. -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. -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: 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 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 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] FILES .netsnooprc $HOME/.netsnooprc User customization file /tmp/.*.cache Protocol-dependent caches /usr/sbin/netsnoop Executable SEE ALSO analyzer(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.