Provided by: nam_1.15-5.2_amd64 bug

NAME

       nam - VINT/LBL Network Animator

SYNOPSIS

       nam [ -g geometry ] [ -t graphInput ][ -i interval ] [ -P peerName ] [ -N appName ] [ -c
       cacheSize ] [ -f configfile ] [ -S ] tracefile

DESCRIPTION

       Nam is a Tcl/TK based animation tool for viewing network simulation traces and real  world
       packet trace data.

       The  first  step  to  use nam is to produce the trace file.  The trace file should contain
       topology information, e.g., nodes, links, as well as packet traces. The detailed format is
       described in the TRACE FILE section. Usually, the trace file is generated by ns(1). During
       an ns simulation, user can produce topology configurations, layout information, and packet
       traces using tracing events in ns. Refer to ns(1) for detailed information.

       When  the  trace  file is generated, it is ready to be animated by nam.  Upon startup, nam
       will read the trace file, create topology, pop up a window, do layout if  necessary,  then
       pause  at  the time of the first packet in the trace file. Through its user interface, nam
       provides control over many aspects of animation. These functionalities will  be  described
       in detail in the USER INTERFACE section.

       This  version  of  nam  is  highly  experimental  -  there  will be bugs!. Please mail ns-
       developers@mash.cs.berkeley.edu if you encounter any bugs, or with suggestions for desired
       functionality.

OPTIONS

       -g     Specify geometry of the window upon startup. The format is described in X(1)

       -t     [Information  incomplete]  Instruct  nam to use tkgraph, and specify input file nam
              for tkgraph.

       -i     [Information for this option may not be accurate] 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).

       -N     Specify  the application name of this nam instance. This application name may later
              be used in peer synchronization.

       -P     Specify the application name of the peer  nam  instance  whose  execution  will  be
              synchronized  with  the  execution  of this nam instance. Refer to the above option
              (-N) as how to specify application names.
              General usage is: (1) starting the first nam instance (slave) by:
              nam -N <name #1> <trace file name #1>
              Then start the second nam instance (which will be the master):
              nam -N <name #2> <trace file name #2>
              Then every animation control (play, stop, backward, but  exclude  other  inspection
              and interactive operations such as monitoring) will be synchronized between the two
              instances.
              Please note that because this mechanism uses Tcl's send command, it  requires  that
              your  X  server  used  xauth as authentication. Specifically, you should add option
              `-auth <authorization file name>' when you starts  your  X  server.   Without  this
              option,  X  will  use  xhost  as  authentication,  which is too weak and considered
              insecure. Refer to man page of Xsecurity, xauth and Xserver for  details,  and  the
              available authentication protocols.

       -c     [Information  incomplete]  The  maximum  size  of  the cache used to store 'active'
              objects when doing backward animation.

       -f     Name of the initialization files to be loaded during startup. In  this  file,  user
              can define functions which will be called in the trace file. An example for this is
              the 'link-up' and 'link-down' events of dynamic links in ns. (Refer to $ns  rtmodel
              for  detail,  and  tcl/ex/simple-dyn.tcl in your ns directory for example). Example
              initialization files can be found at ex/sample.nam.tcl and ex/dynamic-nam.conf.

       -S     Enable synchronous X behavior so it is easier  for  graphics  debugging.  For  UNIX
              system running X only.

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

OBJECTS IN NAM

       nam  does animation using the following building blocks: node, link, queue, packet, agent,
       monitor. They are defined below:

       node   Nodes  are  created  from  'n'  trace  event  in  trace  file.  It   represents   a
              source/host/router,  etc.  nam will terminate if there are duplicate definition for
              the same node. Node may have many shapes, (circle, square, and hexagon),  but  once
              created  it cannot change its shape.  Node may also have many colors, it can change
              its color during animation.  Refer to ns(1) for related tracing events.

       link   Links are created  between  nodes  to  form  a  network  topology.  nam  links  are
              internally  simplex,  but it is invisible to the users. The trace event 'l' creates
              two simplex links and other necessary setups, hence it looks to users identical  to
              a duplex link. Link may have many colors, it can change its color during animation.
              Refer to ns(1) for related tracing events.

       queue  Queue needs to be constructed in nam between two nodes. Unlike link, nam  queue  is
              associated  to  a  simplex  link.  The  trace  event 'q' only creates a queue for a
              simplex link. In nam, queues  are  visualized  as  stacked  packets.   Packets  are
              stacked  along  a  line,  the angle between the line and the horizontal line can be
              specified in the trace event 'q'.

       packet Packet is visualized as a block with an arrow. The direction of the arrow shows the
              flow direction of the packet. Queued packets are shown as little squares.  A packet
              may be dropped from a queue or a  link.  Dropped  packets  are  shown  as  rotating
              squares,  and  disappear  at the end of the screen. Dropped packets are not visible
              during backward animation.

       agent  Agents are used to separate protocol states from nodes. They are always  associated
              with  nodes.  An  agent has a name, which is a unique identifier of th agent. It is
              shown as a square with its  name  inside,  and  a  line  link  the  square  to  its
              associated node.

AUTOMATIC LAYOUT

       In  nam,  a  topology  is specified by alternating node objects with edge objects.  But to
       display the topology in a comprehensible way, a layout mechanism is needed. Currently  nam
       provides two layout methods.

       First,  user may specify edges' orientations. An edge orientation is the angle between the
       edge and the horizontal line, in the interval [0, 2*pi). During layout, nam will honor the
       given  edge  orientations.  Generally,  it  will first choose a reference node, then place
       other nodes using edge orientation and edge length, which is  determined  by  link  delay.
       This works well for small and manually generated topologies.

       Second,  when  we are dealing with randomly generated topologies, be it small or large, we
       may want to do layout automatically. An automatic graph  layout  algorithm  ([1]  [2])  is
       adapted  and  implemented.  The basic idea of the algorithm is to model the graph as balls
       (nodes) connected by springs (edges). Balls will repulse each other,  while  springs  pull
       them  together.  This system will (hopefully) converge after some iterations. In practice,
       after a small number of iterations (tens or hundreds), most  graphs  will  converge  to  a
       visually comprehensible structure.

       There are 3 parameters to tune the automatic layout process:

       Ca     Attractive  force  constant, which controls springs's force between balls.  Default
              value is 0.15

       Cr     Repulsive force  constant,  which  controls  the  repulsive  force  between  balls.
              Default value is 0.15

       Number of iterations
              Self explained. Default value is 10.

              For small topologies with tens of nodes, using the default parameters (perhaps with
              20 to 30 more iterations) will suffice to produce a nice layout.   But  for  larger
              topology, careful parameter tuning is necessary. Following is a empirical method to
              layout a 100 node random transit stub topology  generated  by  Georgia  Tech's  ITM
              internet  topology modeler. First,  set Ca_ and Cr_ to 0.2, do about 30 iterations,
              then set Cr_ to 1.0, Ca_ to about 0.01, then do about 10 iterations, then  set  Ca_
              to 0.5, Cr_ to 1.0, do about 6 iterations.

THE USER INTERFACE

       The  top  of  the nam nam window is a menu bar.  Two pulldown menus are on the left of the
       menu bar. The 'File' menu currently only contains a 'Quit'  button.  It  has  a  'Open...'
       button as well, but that is not implemented yet. The 'View' menu has 4 buttons:

       -      New view button: Creates a new view of the same animation. User can scroll and zoom
              on the new view. All views will be animated synchronously.

       -      Show monitors checkbox: If checked, will show a pane at the lower half  of  window,
              where monitors will be displayed.

       -      Show autolayout checkbox: If checked, will show a pane at the lower half of window,
              which contains input boxes and a button for automatic layout adjusts.  This box may
              not  always  be  enabled. When a trace file has its own layout specifications, this
              box will be disabled. If and only if the trace file does not have  complete  layout
              specification  (i.e., each link has orientation specified in the traces), will this
              box be enabled.

       -      Show annotation checkbox: If checked, will show a listbox  at  the  lower  half  of
              window, which will be used to list annotations in the ascending order of time.

              The 'Help' menu is on the right side of the menu bar. It has two buttons.  Clicking
              the 'Help' button will pop up a  new  window  showing  information  on  nam  usage.
              Clicking  the 'About' button will pop up a new window showing history and status of
              nam.

       Acceleration Keys
              ALT+'f' will pull down the 'File' menu. ALT+'v' will pull down the 'Open...'  menu.
              ESC will abort a menu selection in progress.

              Below  the  menu  bar,  there is a control bar containing 6 buttons, a label, and a
              small scrollbar (scale). They can be clicked in any order.  We  will  explain  them
              from left to right.

       Button 1 (<<)
              Rewind.  When  clicked,  animation  time  will  go back at the rate of 25 times the
              current screen update rate.

       Button 2 (<)
              Backward play. When clicked, animation will be played backward in time.

       Button 3 (square)
              Stop. When clicked, animation will pause.

       Button 4 (>)
              Forward play. When clicked, animation will be played in time ascending order.

       Button 5 (>>)
              Fast Forward. When clicked, animation time will go forward at the rate of 25  times
              the current screen update rate.

       Button 6 (Chevron logo)
              Quit.

       Time label
              Show the current animation time (i.e., simulation time as in the trace file).

       Rate slider
              Controls  the  screen  update  rate  (animation  granularity).  The current rate is
              displayed in the label above the slider.

       Below the first control bar, there is Main Display, which contains a tool bar and  a  main
       view  pane  with  two  panning scroll bars. All new views created by menu button 'File/new
       view' will have these three components.
       The tool bar contains two zoom buttons. The button with an up arrow zooms in,  the  button
       with a down arrrow zooms out. The two scroll bars are used to pan the main animation view.
       Clicking  the  left  button  on  any  of  the  objects in the main view pane will pop up a
       information window at the clicking point.  For  packet  and  agent  objects,  there  is  a
       'monitor' button in the popup window. Clicking that button will bring out the monitor pane
       (if it is not there), and add a monitor to the object. For link object, there  will  be  a
       'Graph'  button.  Clink  that  button  will bring out another popup window, where user can
       select drawing bandwidth utilization graph or link loss graph of one of  the  two  simplex
       links of the duplex link clicked on. These functionalities are also available in the views
       created by 'File/new view'.  NOTE:  These  functionalities  are  HIGHLY  EXPERIMENTAL  AND
       UNSTABLE in this release (v1.0a2).

       Below  the  gadgets  we  have  discussed  so  far, there may or may not be a Monitor pane,
       depending on whether the checkbox 'View/show monitors' is set. (The default is unset). All
       monitors  will  be  shown  in  this  pane.  A monitor looks like a big button in the pane.
       Currently only packet and agent may have monitor.
       A packet monitor shows  the  size,  id,  and  sent  time.  When  the  packet  reaches  its
       destination, the monitor will still be there, but saying the packet is invisible.
       A  agent  monitor  shows  the  name  of  the  agent,  and if there are any variable traces
       associated with this agent, they will be shown there as well.

       Below the monitor pane (or in its place if the monitor pane isn't there), there is a  Time
       Slider.   It  looks  like  a scaled rule, with a tag 'TIME' which can be dragged along the
       rule. It is used to set the current animation time.  As you drag the 'TIME'  tag,  current
       animation time will be displayed in the time label in the control bar above. The left edge
       of the slider represents the earliest event time in the trace  file  and  the  right  edge
       represents the last event time.
       Clicking  left  button  on  the  rule  (not the tag) has the same effect as Rewind or Fast
       Forward, depending on the clicking position.

       The Automatic Layout Pane can be visible or hidden. If  visible,  it  is  below  the  time
       slider.   It  has  three  input boxes and one relayout button. The labeled input boxes let
       user adjust two automatic layout constants, and  the  number  of  iterations  during  next
       layout.  When  user press ENTER in any of the input boxes, or click the 'relayout' button,
       that number of iterations will be performed. Refer to the  AUTOMATIC  LAYOUT  section  for
       details of usage.

       The  bottom  component  of  the  nam window is a Annotation Listbox, where annotations are
       displayed. An annotation is a (time, string) pair, which describes  a  event  occuring  at
       that  time.  Refer  to  ns(1)  for  functions  to generate annotations. Double-click on an
       annotation in the listbox will bring nam to the time when that annotation is recorded.
       When pointer is within the listbox, clicking right button will stop animation and bring up
       a  popup  menu  with 3 options: Add, Delete, Info. `Add' will bring up a dialog box with a
       text input and add a new annotation entry which has the current animation time.  User  can
       type  annotation  string  in  the  dialog  box.  `Delete' will delete the annotation entry
       pointed by the pointer. `Info' will bring out a pane which shows both the annotation  time
       and the annotation string.

KEYBOARD COMMANDS

       [Incompelete,  but accurate] Most of the buttons have keyboard equivalents. Note they only
       function when mouse cursor is inside the nam window.
       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.)

       `p' or `P'
              Pause but not step if paused.

       `c' or `C'
              Continue after a pause.

       `b' or `B'
              Descrease animation time for one screen update interval.

       `r' or `R'
              Rewind.

       `f' or `F'
              Fast Forward.

       `n' or `N'
              Move to next event.

       `x' or `X'
              Undo the last rate change

       `u' or `U'
              Undo the last time slider dragging.

       `>' or `.'
              Increase the granularity (speed up) by 5%.

       `<' or `,'
              Decrease the granularity (slow down) by 5%.

       SPACE  Toggle the pause state of nam.

       `q', `Q' or Control-c
              Quit

RECORDING ANIMATIONS

       To  record  nam animations, select the ``Record Animation'' option under the file menu.  A
       series of namXXX.xwd files will be produced (where XXX is the frame number), one per time-
       step.   These files can then be assembled into animated GIFs or MPEGs with the appropriate
       post-processing tools.

TRACE FILE FORMAT

       The trace file events can be divided into 6 types, depending on to which object the  event
       is associated. Below, we discuss them in detail.

       Packet Basic packet events are a type character, followed by some tags:

                      <type> -t <time> -e <extent> -s <src_addr> -d <dst_addr> -c <conv> -i <id>

              <type> is one of:

              `h'  -  Hop.  The  packet  started  to  be transmitted on the link from src_addr to
              dst_addr
              `r' - Receive. The packet finished transmission and started to be received  at  the
              destination.
              `d' - Drop. The packet was dropped from queue or link from src_addr to dst_addr.
              `+' - Enter queue. The packet entered the queue from src_addr to dst_addr.
              `-' - Leave queue. The packet left the queue from src_addr to dst_addr.

              Drop  here doesn't distinguish between dropping from queue or link. This is decided
              by the drop time.

              The flags have the following meanings:

              -t <time> is the time the event occurred.
              -e <extent> is the size (in bytes) of the packet.
              -s <src> is the originating node.
              -d <dst> is the destination node.
              -c <conv> is the conversation id.
              -i <id> is the packet id in the conversation.
              -a <attr> is the packet attribute, which is currently used as color id.

              Additional flags may be added for some protocols. This  list  may  be  extended  as
              required:

              -P  <pkt_type>  gives  an  ASCII string specifying a comma separated list of packet
              types. Some values are: TCP - a tcp data packet.  ACK  -  generic  acknowledgement.
              NACK - generic negative acknowledgement.  SRM - SRM data packet.
              -n <sequence number> gives the packet sequence number.

       Link/Queue State

              l -t <time> -s <src> -d <dst> -S <state> [-c <color>] [-r <bw> -D <delay>]
              q -t <time> -s <src> -d <dst> -a <attr>

              <state>  gives  the  link  state  transition. It has 3 possible values: UP and DOWN
              marks link failure and recovery, COLOR marks link color change. If COLOR is  given,
              a following -c <color> is expected which gives the new color value.  In link event,
              [-r <bw> -D<delay>] gives link bandwidth and delay, respectively. It is  only  used
              when nam creates the link, i.e., loading the trace file.
              <attr>  specifies  the queue position, i.e., the angle between the link along which
              queued packets are displayed and the horizontal line.

       Node State

              n -t <time> -s <src> -S <state> [-c <color>] [-o <color>] [-A <labels>]

              Flags `-t', `-S' and `-c' have the same meaning as those in Link. Flag `-A' is used
              to  add  a  arbitrary  string  to  the label of the node. It can be used to display
              explainations of a node's state. Flag `-o' is used in backtracing  to  restore  old
              colors of a node.

       Node Mark

              Node marks are colored circles around nodes. They are created by:

              m -t <time> -n <mark name> -s <node> -c <color> -h <shape> [-o <color>]

              and can be deleted by:

              m -t <time> -n <mark name> -s <node> -X

              Note  that  once created, a node mark cannot change its shape. The possible choices
              for shapes are, circle, square, and hexagon. They are defined as lower-case strings
              exactly as above.

       Protocol State

              Agents can be constructed by:

              a -t <time> -n <agent name> -s <src> -d <dst>

              They can be destructed by:

              a -t <time> -n <agent name> -s <src> -d <dst> -X

              To  visualize  protocol  state  variables associated with an agent, we use the name
              `feature'. Currently we allow three types of features:  timers,  lists  and  simple
              variables. But only the last one is implemented in ns(1) tracing APIs.

              Features may be added or modified at any time after agent creation using:

              f -t <time> -a <agent name> -T <type> -n <var name> -v <value> -o <prev value>

              <type>  is  `l' for a list, `v' for a simple variable, `s' for a stopped timer, `u'
              for an up-counting timer, `d' for a down-counting timer.
              -v <value> gives the new value of the variable. Variable values  are  simple  ASCII
              strings  obeying  the TCL string quoting conventions. List values obey the TCL list
              conventions. Timer values are ASCII numeric values.
              -o <prev value> gives the previous value of the variable. This is to allow backward
              play of animation.

              Features may be deleted using:

              f -t <time> -a <agent name> -n <var name> -o <prev value> -X

       Misc   v -t <time> TCL script string

              is used for annotation, it may includes an arbitrary tcl script to be executed at a
              given time, as long as the script is in one line (no more than 256 characters). The
              order of flag and the string is important.

              c -t <time> -i <color id> -n <color name>

              defines a color. The color name should be one of the names listed in color database
              in X11 (/usr/X11/lib/rgb.txt). After this definition, the color can  be  referenced
              using its id.

EXAMPLES

FILES

       /usr/lib/X11/rgb.txt

SEE ALSO

       tcpdump(1)

       [1]    Fruchterman,  T.M.J. and Reingold, E.M., Graph Drawing by Force-directed Placement,
              Software - Practice and Experience, vol. 21(11), 1129-1164, (November 1991).

       [2]    Amir, E., Carta: A Network Topology Presentation Tool, Project Report, EECS  Dept.,
              UC Berkeley, 1993.  http://http.cs.berkeley.edu/~elan/mbone.html

       Mailing  lists  for  nam  users and announcements are the same as those for ns users. Send
       email to ns-users-request@mash.cs.berkeley.edu or ns-announce-request@mash.cs.berkeley.edu
       to join.  Questions should be forwarded to ns-users@mash.cs.berkeley.edu, ns-announce will
       be low-traffic announcements only.

BUGS

       This manual page is incomplete.

                                           04 Nov 1997                                     NAM(1)