NAM(1)

NAME
nam - the LBL Network Animator

SYNOPSIS
nam [ -p ] [ -m ] [ -g granularity ] [ -j jump ] [ -r rate ] tracefile [ layoutfile ]

DESCRIPTION

Nam is a tcl/tk based animation tool for viewing network simulations and packet trace data. A user define tcl procedure is invoked at start up to define the topology and layout. The animation is driven by trace data that, for example, is generated from ns(1) or tcpdump(1).

OPTIONS

-g  Specify granularity (simulated) seconds as the initial setting for the simulation granularity slider. The default granularity is 0.002 (2ms).

-j  jump over gaps of more than jump (simulated) seconds in the trace.

-r  Specify rate (real) milliseconds as the screen update rate. The default rate is 50ms (i.e., 20 frames per second). Note that the X server may not be able to keep up with this rate, in which case the animation will run as fast as the X server allows it to (at 100% cpu utilization).

-p  Start up with the simulation running. The default is to begin in a paused state so you can reposition and resize windows.

-m  Force monochrome on a color display (depending on your X server, this may significantly speed up the animation).

tracefile is the name of the file containing the trace data to be animated (format described below). If tracefile cannot be read, nam will try to open tracefile.tr.

layoutfile is the name of the file describing the graphical layout of the animation. (format described below). If no layoutfile is given, nam will try to open tracefile.lo (any trailing extension will be removed from tracefile before the .lo extension is appended).

THE ANIMATOR DISPLAY
The top of the nam display is a title bar which contains, from left to right,

-   Loop/single button: Controls whether nam plays the trace once then halts or rewinds at the end and replays. Clicking on this button will toggle between the two states.

-   Rewind button: clicking will restart the animation at its beginning (or the current lower limit).

-   Play/pause button: clicking will start a paused animation or pause a running animation.

-   The name of the trace file being animated and the time that file was last modified.

-   The current simulated clock, in seconds. I.e., the picture on the screen represents the network state at this time.

Below the title bar is a time scroller that shows the current (relative) position in the trace and allows you to change that position with the mouse. The left edge of the scroller represents the earliest event time in the trace file and the right edge represents the last event time. Click anywhere on the grey bar to set the simulated clock to the corresponding time. To set to a particular time, hold down the mouse button and slide the white scroller around until the simulated clock shows that time then release the mouse button. (Make sure the cursor is in the scroller's bar when you release the mouse button or nam might end up in a strange state.)

Below the time scroller are lower and upper limit indicators. These are intended to let you animate just a portion of a trace (this is particularly useful in `loop' mode to continuously replay some ``interesting'' event). If you click the left button in this region, the lower limit will be set to corresponding time. Clicking the right button sets the upper limit.

Below the limit indicators is a large window containing the animation (the contents of the window are largely determined by the layout file, described below).

At the right is the animation window is a granularity scroller that can be used to change the animation granularity (the amount the simulated clock changes between animator frames). Moving the scroller up make the animation coarser (larger clock step size) and moving it down makes the animation finer (smaller step size).

KEYBOARD COMMANDS
Most of the buttons have keyboard equivalents. Typing a space or return will pause nam if it's not already paused. If nam is paused, space or return will step the animation one simulated clock tick. (If your keyboard autorepeats, holding down space is a good way to slow-step through some part of the animation.) A `p' will pause but not step if paused. A `c' will continue after a pause. An `r' will rewind. `>' or `.' will increase the granularity (speed up) by 5%. `<' or `,' will decrease the granularity (slow down) by 5%.

LAYOUT FILE
The layout file is a pic-style representation of the network topology, drawing parameters, and ``strip chart'' graph options. The (modified) subset of pic recognized by nam includes the objects, circle, box, hexagon, source, router, sink, and edge.

Node objects (all of the previous excepting edge) require a small integral identification number that correponds to the events in the trace file. Nodes may be qualified with a position and a color. Note that only one node in a set of connected nodes can have a position, the remaining positions are fixed by the edge lengths (or ``link delays'') and directions. A position is specified by appending ``at x, y'' to the node definition. If none of the nodes in the network are anchored with such a definition, the first node entered defaults to (0,0). A node can be colored by appending ``color name'' to its definition, where name is a standard X color listed for instance in /usr/lib/X11/rgb.txt. The default color is black.

An edge definition requires the link delay of the corresponding network connection. An edge statement implicitly connects the previous node with the following node along the current direction. Alternatively, the edge can be hung off previous node definitions by appending either or both ``from label'' and ``to label'' where label is labels a previous node object. For example,
    edge 10ms from routerHost to sinkHost; describes an edge between to previously declared nodes.

The current path can be modified with the keywords up, down, right, left, and angle.

Generally speaking, a topology is specified by alternating node obects (i.e., source, router, circle) with edge objects.

TRACE FILE
Most entries in the trace file have the same format:
 <type> <time> <extent> <src> <dst> <conv> <ptype> <id> <type> is one of `h' (hop), `+' (enter queue), `-' (leave queue), and `d' (drop from queue). For all of these, <time> is when the event starts, <extent> is the size (in time) of the packet, <src> is the originating node, <dst> is the destination node (for queue types, the queue referenced is the one at <src> on the edge bound for <dst>), <conv> is the conversation number, <id> is the packet id in the conversation and <ptype> says if the packet should be drawn filled or hollow. `Value' entries in the trace file have the form:
 v <time> <name> <value> where <time> is the time that variable <name> had value <value>.

EXAMPLES

FILES
/usr/lib/X11/rgb.txt

SEE ALSO
tcpdump(1)

BUGS