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:
There are three things in the tarball: cupid.jar, psyche (a directory), and README.txt. The last is simply a pointer to this document.
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):
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 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:
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.
As you might expect, psyche takes command line arguments. If you type:
you'll get a message that may be helpful. On my machine I get the following:
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:
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
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:
The properties files are named "net.callmeike.cupid.source.psyche.properties" and "net/callmeike/cupid/source/psyche/net.callmeike.cupid.source.psyche.properties". 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.