Scalable Simulation Framework
How to use SSFNet
SSFNet design overview - read first
       package SSF.OS
  package SSF.Net
  DML configuration database
  how to run SSFNet models
  parallel execution
TUTORIAL 1: how to write DML network models
       simplest networks: host configuration
  complex networks: addresses and routing
       about VLSM IP addressing (CIDR)
  user-defined address aggregation
  composing very large networks
TUTORIAL 2: how to write SSFNet protocols
       SSF.OS protocol design pattern
  timers and blocking I/O
TUTORIAL 3: SSFNet measurement infrastructure
       Distributed network monitoring
  Example of queue monitors
TUTORIAL 4: Animation of SSFNet models
TCP requirements and SSF validation tests
Net DML schema reference manual
SSFNet programming guidelines

SSFNet design overview

SSFNet is a collection of Java SSF-based components for modeling and simulation of Internet protocols and networks at and above the IP packet level of detail. Link layer and physical layer modeling can be provided in separate components.

SSFNet models are self-configuring - that is, each SSFNet class instance can autonomously configure itself by querying a configuration database, which may be locally resident or available over the Web. The network configuration files are in the DML format. They are used to configure a complete model, and instantiate a simulation with the help of the scalable DML configuration database package that is distributed with the SSF simulators.

The principal classes used to construct virtually any Internet model are organized into two derivative frameworks, SSF.OS (for modeling of the host and operating system components, esp. protocols) and SSF.Net (for modeling network connectivity, creating node and link configurations).

The frameworks SSF.OS and SSF.Net hide all details of the discrete event simulator SSF API, allowing to implement the protocols like for a real operating system.

package SSF.OS

The principal classes of package SSF.OS are:

  1. ProtocolGraph
  2. ProtocolSession
  3. ProtocolMessage and PacketEvent

This architecture makes it simple to add a new protocol without any changes to the framework, provided its main class is derived from ProtocolSession, and (if desired) comes with a private DML configuration that extends the base ProtocolSession's DML schema. Importantly, on shared memory machines SSF.OS provides significant performance optimizations by implementing zero-copy message processing and protocol method call chaining.

These classes allow to create an abstract protocol graph and install in it any combination of protocols (in a generalized sense, including not only IP, TCP, BGP, etc., but also network device drivers, and client/server applications). The idea of SSF.OS has been originally inspired by the x-kernel, but the design of SSF.OS is simpler, and it differs from the x-kernel in many ways.

Internet protocol models are packages built atop SSF.OS, such as SSF.OS.IP, SSF.OS.TCP, SSF.OS.OSPF, etc., and their variants. ProtocolGraph provides methods for establishing proper dependence relations among the installed protocols. Each Internet protocol package SSF.OS.* in the SSFNet distribution has a test subdirectory with usage examples, and a suite of validation tests (TCP validation has its own website).

package SSF.Net

The principal classes of package SSF.Net are:

  1. Net
  2. Host and Router
  3. NIC
  4. link

Class Net loads all the model's DML configuration files and controls the orderly instantiation of the entire model: hosts and routers with their protocols, links connecting hosts and routers, as well as traffic scenarios and multiple random number streams. As you will see in the tutorials, DML configuration is hierarchical, and allows recursive composition of larger networks from pre-configured sub-networks.

Class Host is actually derived from SSF.OS.ProtocolGraph, which means that it is fully configurable and can support any network protocol graph. Minimally, this must include IP (which provides routing) and at least one NIC (Network Interface Card). A Router is a special case of a Host with multiple NICs, and possibly a specialized protocol graph.

Class NIC derived from ProtocolSession is a bottom-level pseudo-protocol that maintains a pair of buffered SSF in/outChannels to the world outside the protocol graph. A NIC may be connected to another NIC on the same link, by transparently mapping the encapsulated in/outChannels. NIC has various configuration options for physical link characteristics, packet flow buffering and scheduling, that may be configured from a matching DML description.

Class link models link-layer connectivity among a set of attached interfaces. A link with more than two attached interfaces implicitly performs level-2 routing of IP packets sent on any attached interface.

DML network configuration database

High-level model description is aided by a simple, standardized syntax of all configuration files, the Domain Modeling Language (DML). The DML syntax specifies a hierarchy of lists of attributes (key-value pairs), that can be stored as ASCII files which are easy to read and interpret. For details see the DML Reference Manual.

The DML package (such as com.renesys.raceway.DML included in the library raceway.jar) together with the DML standard of model configuration files support a uniform and efficient approach to the closely related tasks of:

  • model description (configuration),
  • model instantiation in the first phase of a simulation run,
  • runtime inspection (reflection).

DML is simple and easy to read and write directly by modelers. At the same time, DML is intended as a target of network design and validation tools, and as a machine-independent model exchange format suitable for storage in databases.

DML is an application-independent package: it defines a Configuration interface for the classes that store and provide access to DML configurations in memory, and a Configurable interface for any class that can self-configure itself using the attributes obtained from the matching Configuration objects. It also contains the class dmlConfig that can read and parse the DML files and produce the corresponding runtime searchable Configuration objects.

Any configurable derivative framework created above the SSF API can use the services of the DML package to configure a model.

About configurable design patterns

Below the SSFNet network modeling layers is the SSF API. SSF is a completely general discrete event modeling and simulation framework that can be used to build models in virtually any domain of science and engineering. Since too much design freedom may be counterproductive in designing models within a restricted application domain (such as IP internetworks), in our approach all models in a given application domain are composed using domain-specific, configurable derived frameworks.

A derived framework is an OO framework written atop another framework. In our case, such a framework consists of one or more packages, each consisting of several cooperating abstract classes that:

  • express the standard modeling patterns appropriate for the application domain,
  • are Configurable, and matched with the corresponding DML schemas.

Parametrization and reflection in SSF models is achieved by the pairing of classes implementing the Configurable interface with DML schemas:

Configurable class ----- DML schema(s),

while an instantiated parametrized object is paired with a DML tuple:

Configured object ----- DML tuple(s).

In the SSFNet 1.x releases the DML tuples are stored as ASCII files, therefore we interchangeably say 'DML tuple' or 'DML configuration file'.

How to run SSFNet models

We assume here that you have installed SSFNet and JDK1.2 or JDK1.3 and you know how to run java programs from command line. You must include in the classpath the jarfiles in the directory ssfnet/lib, and the parent directory of any class files that are required (see e.g. the Java Tool Documentation page).

For instance, if you installed SSFNet on Windows in directory D:\ssfnet, you have downloaded the Raceway library raceway.jar (it contains the SSF simulator kernel and DML), and your network model description is in a DML configuration file D:\private\myBigModel.dml, you could run it as follows from directory D:\private\:

  set CLASSPATH=D:\ssfnet\lib\raceway.jar;D:\ssfnet\lib\ssfnet.jar
  set CLASSPATH=%CLASSPATH%;D:\ssfnet\lib\cernlite.jar

  set CLASSPATH=%CLASSPATH%;D:\ssfnet\lib\raceway.jar

  set CLASSPATH=%CLASSPATH%;D:\ssfnet\lib\regexp.jar
  set CLASSPATH=%CLASSPATH%;D:\ssfnet\src\

  java SSF.Net.Net 1234 myBigModel.dml D:\ssfnet\examples\net.dml

and similarly on a UNIX system, with proper changes in the pathnames (BTW, we wrote it this way for readability, it's recommended to use the -classpath option).

Above, "1234" is the value of the requested simulation end time in seconds; and D:\ssfnet\examples\net.dml is the official DML SSFNet schema file that is used for automatic validation of your input DML file, myBigModel.dml.

At the start of the sumulation run, SSF.Net.Net object will use the services of the DML library to load the content of the files myBigModel.dml and net.dml into a runtime Configuration database object. After that, SSF.Net.Net will systematically instantiate and configure all simulation objects (Hosts, Routers, protocols, and network links). Once all simulation objects have been instatiated, the initialization phase begins (Entity subclasses call their init() method), and finally SSF.Net.Net invokes its method startAll(), and the simulation begins with simulation time value equal to 0 sec. There is a lot of verbose output, including the automatically generated IP address blocks etc., that may be suppressed by command line options to SSF.Net.Net.

Note: To run very large models, you may need to use java command line options specifying the amount of memory required (e.g., -Xms and -Xmx options on Windows). You should also be aware that not all versions of JDK support unlimited parallel thread execution, check the documentation.

Parallel execution of SSFNet models

At the low level, the parallel execution is achieved by the SSF simulator kernel by maintaining multiple event queues, and executing them on multiple processors with proper synchronization. How it actually happens depends on the simulator kernel implementation, on the Java platform, and on the operating system. Vastly oversimplifying, on shared memory multiprocessors (SMP) such as multiprocessor Intel PCs running Linux or Windows NT, or on multiprocessor SUN Solaris Enterprise servers, the SSF kernel will execute in multiple system threads running in parallel. SSFNet and SSF hide from the modelers all such details.

Instead, a modeler can direct parallel execution at the DML model specification level. SSF is then responsible for transparently mapping this directive onto available machine resources. By the way, it is completely legal to specify N-way parallel execution in a model and then run it on a machine with fewer or single processor, and indeed often you can achieve a better performance in this way.

Partition of a DML network model for parallel execution is controlled by an optional string-valued alignment attribute of Hosts, Routers, Links and Nets. The values associated with that attribute are resolved globally, so that any two Hosts, Nets etc. that specify the same integer or string value will get the same alignment (and will therefore execute on the same processor if available). Alignments may also be specified for Net attributes, in which case all hosts, routers, and links within the Net get that alignment by default. The latter is the most frequently used option for large, multi-Net models.

The default is to omit all "alignment" attributes, resulting in serial (single timeline) execution.

Below is a DML fragment showing the use of the "alignment" attributes. This is a concise DML description of four copies of a network called campus24 whose gateway routers are connected in a ring topology, with "alignment" attributes specifying four-processor parallel execution:

   Net [
     frequency 1000000000  # specifies time resolution 1/1000000000 = 1 nanosecond

     # below we import the preconfigured networks
     # and align them to four named timelines
     Net [id 10 alignment "cpu0"  _extends .networks.campus24.Net]
     Net [id 11 alignment "cpu1"  _extends .networks.campus24.Net]
     Net [id 12 alignment "cpu2"  _extends .networks.campus24.Net]
     Net [id 13 alignment "cpu3"  _extends .networks.campus24.Net]

     # specify ring connectivity using topological addresses of router interfaces
     link [ attach 10:0:0(3) attach 11:0:0(4) _find .params.as2as.delay]
     link [ attach 11:0:0(3) attach 12:0:0(4) _find .params.as2as.delay]
     link [ attach 12:0:0(3) attach 13:0:0(4) _find .params.as2as.delay]
     link [ attach 13:0:0(3) attach 10:0:0(4) _find .params.as2as.delay]
     # specify that co-aligned consumers of random number streams
     # will share one generator per timeline for efficiency
     randomstream [
       generator "MersenneTwister"
       stream "seedstarter4"
       reproducibility_level "timeline"

     # traffic specifications omitted...
   ] # end of Net

See the SSFNet tutorials for explanation of the attributes' names and values. Note the use of the inheritance keyword "_extends" and substitution keyword "_find" - they can save a lot of space when some attributes would otherwise unnecessarily repeat.

Note 1: For good performance, you should balance the computational load among the timelines, and choose a network partition in such a way that links crossing from one timeline to another have as large delay as possible.

See viewgraph 1 on parallel performance on a multiprocessor SUN Enterprise server.

Note 2: You don't need a big server to obtain good parallel performance. SSFNet users often benefit from parallelization on dual-CPU Intel workstations running Linux or NT, and see nice speedups.

See viewgraph 2 on parallel performance on a dual-CPU Windows NT workstation.