Technical Q&A QA1176

Getting a Packet Trace

Q: I'm trying to debug a network problem. How do I take a packet trace?

A: There are a variety of tools to do this. They are listed below.

FrameSeer

FrameSeer is an inexpensive network packet capture application for Mac OS X.

CPA

Cocoa Packet Analyzer is a native Mac OS X implementation of a network protocol analyzer and packet sniffer.

IPNetMonitorX

IPNetMonitorX is a network troubleshooting toolkit for debugging Internet service problems and optimizing performance.

Wireshark

Wireshark is an open source packet analyzer that has been ported to Mac OS X. It requires X11.

tcpdump

This command line tool is included with all versions of Mac OS X, and is also available on many other Unix platforms. To get started, try the following command.

sudo tcpdump -i en0 -s 0 -B 524288 -w DumpFile.dmp

Each element of the command line is explained below.

• The sudo command causes tcpdump to run with privileges, which is necessary in order to capture network traffic.

• The -i en0 option tells tcpdump to capture packets on the first Ethernet interface. By default, tcpdump will use the first non-loopback interface it can find (usually en0). To specify a different interface, just change en0 to the BSD name of that interface. For example, the AirPort interface is typically en1.

  To get a list of network interfaces and their user-visible names, run the networksetup tool with the -listallhardwareports argument.

• The -s 0 option requests the full packet rather than just the first 68 bytes. This is the default on Mac OS X 10.6 and later.

• The -B 524288 option increases the packet capture buffer size to 512 KB. This is important to avoid dropped packets on high-speed networks. See Dropped Packets for more information about this.

• The -w DumpFile.dmp parameter tells tcpdump to dump the packets to a file called DumpFile.dmp.

In response to this command, tcpdump will begin to capture packets and put them in the DumpFile.dmp file. When you want to stop capturing, interrupt tcpdump by typing ^C. You can then display the contents of the packets as text using the following command.

tcpdump -s 0 -n -e -x -vvv -r DumpFile.dmp

New elements of the command line are explained below.

• The -n option means that addresses are not converted to domain names, which speeds things up considerably.

• The -e option causes tcpdump to display the link-level header for each packet.

• The -x option causes the contents of the packet to also be displayed in hex.

• The -vvv option makes tcpdump's output as verbose as possible.

• By specifying -r DumpFile.dmp option you tell tcpdump to read packets from the file DumpFile.dmp rather than from a network interface. Note that you don't need privileges to do this, so running tcpdump using sudo is not required.

You can also combine these steps, as shown below, but if you do this you don't get a high-fidelity record of the packets that you captured.

sudo tcpdump -i en0 -s 0 -n -e -x -vvv

You can learn about tcpdump from the online manual and from the book TCP/IP Illustrated, Volume 1: The Protocols, W. Richard Stevens, Addison-Wesley, 1994, ISBN 0-201-63346-9. That book is also an excellent introduction to TCP/IP protocols in general.

tcpflow

If you're debugging a high-level protocol, it's nice to be able to see the various TCP connections as streams of data rather than individual packets. The tcpflow tool can do that for you. For example, if you're debugging an HTTP client, you can run the following command.

sudo tcpflow -i en0 port 80

tcpflow will create a bunch of files in the current directory, each of which contains the reassembled contents of a single TCP stream. For example, if you run tcpflow as shown above and then fetch the URL http://apple.com, you can see how the HTTP redirect works.

$ sudo tcpflow -i en0 port 80
tcpflow[953]: listening on en0
^C
tcpflow[953]: terminating
$ ls -lh
total 16
-rw-r--r-- 1 root  quinn [...] 010.000.040.015.50232-017.149.160.049.00080
-rw-r--r-- 1 root  quinn [...] 017.149.160.049.00080-010.000.040.015.50232
$ cat 010.000.040.015.50232-017.149.160.049.00080
GET / HTTP/1.1
User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8k zlib/1.2.3
Host: apple.com
Accept: */*

$ cat 017.149.160.049.00080-010.000.040.015.50232
HTTP/1.1 302 Object Moved
Location: http://www.apple.com/
Content-Type: text/html
Cache-Control: private
Connection: close

<head><body> This object may be found <a HREF="http://www.apple.com/">here</a> </body>

tcpflow is not built-in to Mac OS X. You can get tcpflow in a variety of ways.

• Dowload and build the source code from its home site.

• Install it via a 'ports' project, like MacPorts or Fink.

• Dowload a pre-built binary from here.

HTTP Scoop

HTTP Scoop is an HTTP protocol analyzer for Mac OS X. It reconstructs complete HTTP conversations (rather than just showing the packets that make them up) and presents them in a user-friendly manner.

Miscellaneous Notes

Loopback Issues

Some tools have problems with packets being transferred to or from the trace machine (the machine running the tool). To avoid these problems, separate your trace machine from the machines whose network traffic you're tracing.

As an example of this, on Mac OS X tcpdump may, by default, display the TCP checksum of packets sent by the trace machine as bad. This is because of TCP checksum offloading; packets sent by the trace machine are captured before being handed to the network adapter, so they don't have the TCP checksum set correctly. This is not a fatal problem; if the bad checksums bother you, you can turn off tcpdump's checksum checking by passing in the -K option.

Dropped Packets

If you capture all the bytes of each packet (for example, by passing -s 0 to tcpdump), it's very easy to overrun the kernel's packet capture buffer. The symptoms of this overrun are that your packet capture tool will report that it dropped packets.

In the case of tcpdump, it prints a summary of how many packets were captured, filtered, and dropped when you stop the capture. For example:

$ sudo tcpdump -i en0 -s 0 -w DumpFile.dmp
tcpdump: listening on en0, link-type EN10MB (Ethernet), capture size 65535 bytes
^C
94 packets captured
177 packets received by filter
0 packets dropped by kernel

If the dropped count is non-zero, you need to increase the packet capture buffer size by passing the -B option to tcpdump, as discussed earlier.

Switches And Hubs

If you use a separate trace machine, you have to make sure that the trace machine can see the packets of interest. There are two ways to do this:

• Use a hub rather than a switch ‚Äî These days it is hard to find real hubs. Most 10/100 hubs are actually switches in disguise. However, it is possible to find a 10/100 hub that only switches between the different speed segments (for example, the SMC-EZ58xxDS range).

• Enable port mirroring ‚Äî On most advanced switches it is possible to configure the switch so that all traffic is mirrored to a specific port. To learn more about this, consult the documentation for your switch.

Capture Hints From The Wireshark Wiki

The Wireshark wiki has some really useful information about how to setup your packet tracing environment.

• The Ethernet Capture Setup Document contains good background information for setting up your network for monitoring.

• The Hub Reference Document contains information on various types of hubs.

• The Switch Reference Document contains information on analysis features, such as port mirroring, found on various models of switches, including links to online documentation for those switches.

Submitting A Trace To DTS

If you send a packet trace to DTS, please include the following:

• The system type and OS version of the trace machine.

• The name and version of the tool you used to capture the packet trace.

• If you've used a tool whose native file format is the libpcap file format (these include tcpdump, Wireshark, and various others), you can send us the packet trace file in its native format. Otherwise, please include a copy of the packet trace in both its native format and, if that native format isn't text, a text export of the trace as well. That way we're guaranteed to be able to read your packet trace.

• For each relevant machine shown in the trace, please describe the following:

  • the machine's role in the network conversation

  • the system type and OS version

  • the machine's IP address

  • the machine's hardware address (also known as the Ethernet address or MAC address)

Document Revision History