[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Commands Reference, Volume 5


tcpdump Command

Purpose

Prints out packet headers.

Syntax

tcpdump [ -d ] [  -e ] [  -f ] [  -I ] [  -n ] [  -N ] [  -O ] [  -p ] [  -q ] [  -S ] [  -t ] [  -v ] [  -x ] [  -c Count ] [  -F File ] [  -i Interface ] [  -r File ] [  -s Snaplen ] [  -w File ] [ Expression ]

Description

The tcpdump command prints out the headers of packets captured on a network interface that matches the boolean Expression parameter. If no Expression parameter is given, all packets on the network will be dumped. Otherwise, only packets for which the Expression parameter is True will be dumped. Only Ethernet, Fiber Distributed Data Interface (FDDI), token-ring, and loopback interfaces are supported. Access is controlled by the permissions on /dev/bpfO,1,2, and 3.

The Expression parameter consists of one or more primitives. Primitives usually consist of an id (name or number) preceded by one or more qualifiers. There are three types of qualifier:

type Specifies what kind of device the id name or number refers to. Possible types are host, net, and port. Examples are host foo, net 128.3, port 20. If there is no type qualifier, host is assumed.
dir Specifies a particular transfer direction to or from id. Possible directions are src, dst, src or dst, and src and dst. Some examples with dir qualifiers are: src foo, dst net 128.3, src or dst port ftp-data. If there is no dir qualifier, src or dst is assumed.
proto Restricts the match to a particular protocol. Possible proto qualifiers are: ether, ip, arp, rarp, tcp, and udp. Examples are: ether src foo, arp net 128.3, tcp port 21. If there is no proto qualifier, all protocols consistent with the type are assumed. For example, src foo means ip or arp, net bar means ip or arp or rarp net bar, and port 53 means tcp or udp port 53.

In addition to the above, there are some special primitive keywords that do not follow the pattern: broadcast, multicast, less, greater, and arithmetic expressions. All of these keywords are described below.

Allowable Primitives

Primitives allowed are the following:

dst host Host True if the value of the IP (Internet Protocol) destination field of the packet is the same as the value of the Host variable, which may be either an address or a name.
src host Host True if the value of the IP source field of the packet is the same as the value of the Host variable.
host Host True if the value of either the IP source or destination of the packet is the same as the value of the Host variable. Any of the above host expressions can be prepended with the keywords ip, arp, or rarp as in:

ip host Host

If the Host variable is a name with multiple IP addresses, each address will be checked for a match.

dst net Net True if the value of the IP destination address of the packet has a network number of Net.
src net Net True if the value of the IP source address of the packet has a network number of Net.
net Net True if the value of either the IP source or destination address of the packet has a network number of Net.
dst port Port True if the packet is TCP/IP (Transmission Control Protocol/Internet Protocol) or IP/UDP (Internet Protocol/User Datagram Protocol) and has a destination port value of Port. The port can be a number or a name used in /etc/services. If a name is used, both the port number and protocol are checked. If a number or ambiguous name is used, only the port number is checked (dst port 513 will print both TCP/login traffic and UDP/who traffic, and port domain will print both TCP/domain and UDP/domain traffic).
src port Port True if the value of the Port variable is the same as the value of the source port.
port Port True if the value of either the source or the destination port of the packet is Port. Any of the above port expressions can be prepended with the keywords tcp or udp, as in:

tcp src port port

which matches only TCP packets.

less Length True if the packet has a length less than or equal to Length. This is equivalent to:

len < = Length.

greater Length True if the packet has a length greater than or equal to the Length variable. This is equivalent to:

len > = Length

ip proto Protocol True if the packet is an IP packet of protocol type Protocol. Protocol can be a number or one of the names icmp, udp, or tcp.

Note: The identifiers tcp, udp, and icmp are also keywords and must be escaped via \ (backslash), which is \\ (double backslash) in the korn-shell.
ip broadcast True if the packet is an IP broadcast packet. It checks for the all-zeroes and all-ones broadcast conventions, and looks up the local subnet mask.
ip multicast True if the packet is an IP multicast packet.
proto Protocol True if the packet is of type Protocol. Protocol can be a number or a name like ip, arp, or rarp.

Note: These identifiers are also keywords and must be escaped via \ (backslash).
ip, arp, rarp Abbreviations for:

proto p

where p is one of the above protocols.

tcp, udp, icmp Abbreviations for:

ip proto p

where p is one of the above protocols.

Relational Operators of the Expression Parameter

The simple relation:

expr replop expr

Holds true where relop is one of > (greater than), < (less than), >= (greater than or equal to), <= (less than or equal to), = (equal), != (exclamation point and equal sign) and expr is an arithmetic expression composed of integer constants (Expressed in standard C syntax), the normal binary operators + (plus sign), - (minus sign), * (asterisk), / (slash), & (ampersand), | (pipe), a length operator, and special packet data accessors. To access data inside the packet, use the following syntax:

proto [ expr : size ]

Proto is one of the keywords ip, arp, rarp, tcp or icmp, and indicates the protocol layer for the index operation. The byte offset relative to the indicated protocol layer is given by expr. The indicator size is optional and indicates the number of bytes in the field of interest; it can be either one, two, or four, and defaults to one byte. The length operator, indicated by the keyword len, gives the length of the packet.

For example, expression ip[0] & 0xf != 5 catches only unfragmented datagrams and frag 0 of fragmented datagrams. This check is implicitly implied to the tcp and udp index operations. For instance, tcp[0] always means the first byte of the TCP header, and never means the first byte of an intervening fragment.

Combining Primitives

More complex filter expressions are built up by using the words and, or, and not to combine primitives. For example, host foo and not port ftp and not port ftp-data. To save typing, identical qualifier lists can be omitted. For example, tcp dst port ftp or ftp-data or domain is exactly the same as tcp dst port ftp or tcp dst port ftp-data or tcp dst port domain.

Primitives may be combined using a parenthesized group of primitives and operators (parentheses are special to the Shell and must be escaped).

Negation has highest precedence. Alternation and concatenation have equal precedence and associate left to right.

If an identifier is given without a keyword, the most recent keyword is assumed. For example,

not host gil and devo

is short for

not host gil and host devo

which should not be confused with

not \(host gil or devo\)

Expression arguments can be passed to the tcpdump command as either a single argument or as multiple arguments, whichever is more convenient. Generally, if the expression contains Shell metacharacters, it is easier to pass it as a single, quoted argument. Multiple arguments are concatenated with spaces before being parsed.

Protocol Output Formats

The output of the tcpdump command is protocol-dependent. The following are brief descriptions and examples of most output formats.

TCP Packets

The general format of a TCP protocol line is:

src  >  dst: flags data-seqno ack win urg options

In the following list of fields, src, dst and flags are always present. The other fields depend on the contents of the packet's TCP protocol header and are output only if appropriate.

src Indicates the source (host) address and port. The src field is always specified.
dst Indicates the destination address and port. The dst field is always specified.
flags Specifies some combination of the flags S (SYN), F (FIN), P (PUSH) or R (RST) or a single . (period) to indicate no flags. The flags field is always specified.
data-seqno Describes the portion of sequence space covered by the data in this packet (see example below).
ack Specifies (by acknowledgement) the sequence number of the next data expected from the other direction on this connection.
win Specifies the number of bytes of receive buffer space available from the other direction on this connection.
urg Indicates there is urgent data in the packet.
options Specifies TCP options enclosed in angle brackets (for example, <mss 1024>).

Here is the opening portion of the rlogin command from host gil to host devo:

gil.1023 > devo.login:S 768512:768512(0) win 4096 <mss 1024>
devo.login > gil.1023:S 947648:947648(0) ack 768513 win 4096 <mss
1024>
gil.1023 > devo.login: . ack 1 win 4096
gil.1023 > devo.login: P 1:2(1) ack 1 win 4096
devo.login > gil.1023: ack 2 win 4096
gil.1023 > devo.login: P 2:21(19) ack 1 win 4096
devo.login > gil.1023: P 1:2(1) ack 21 win 4077
devo.login > gil.1023: P 2:3(1) ack 21 win 4077 urg 1
devo.login > gil.1023: P 3:4(1) ack 21 win 4077 urg 1

The first line says that TCP port 1023 on host gil sent a packet to the login port on host devo. The indicates that the SYN flag was set. The packet sequence number was 768512 and it contained no data. (The notion is `first:last(nbytes)' which means `sequence numbers first up to but not including last which is nbytes bytes of user data'.) There was no piggy-backed ack field, the available receive field win was 4096 bytes and there was a max-segment-size(mss) option requesting an mss of 1024 bytes.

Host Devo replies with a similar packet except it includes a piggy-backed ack field for host gil's SYN. Host gil then acknowledges host devo's SYN. The . (period) means no flags were set. The packet contains no data so there is no data sequence number.

Note: The ack field sequence number is a small integer (1).

The first time a tcpdump sees a TCP conversation, it prints the sequence number from the packet. On subsequent packets of conversation, the difference between the current packet's sequence number and this initial sequence number is printed. This means that sequence numbers after the first can be interpreted as relative byte positions in the conversation's data stream (with the first data byte each direction being 1). The -S flag overrides this feature, causing the original sequence numbers to be output.

On the sixth line, host gil sends host devo 19 bytes of data (bytes 2 through 20 in the gil-devo side of the conversation). The PUSH flag is set in the packet. On the seventh line, host devo says it received data sent by host gil up to but not including byte 21. Most of this data is apparently sitting in the socket buffer since host devo's receive window has gotten 19 bytes smaller. Host devo also sends one byte of data to host gil in its packet. On the eighth and ninth lines, host devo sends two bytes of urgent PUSH data to host gil.

UDP Packets

UDP format is illustrated by this rwho command packet:

devo.who > bevo.who: udp 84

This command sequence says that port who on host devo sent a udp datagram to port who on host bevo. The packet contained 84 bytes of user data.

Some UDP services are recognized (from the source or destination port number) and the higher level protocol information is printed. In particular, Domain Name service requests (RFC-1034/1035) and Sun RPC calls (RFC-1050) to NFS.

UDP Name Server Requests

Name server requests are formatted as:

src > dst: id op? flags qtype qclass name (len)

In addition to those fields previously explained, UDP name server requests have the following:

id Specifies the identification number of the query.
op Specifies the type of operation. The default is the query operation.

qclass

name

(len)

An example of a name server rquest is:

tnegev.1538 > tnubia.domain: 3+ A? austin.ibm.com. (37)

Host tnegev asked the domain server on tnubia for an address record (qtype=A) associated with the name austin.ibm.com. The query id was 3. The + (plus sign) indicates the recursion desired flag was set. The query length was 37 bytes, not including the UDP and IP protocol headers. The query operation was the normal one, Query, so the op field was omitted. If the op had been anything else, it would have been printed between the 3 and the + . Similarly, the qclass was the normal one (C_IN), and it was omitted. Any other qclass would have been printed immediately after the A.

A few anomalies are checked and may result in extra fields enclosed in square brackets. If a query contains an answer, name server, or authority section, then ancount, nscount, or arcount are printed as [na], [nn] or [nau] where n is the appropriate count. If any of the response bits are set (AA, RA, or rcode) or any of the `must be zero' bits are set in bytes two and three [b2&3=x] is printed, where x is the hex value of header bytes two and three.

UDP Name Server Responses

Name server responses are formatted as:

src > dst: id op rcode flags a/n/au type class data (len)

In addition to those fields previously explained, UDP name server responses have the following:

rcode

data

An example of a name server response is:

tnubia.domain > tnegev.1538: 3 3/3/7 A 129.100.3
tnubia.domain > tnegev.1537: 2 NXDomain* 0/1/0 (97)

In the first example, tnubia responds to query 3 from tnegev with 3 answer records, name server records, and 7 authority records. The first answer record is type A (address) and its data is internet address 129.100.100.3. The total size of the response was 273 bytes, excluding UDP and IP headers. The op (Query) and response code (NoError) were omitted, as was the class (C_IN) of the A record.

In the second example, tnubia responds to query 2 with a response code of non-existent domain (NXDomain) and with 0 answer records, 1 name server record, and 0 authority records. The (asterisk) indicates that the authoritative answer bit was set. Since there were no answers, no type, class, or data were printed.

Other flag characters that might appear are - (recursion available, RA, not set) and | (truncated message, TC, set).

Note: Name server requests and responses tend to be large and the default snaplen of 80 bytes may not capture enough of the packet to print. Use the -s flag to increase the snaplen if you need to investigate large quantities of name server traffic.

NFS Requests

Sun NFS (Network FIle System) requests and replies are formatted as:

src.xid > dst.nfs: len op args
src.nfs > dst.xid: reply stat len

In addition to fields previously explained, NFS requests and responses include these fields:

args Specifies the directory file$file handle$.
reply stat Indicates the response status of the operation.

An example of an NFS request and response is:

L1.e2766 > L2.nfs: 136 readdir fh 6.5197 8192 bytes @ 0
L2.nfs > L1.e2766: reply ok 384
L1.e2767 > L2.nfs: 136 lookup fh 6.5197 `RCS'

In the first line, host L1 sends a transaction with id e2766 to L2 (note that the number following the src host is a transaction id, not the source port). The request was 136 bytes, excluding the UDP and IP headers. The operation was a readir (read directory) on file handle (fh) 6.5197. Starting at offset 0, 8192 bytes are read. L2 replies ok with 384 bytes of data.

In the third line, L1 asks L2 to lookup the name `RCS' in directory file 6.5197. Note that the data printed depends on the operation type.

Note: NFS requests are very large and the above won't be printed unless snaplen is increased. Use the flag -s 192 to watch NFS traffic.

ARP/RARP Packets

Address Resolution Protocol/Reverse Address Resolution Protocol (ARP/RARP) output shows the type of request and its arguments. The following example shows the start of the rlogin command from host devo to host bevo:

arp who-has bevo tell devo
arp reply bevo is-at 1d:2d:3d:4d:5d:6d

The first line says that devo sent an ARP packet asking for the Ethernet address of Internet host bevo. In the second line bevo replies with its Ethernet address.

IP Fragmentation

Fragmented Internet datagrams are printed as:

(frag id:size@offset+)
(frag id:size@offset)

The first form indicates that there are more fragments. The second indicates this is the last fragment. IP fragments have the following fields:

id Identifies the fragment.
size Specifies the fragment size (in bytes) including the IP header.
offset Specifies the fragment's offset (in bytes) in the original datagram.

The fragment information is output for each fragment. The first fragment contains the higher level protocol header and the frag info is printed after the protocol info. Fragments after the first contain no higher level protocol header and the frag info is printed after the source and destination addresses. For example here is a ping echo/reply sequence:

gil > devo: icmp: echo request (
frag 34111: 1480@0+)
gil > devo: (frag 34111!28@1480)
devo > gil: icmp: echo reply (frag
                   15314:148@0+)

A packet with the IP don't fragment flag is marked with a trailing (DF).

Timestamps

By default, all output lines are preceded by a timestamp. The timestamp is the current clock time in the form

hh:mm:ss.frac

and is as accurate as the kernel's clock. The timestamp reflects the time the kernel first saw the packet. No attempt is made to account for the time lag between when the ethernet interface removed the packet from the wire and when the kernel serviced the new packet interrupt.

Flags


-c Exits after receiving Count packets.
-d Dumps the compiled packet-matching code to standard output, then stops.
-e Prints the link-level header on each dump line. If the -e flag is specified, the link level header is printed out. On Ethernet and token-ring, the source and destination addresses, protocol, and packet length are printed.
-f Prints foreign internet addresses numerically rather than symbolically.
-F Uses File as input for the filter expression. The -F flag ignores any additional expression given on the command line.
-i Listens on Interface. If unspecified, the tcpdump command searches the system interface list for the lowest numbered and configured interface that is up. This search excludes loopback interfaces.
-I (Capital i) Specifies immediate packet capture mode. The -l flag does not wait for the buffer to fill up.
-l (Lowercase L) Buffers the standard out (stdout) line. This flag is useful if you want to see the data while capturing it. For example:

tcpdump -l : tee dat
 
 or
 
 tcpdump -l > dat & tail -f dat
-n Omits conversion of addresses to names.
-N Omits printing domain name qualification of host names. For example, the -N flag prints gil instead of gil.austin.ibm.com.
-O Omits running the packet-matching code optimizer. This is useful only if you suspect a bug in the optimizer.
-p Specifies that the interface not run in promiscuous mode.

Note: The interface might be in promiscuous for some other reason; hence, -p cannot be used as an abbreviation for `ether host {localhost}' or `broadcast'.
-q Quiets output. The -q flag prints less protocol information so output lines are shorter.
-r Reads packets from File (which was created with the -w option). Standard input is used if File is "-".
-s Captures Snaplen bytes of data from each packet rather than the default of 80. Eighty bytes is adequate for IP, ICMP, TCP, and UDP but may truncate protocol information from name server and NFS packets (see below). Packets truncated because of a limited snapshot are indicated in the output with "[|proto]", where proto is the name of the protocol level at which the truncation has occurred.

Note: Taking larger snapshots increases the amount of time it takes to process packets thereby decreasing the amount of packet buffering. This may cause packets to be lost. You should limit Snaplen to the smallest number of bytes that capture the protocol information you are interested in.
-S Prints absolute rather than relative TCP sequence numbers.
-t Omits the printing of a timestamp on each dump line.
-tt Prints an unformatted timestamp on each dump line.
-v Specifies slightly more verbose output. For example, the time to live and the type of service information in an IP packet is printed.
-w Writes the raw packets to File rather than parsing and printing them out. They can later be printed with the -r flag. Standard output is used if  File is "-".
-x Prints each packet (minus its link level header) in hex. The smaller of the entire packet or Snaplen bytes will be printed.

Examples

  1. To print all packets arriving at or departing from devo:

    tcpdump host devo
    
  2. To print traffic between gil and either devo or bevo:

    tcpdump ip host gil and \(devo bevo\)
    
  3. To print all IP packets between bevo and any host except gil:

    tcpdump ip host bevo and bevo gil
    
  4. To print all traffic between local hosts and hosts on network 192.100.192:

    tcpdump net 192.100.192
    
  5. To print traffic neither sourced from nor destined for local hosts:

    tcpdump ip and not net localnet
    
  6. To print the start and end packets (the SYN and FIN packets) of each TCP conversation that involves a non-local host:

    tcpdump \(tcp[13] \& 3 !=0 and not src and dst net localnet\)
    
  7. To print all ICMP packets that are not echo requests or replies (not ping packets):

    tcpdump \(icmp[0] !=8 and icmp[0] !=0\)
    
  8. To immediately print packet information, enter

    tcpdump -I
    
  9. To specify the token-ring interface to listen on, enter:

    tcpdump -i tr0
    
  10. To print packet information to the file TraceInfo, enter:

    tcpdump -wTraceInfo
    


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]