Appendix: tcpflow

Note: tcpflow is a UNIX-based program for monitoring Internet traffic. It is available for Mac OS X (and bundled with Interarchy). tcpflow is roughly equivalent to Interarchy's Show Traffic command, which is only available under Mac OS 9 and earlier.

tcpflow is a program that captures and stores or displays data transmitted on a TCP/IP network. It is very useful for debugging network problems. For example, it is possible to watch what really passes between a web browser and a web server, including HTTP headers with cookies, etc.

The software was written by Jeremy Elson, and the homepage for the package is listed below under Further Information.

Installation

You must have an "administrator" account on the Mac OS X machine in order to install tcpflow.

Installation is simple: just double-click the tcpflow package icon and the standard Apple installer will launch. Authenticate yourself as administrator when asked to, then follow the simple instructions.

Usage Examples

tcpflow is a command-line tool, which means that you have to open a Terminal window and type in commands in order to use it -- some examples are shown below. The Terminal application is inside /Applications/Utilities on Mac OS X.

By default, tcpflow captures all traffic it sees on the specified network interface, which is usually more than desired. To alleviate this problem, you can write simple filter expressions to tell it what data you're interested in.

We're only giving a few short examples here, but the filter language is very powerful and goes far beyond this. The filtering syntax is documented in the tcpflow man page; available with the command "man tcpflow".

To capture HTTP traffic to and from your machine use this command:

  sudo tcpflow -c port 80

tcpflow must be executed by a user with administrative access on the system, and the "sudo" command activates that access. The "-c" tells tcpflow to display the captured data directly in the Terminal window instead of storing it into files. Everything thereafter -- "port 80" in this case, to specify HTTP (web) traffic -- is the filter expression.

After issuing this command, you will get results immediately if there is ongoing HTTP traffic; otherwise the program will wait after the "listening on" message:

  [localhost:~] user% sudo tcpflow -c port 80
  tcpflow[3924]: listening on en1

Here is an example of tcpflow's output when requesting a web page. The browser's request is displayed immediately:

  192.168.1.1.54156-131.179.144.110.00080: GET /~jelson/software/tcpflow/ HTTP/1.0
  Connection: Keep-Alive
  User-Agent: Mozilla/4.5 (compatible; OmniWeb/4.0.3; Mac_PowerPC)
  Pragma: no-cache
  Host: www.circlemud.org
  Accept-Encoding: gzip
  Accept-Language: en, de, fr, nl, it, ja, es

As you can see, every data packet captured and displayed by tcpflow starts with a short header that looks like this:

  192.168.1.1.54156-131.179.144.110.00080

This indicates where the data is coming from and where it is going. The address on the left of the dash is the source IP address and port (IP 192.168.1.1, port 54156). The destination address and port follow the dash.

The source address is your computer and the destination address is the remote web server.

Right after the browser's request comes the server's response:

  131.179.144.110.00080-192.168.1.1.54156: HTTP/1.1 200 OK
  Date: Tue, 07 Aug 2001 13:38:29 GMT
  Server: Apache/1.3.12 (Unix) mod_perl/1.24
  Last-Modified: Fri, 08 Jun 2001 19:41:17 GMT
  ETag: "2b818-1e32-3b212a5d"
  Accept-Ranges: bytes
  Content-Length: 7730
  Keep-Alive: timeout=15, max=100
  Connection: Keep-Alive
  Content-Type: text/html

  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/strict.dtd">
  <html>
  <head>
  <title> tcpflow -- TCP Flow Recorder </title>
  <link rel=StyleSheet href="../../style.css">
  </head>
  ...

Again, you can see the data is prefixed by the header, this time your computer's address is on the right side of the dash, indicating that it is the receiver of the data.

tcpflow continues to show all the traffic passing through port 80 until you press Ctrl-C to stop monitoring.

Some more examples:

  sudo tcpflow -c host 192.168.1.2

This will show you all traffic to and from the machine with the IP address 192.168.1.2, regardless of the port, (i.e., you would see HTTP requests, e-mail transfers, etc.).

  sudo tcpflow -c host 192.168.1.2 and not port 80

This is similar to the command above, but this time it will skip any HTTP traffic. This demonstrates multiple criteria, which can be combined with keywords like "and", "not" and "or" for sophisticated filtering. More info on keywords and filtering is available in the documentation listed below.

Further Information

tcpflow's home page is at http://www.circlemud.org/~jelson/software/tcpflow/.

The man page contains very detailed instructions. To view it, either type "man tcpflow" in a Terminal window, or have a look at the HTML version at http://www.circlemud.org/~jelson/software/tcpflow/tcpflow.1.html.

The most recent version for Mac OS X will always be available at http://www.entropy.ch/software/macosx/.

tcpflow is based on the libpcap library. More information about libpcap is available at http://www.tcpdump.org/.

August 7, 2001 / Marc Liyanage http://www.entropy.ch/