


User Commands                                              NAM(1)



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  func-
     tionality.

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 synchroniza-
          tion.



SunOS 5.6           Last change: 04 Nov 1997                    1






User Commands                                              NAM(1)



     -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 ani-
          mation.

     -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 exam-
          ple). 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



SunOS 5.6           Last change: 04 Nov 1997                    2






User Commands                                              NAM(1)



          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 anima-
          tion. 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  orien-
     tation  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



SunOS 5.6           Last change: 04 Nov 1997                    3






User Commands                                              NAM(1)



     delay. This works well  for  small  and  manually  generated
     topologies.

     Second, when we are dealing with randomly generated  topolo-
     gies,  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 itera-
     tions (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 itera-
          tions) 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  anima-
          tion.  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



SunOS 5.6           Last change: 04 Nov 1997                    4






User Commands                                              NAM(1)



          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 list-
          box  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 for-
          ward  at the rate of 25 times the current screen update
          rate.

     Button 6 (Chevron logo)
          Quit.

     Time label



SunOS 5.6           Last change: 04 Nov 1997                    5






User Commands                                              NAM(1)



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

     Rate slider
          Controls the screen update  rate  (animation  granular-
          ity).  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' but-
     ton. 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



SunOS 5.6           Last change: 04 Nov 1997                    6






User Commands                                              NAM(1)



     position.

     The Automatic Layout Pane can be visible or hidden. If visi-
     ble,  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 List-
     box,  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 annota-
     tions. 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  key-
     board 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  inter-
          val.

     `r' or `R'
          Rewind.

     `f' or `F'
          Fast Forward.




SunOS 5.6           Last change: 04 Nov 1997                    7






User Commands                                              NAM(1)



     `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 dis-
     cuss them in detail.

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

                  <type> -t <time> -e <extent> -s  <srcaddr>  -d
          <dstaddr> -c <conv> -i <id>

          <type> is one of:

          `h' - Hop. The packet started to be transmitted on  the
          link from srcaddr to dstaddr
          `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 srcaddr to dstaddr.
          `+' - Enter queue. The packet entered  the  queue  from
          srcaddr to dstaddr.
          `-' - Leave queue.  The  packet  left  the  queue  from
          srcaddr to dstaddr.



SunOS 5.6           Last change: 04 Nov 1997                    8






User Commands                                              NAM(1)



          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 <pkttype> 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  pos-
          sible  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, respec-
          tively. 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>]

          Flags have th same meaning as those in Link.


     Protocol State



SunOS 5.6           Last change: 04 Nov 1997                    9






User Commands                                              NAM(1)



          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 vari-
          ables.  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.  Vari-
          able  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  vari-
          able. 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  charac-
          ters). 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.





SunOS 5.6           Last change: 04 Nov 1997                   10






User Commands                                              NAM(1)



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.






























SunOS 5.6           Last change: 04 Nov 1997                   11



