4 - Oversim overview

The first thing to know about Oversim, is that it's built on Omnet++. This means that if you want to learn Oversim, you have to first learn, at least the basics, of Omnet++. Luckily, Omnet++ has en excellent manual, which should be the first step in learning Oversim. I recommend reading the manual at least to Chapter 10 (a PDF is also available).

To be able to learn Oversim, the following Omnet++ concepts should be studied:

1. The basics of the NED language, used to define modules.
2. The concept of simple and compound modules.
3. How modules use gates to communicate.
4. The concept of channels.
5. Message and packet definitions.
6. Self messages.
7. Configuring simulations (omnetpp.ini) and assigning values to module parameters.
8. How to run simulations in both the command-line environment, as well as the graphical user environment.

Once these Omnet++ concepts are known, one can continue learning concepts central to Oversim.

Oversim is basically an Omnet++ simulation that adds specialized modules to simplify the task usually present in simulating a peer-to-peer network, using some routing overlay. At the start of a basic (and sometimes even very advanced) Oversim simulation, there exists a single module, called the Churn Generator. It is the task of the churn generator to generate all network peers at times drawn from some distribution. Setting up an Oversim simulation, therefore usually means that some module type has to be defined as your network peer and this module will then be created by the churn generator. Multiple churn generators can exist, that generate multiple modules types at differing rates.

A key concept in Oversim is that each peer consists of multiple layers that emulate the Internet protocol stack from the transport layer upwards. The functionality of each layer is provided by an underlying module. When one sets up an Oversim simulation, the configuration phase entails specifying the module responsible for each layer in the protocol stack, for each type of peer in the simulation. In other words, each churn generator requires information on all the layers of the peer that it will be creating.

To specify what types of peers should be generated, which modules should be implemented in the different layers and to configure the parameters of the peers as well as the simulation environment, Oversim uses the omnetpp.ini and the default.ini files. A basic configuration is as follows:

[Config Chord]

description = Chord (iterative, SimpleUnderlayNetwork)

*.underlayConfigurator.churnGeneratorTypes = "oversim.common.LifetimeChurn"

**.overlayType = "oversim.overlay.chord.ChordModules"

**.tier1Type = "oversim.applications.kbrtestapp.KBRTestAppModules"

Each configuration starts with the "Config" keyword, followed by the configuration name, e.g., [Config Chord]. This will identify the configuration at simulation runtime. Note that a single configuration, for example the one shown above, specify all parameters of the simulation. This means that for a single configuration run, the parameter values given are the only values that will be used. Therefore, one configuration specifies one experiment. A configuration file can be set up to perform multiple runs, when multiple values are given to some of the parameters with the ${value1, value2} definition.

For each configuration, a description should be provided to inform the user as to the purpose of the experiment.

The following line:

*.underlayConfigurator.churnGeneratorTypes = "oversim.common.LifetimeChurn"

Specifies what type of churn generator should be used. It is also possible to use multiple churn generators to generate multiple module types. There are three types of churn generators in Oversim, "NoChurn", "LifetimeChurn" and "ParetoChurn". The most basic is the "NoChurn" churn generator. It just creates the specified number of peers and then stops. This is usually a good place to start when creating your fist simulation. After that, the nasty effects of churn can be investigated with the remaining two generators.

The options for churn generation, therefore are:

1. *.underlayConfigurator.churnGeneratorTypes = "oversim.common.NoChurn"
2. *.underlayConfigurator.churnGeneratorTypes = "oversim.common.LifetimeChurn"
3. *.underlayConfigurator.churnGeneratorTypes = "oversim.common.ParetoChurn"

One can specify multiple churn generators as follows:

*.underlayConfigurator.churnGeneratorTypes = "oversim.common.NoChurn oversim.common.NoChurn oversim.common.ParetoChurn"

This will have Oversim create three churn generators, two NoChurn and one ParetoChurn. When using multiple churn generators, the complete protocol stack of every peer types should be defined (details to follow).

The last two lines of the configuration specify the protocol layer types of the peer. The possible layer types are "overlay", "tier1", "tier2" and "tier3", appended with the word "Type". This is the architecture view also shown Figure 1.1 of the Introduction section of this site and replicated here for the reader's convenience:

This picture does not tell the complete story, since every layer is also connected to the UDP and TCP layers, which allows one to send message between the same layer on different nodes using either TCP or UDP. The easiest is usually just to use UDP, except of course if the simulation requirement is that the effect of TCP (ramping and back-off) also be taken into account. Because Oversim is a simulation environment, UDP can be used with 100% reliability (it is of course also possible to simulate UDP packet loss).

Oversim allows every layer to send and receive messages from the layers directly above and below it (It should probably later be described how this is done). To go back to the last two lines of the original example, the second last line:

**.overlayType = "oversim.overlay.chord.ChordModules"

Specifies that the overlay network should be a Chord overlay. More specifically, it specifies that, for this layer, the compound module "ChordModules", which is situated in oversim/overlay/chord, should be used.

Usually when creating an Oversim simulation, the developer wishes to build her own Oversim overlay and investigate how it compares to existing Overlays, or the developer wishes to create some novel application(s) that uses existing overlays for some specialised functionality. Creating an application or overlay, entails writing a C++ class. It is therefore advised that Oversim users have a decent understanding of C/C++.

In the following sections, Oversim's design of the overlay and application layer will be discussed, as well as an explanation of the core concepts required to write either an overlay or an application.