Running the net3d early release

Installing net3d

To run the early release of net3d, you will need the installation tarball, Sun's Java 3D API, a *nix computer, and a command line. This is a pre-release and not for the faint of heart.

Install the Sun Java 3D 1.3.1 API (OS X version) using the instructions on the site. Next download and unpack the net3d tarball:

tar -xzf net3d-bin-20040905.tgz

There are three things in the tarball: cupid.jar, psyche (a directory), and README.txt. The last is simply a pointer to this document.

Running Cupid

cupid.jar is the viewer. It is a java program and will probably run on most platforms. Start it by typing (in the directory containing the .jar file):

java -cp cupid.jar

After a short wait, you should see the net3d display. The amber regions indicate un-routable address (RFC1918). Before you move either of the sliders, the X-axis goes from your left to right, the Y-axis from the bottom of the screen to the top, and the Z-axis comes out of the screen at you. Moving the bottom and right sliders rotates the display around the Y- and X- axes, respectively. Packets will be shown in the space, source address on the X-axis, destination address on the Z-axis and destination port on the Y-axis. A red point is a TCP packet, blue is UDP, and yellow is anything else (likely ICMP). Until you run a sampler that feeds data about packets in your network, to the viewier, you won't see any packets.

Running Psyche

Running the sampler, psyche, is a bit more complicated. It runs only on *nix platforms, and requires a library called "pcap". Many BSD (including Mac OSX) and Linux distributions satisfy both these requirements. psyche also must run as root. Also, you will have to build it yourself.

Navigate to the 'psyche' directory, from the distribution. Look through the Makefile, to make sure it all looks reasonable (notably, it will attempt to install psyche at /usr/local/bin/psyche). You might even want to try a dry run ("make all") before you proceed. When you are ready, su to root and type:

make install

If all goes well, psyche will be built and installed. Make sure psyche is now on your PATH (refresh, cd to the installation directory, etc.), and type:


If you now use your browser, collect e-mail, chat, etc, teensy-weensy dots should appear in the Cupid display. They are graphic the representations of the packets traversing the network as you use it.

Advanced Psyche

As you might expect, psyche takes command line arguments. If you type:

./psyche -h

you'll get a message that may be helpful. On my machine I get the following:

psyche version 0.6
libpcap version 0.8
Usage: psyche [-i interface] [-s snaplen] rcvr_addr

You may need to use the -i switch. By default, psyche will let the pcap library choose an interface on which to listen for packets. It may not choose the one most interesting to you. For instance, the built-in ethernet on my machine is en0, and pcap chooses it. It is almost never connected to a network, though: I usually connect via en1, an airport card. If the lowest numbered ethernet interface is not the active network interface on your machine, you might need to type something like:

./psyche -ien1

While you can run psyche on the same machine as the viewer, the reason it is a separate program is that you can run it elsewhere. Run it near a service, on your firewall, anywhere you would like to monitor traffic. (Recall, of course, that an interface attached to a hub/repeater will see more traffic than one attached to a switch.) When you run psyche this way, you will have to tell it where to send the packets it collects (it defaults to sending them to a viewer on the same machine). Do this by supplying the final command line argument:


Psyche communicates with the viewer by sending UDP to port 47778. The viewer never sends anything to psyche.

There is one other command line switch, undocumented, that may be of interest: -d. It causes psyche to print debugging information during its processing

Advanced Cupid

Much of cupid's behavior is controlled by a standard java properties file. Changing these behaviors can be accomplished by changing the properties. To do this, unjar cupid:

jar -xf cupid.jar

The properties files are named "" and "net/callmeike/cupid/source/psyche/". The former controls the viewer itself, and the latter the receiver for the packet data sent by psyche.


The name of the program that inspired this one was "the Cube of Potential Doom", or CuPD.

I would be most pleased to respond to questions, comments and suggestions.