vRouter 0.02 (July 05, 1999)
----------------------------

Author: Blake Scholl <bscholl+@cmu.edu>
Web Page: http://www.andrew.cmu.edu/~bscholl/vRouter

Contributors:  (Get your name here - check out the 'how you can help' section)

Contents:
 1. Overview
 2. How to Compile
 3. How to Run
 4. Changes
 5. Writing Network Descriptor Files
 6. About the Program
 7. To Do 
 8. How You Can Help
 9. About the Author

1. Overview
-----------

The vRouter Project is an _experimental_ project which aims to develop 
an open-source IP network simulator. It can be used to evaluate IP 
Internetwork designs before they are implemented in the field.  
When feature complete, vRouter will be able to simulate the 
behavior of a network under specific network traffic conditions.

As vRouter becomes better developed and tested in the future, it could
provide a testing-ground for new IP services (routing schema,
multicast, QoS) before they are deployed on a real network.

As a network simulator, vRouter is highly experimental.  As of yet, I have
not verified that vRouter produces results which accurately reflect real
network performance (apart from confirming that results 'make sense' with 
respect to my experience).  Once some major improvements are completed in the
simulator, I hope to test the simulator by comparing it with real-world data.
If you're trying vRouter on your network, I'd be interested to know how
well its data matches empirical measurements on your network, or even
if you think it makes any sense.

Of course, vRouter is "as-is," with no warranties, stated or implied.  vRouter
is experimental software; the author cannot take responsibility for any 
dammages or costs incurred as a result of using vRouter.  vRouter is "open 
source," licensed under the latest version of the GNU Public License.
(See www.gnu.org, www.opensource.org for more information). 

Email your comments to the author, Blake Scholl, at bscholl+@cmu.edu.

2. How to Compile:
------------------
Unpack the source archive you downloaded and run 'make'.  That should work.
I'm looking for volunteers to help out with adding GNU autoconf/automake
support and porting to other platforms.

3. How To Use:
--------------

The vRouter executable is called 'configreader' -- it parses network
descriptor files given on standard-in.

To use, make a network descriptor file.  Sample network descriptors are
n the files "network" and "simple-network".  The vRouter configreader
program accepts network descriptions on standard-in.

Run "./configreader < simple-network" for a demonstration of vRouter.


4. Changes
----------

Version 0.02
------------

Changes visible to users:
 - Network descriptor files now support comments 
    - '#' at the beginning of a line marks it as a comment
 - Unlimited routers and datalinks
 - Unlimited route table entries on routers
 - New queuing-theory-based delay calculations for datalinks
   improve accuracy of simulations
 - 'traffic' directive in descriptor file no longer supported
 - Misc. bugfixes & improved stability

Changes for developers:

The biggest change in 0.02 is a vastly improved object model.  

- (almost) Completely rewritten parser:
   - Two parser classes, 'netparser' and 'simparser' inherit from 
     from 'parse', which provides utility functions for reading 
     from network descriptor files and filters out comments.  If you
     look at configreader.cpp, you'll notice almost all of the guts have
     been moved out into other objects (where it should be)
- New Objects:
   - Netreader, Simreader, and Parse for parsing (see above)
   - Network : encapsulates a profile of a network (including routers and
               datalinks)
   - Simulator : Contains the code for running a simulation and displaying
                 results.

DataLink now implements Poisson Arrivals-based delay calculations.


Bug fixes:
- Simulation now works correctly with small timeslices
- Misc. stability bugs & memory bugs fixed

5. Writing Network Descriptor Files
-----------------------------------

If you'd like to jump in and start writing your own network descriptors,
take a look at the included descriptor file 'network' which is heavily 
commented.  

If you want more information, which is very important if you're interesting
in learning the important caveats and quirks of vRouter, read further.

Here's a brief summary of how some of the configuration commands work.  Note
that not all parameters are currently supported, but the configreader will
get angry if you don't include them.

When specifying an IP address, always provide the dotted-decimal with
prefix notation.  For example, if we wish to refer to the IP address
192.168.5.10, with netmask 255.255.0.0, we would write 192.168.5.10/16.
For those of you not familiar with prefix notation, the /16 is a "prefix
length," the number of bits in the network portion of the IP address.  A 
traditional "class A" network would be /8, a "class B" would be /16, and
a "class C" /24.  The network address need not end on byte boundries.  
vRouter supports VLSM (variable length subnet masking) and CIDR (Classless
Inter-Domain Routing).  Make sure you ALWAYS supply a prefix length
anywhere an IP address is specified.  Failure to do so will cause the 
configreader to flake out.

The first step in writing a vRouter network descriptor file is declaring 
data links.  In the current version, DataLinks behave somewhat like switched
ethernet.  When a datalink receives a packet for delivery (via 
a call to deliverPacket(Packet *)), it looks through the IP addresses known to
be connected to it and calls deliverPacket(Packet *) on the correct router.  
Right now, there are only routers, no plain-vanilla hosts.  Think of a host 
as a router with only one interface.

The syntax for declaring a datalink is:
   datalink (network address) (bandwidth, in bps) (delay, in ms)

vRouter identifies datalinks by their network address.

By default, vRouter supports up to 15 datalinks.  To change this value,
change the value of "MAX_DATALINKS" near the top of configreader.cpp.  
By default, datalinks support a maximum of 5 attached routers.  To change
this, change the value of "DL_MAXHOSTS" in router.h.  

The next step is to define the routers that link together your network.
Routers are identified by a single-word name.  A router with no interfaces
and no routing information looks like this:

   router this_is_the_name_of_my_router
   end-router

Next, equip your router with interfaces.  An interface is a router's connection
to one of the datalinks you declared earlier.  An interface has two parameters:
the network address identifying the datalink the router is connected to and the
router's IP address on that datalink.  Here's how you declare an interface:

   router my_router
      interface (datalink network address) (IP address on network)
   end-router

By default, routers can have up to 5 interfaces.  To change this, alter
the value of "RTR_MAXDATALINKS" near the top of router.h.  By default,
routers can buffer 1000 packets on each interface.  This can be changed by
altering "PKT_BUFF_SIZE" in router.cpp.  If a router's queue gets overflowed,
packets are dropped from the end of the queue.  

Now that your router has connections to the network, you must tell it how
to forward packets.  Currently, vRouter supports only static routing.  As this
makes simulation of large internetworks cumbersome, later versions of vRouter
will likely include support for auto-generation of routing tables.  Routers
in vRouter automatically know how to forward packets to directly connected
datalinks.  You must provide static routes to all other networks on your
internetwork.  vRouter has no problems with route aggregation.  To specify
a default route (sometimes refered to a "gateway of last resort"), simply
specify the destination address as "0.0.0.0/0."  

Routes take 3 parameters:  a destination address, a next hop address, and
a metric.  The destination address is the network address of the destination
for the route you are specifying.  The next hop address is the address of the
next router to which packets should be forwarded to reach their destination.  
vRouter does not support recursive route table lookups; thus, the next hop 
address MUST lie on a directly connected network.  Furthermore, route lookups 
are performed by linear search through the routes in the order they are 
specified in the network descriptor file.  Packets are forwarded to the first route  which matches their destination address.  Thus, most specific routes (longest prefix lengths) should be specified first.  The default route MUST be specified last; any routes after it will be ignored.  (This behavior may change in the  future; the implementation of routing tables is currently a terrible hack which is slow and inefficient.  A vastly improved routing table will be implemented once the rest of vRouter is stable.) 

Routing metrics are currently ignored.  Future versions of vRouter will
likely support metric-based route selection and equal-cost multipath routing.
It's a good idea to set metrics to 0 for now; in the future, routes with
lower metrics will be favored.  Metrics must take integer values.  Don't 
be evil and specify routes with negative metrics.  

Here is how you specify a route:

route (destination network) (next hop address) (metric)

Routers currently support up to 10 route table entries each.  Again,
to change this value, adjust the value of "RTR_MAXROUTES" in router.h.

When you're done specifying routers, the description of the network itself
is complete.  Enter "end-network" to signify that your network is complete.

The next part of the network descriptor file provides parameters for the 
simulation.  You can have multiple simulations within a network descriptor
file; they will be executed sequentially, one after another.

Begin a simulation with the "simulation" keyword.  Next, specify flows on 
your network.  A flow is a stream of packets from a single source to a single
destination with a constant packet size and transmition rate.  Flows start
at a particular point in the simulation (specified in ms elapsed since the 
start of the simulation) and continue for a certain duration (measured in ms
elapsed since the flow started).  At the end of the simulation, vRouter
reports statistics for each flow: percentage of packets delivered and
average delay (among packets successfully delivered).  In the future,
vRouter will keep track of other data as well, such as jitter.  (Jitter refers
to the variation in delays of packets in a flow.)  

Declare a flow like this:

flow (source router name) (source IP) (destination IP) (packet size in bytes) (data rate in packets per second) (begin time) (duration)

For example: flow seattle 10.0.1.2/24 10.0.5.23/24 1024 1000 0 50
That statement declares a flow beginning at a router named seattle with
packet source address 10.0.1.2/24 and destination address 10.0.5.23/24.  
Packets are 1024 bytes each, and 1000 packets are transmitted per second.  The
flow begins at 0ms (the beginning of the simulation) and lasts for 50ms.  Note
that the source address is currently ignored by vRouter.  The destination
address is used to deliver the packet to the destination router.

When you have declared flows for your simulation, use the "run" command to 
run a simulation.  Run takes two parameters, the timeslice length and number of
timeslices.  vRouter simulates the continuous operation of an Internetwork
with a discrete model, in which routers take turns operating for a timeslice.
In general, the smaller the length of the timeslice the more accurate the
simulation.  Timeslices which are too small, however, may cause innacurrate
calculations to do large roundoff errors.  This is a bug, and will be fixed in
later versions.  The duration of the simulation is the product of the timeslice
length and the number of timeslices.  Note that program running time increases
linearly with the number of timeslices.  

A run command looks like this:
    run (timeslice length) (number of timeslices)


You can specify more flows after a run command; they will be added to the 
currently specified flows and will be present in future run commands within
a simulation.  Flows, however, are scoped to a single simulation.  Runs
declared in one simulation will not be present in subsequent simulations.

End your simulation with "end-simulation".

End your network descriptor file with "end".

Note that support for "traffic" directives in network descriptor files
are no longer supported since version .02.


6. About the Program
--------------------

vRouter attempts to model an IP-based internetwork using C++ objects to
represent routers, datalinks, and packets.  Relevent classes are 
IPAddress (ipaddress.h and IPAddress.cpp), Packet (packet.h), Router (router.h
and router.cpp), DataLink (router.h and DataLink.cpp), and flow (flow.h).  The
configreader (configreader.cpp) handles parsing of network descriptor files
and 

vRouter makes active use of C++ STL (standard template library) classes.  It 
is known to compile with g++ 2.7.2 and egcs 1.1.2 running on Linux 2.2.

7. To Do
--------

vRouter is quite incomplete.  Here are a few things on my personal vRouter
wish-list.  Please email your comments/suggestions to bscholl+@cmu.edu.

In no particular order . . .

* Documentation: vRouter needs better documented code and better instructions
  for users.

* Automake/Autoconf Support:  We all know that automake is a good thing.

* Multiple Platform Support:  vRouter runs on Linux now, but it'd be good
  to have support for Solaris or whatever misc. unices people are interested
  in using. 

* Cleanup, modernization:  vRouter is currently little more than a hack.
  I implemented things quickly to get a "proof of concept" version
  operational.  As a result, inefficient algorithms and data structures are
  everywhere.  There is much work to be done in bringing the codebase up to a
  resonable standard of cleanliness. 

* Improved customization: Behavior of routers and datalinks should be
  configurable from within a network descriptor file.

* Automated route table generation: Making all those static routes is 
  annoying.  vRouter needs to have the option of auto-generating routing 
  tables based on network topologies.  

* Equal cost multipath:  Multipath routing is not supported currently,
  but is cleary very important in the development of a useful network
  simulator.  

* Weighted Queuing:  Multiple queuing schemes for routers, prioritized queues
  for differientated services ('diffserv') -- queuing algorithms should be
  selectable from within a network descriptor file.

* Broadcast packets : Broadcast packets essentially are not supported
  in vRouter.  This needs to be fixed.

* Multicast Support:  Wouldn't it be nice to be able to simulate the behavior
  of multicast traffic?  Perhaps a virtural implementation of PIM (Protocol
  Independant Multicast) or MOSPF (Multicast Open Shortest Path First) would
  lend insights into the construction of real multicast-enabled networks.

* GUI :  Wouldn't it be nice if you could create network descriptors
  with a nice drag-and-drop GUI?  I certainly think so; this feature
  is on a "wish list" and will probably be implemented only if I can find 
  someone else who is interested in helping out.

8. How You Can Help
-------------------

Take a look at the above section on what features I'd like to see in vRouter;
if anything interests you, take a hack at it!

The three biggest things I'd like some help with are automake/autoconf support,
a GUI, and documentation (an HTML version of this file would be nice).

Ultimately, it's good if people work on what they want to.  If something is
screaming 'fix me!' to you or is of particular interest, go ahead and tackle
it.  I'd love to integrate your patches and fixes and I'm happy to give you
credit in sources and documentation and on the vRouter web site.

9. About the Author
-------------------

Blake Scholl just completed his freshman year studying Computer Science
at Carnegie Mellon University.  He is currently working as a Software
Development Engineer Intern at RealNetworks.