marshallasch/rhpman repository overview

⁠rhpman-sim

This NS-3 simulator code module that attempts to implement the RHPMAN scheme and reproduce its performance evaluation as described by the following paper:

This repository is a continuation of the work started by Keefer Rourke to complete the implementation.

⁠Motivation

Our lab^1⁠ is investigating ad-hoc mobile mesh networks (MANETs) and their properties with the hopes that we may inform development of quality mesh network protocols and network applications. A challenge with MANETs is their inherently mobile nature. Much research has been done to discover good algorithms for data distribution and replication within MANETs, however many of these studies are unreproducible as-is.

Having identified the RHPMAN scheme as described by Shi and Chen 2014 as a promising data replication scheme, this project was created to attempt to implement it on the ns-3 simulator⁠, and run the scheme under a similar setting as is described in the performance evaluation conducted by Shi and Chen.

Note: Shi and Chen used the OPNET simulator for their study, however this simulator does not appear to be widely available anymore. Hence, we have chosen to use the latest version of the popular ns-3 network simulator instead.

⁠Building this project

Reproducibility is key in simulation studies, so here's how to build the project!

1. This module makes use of [Google protocol buffers] for the network serialization install the protoc code generator for C++ on your system. instructions⁠

2. Make sure that you have a C++ compiler that has support for at least c++11, and all of the dependencies to install ns-3 installed on your system (see https://www.nsnam.org/wiki/Installation⁠ for ns-3 installation instructions)

3. Download and build copy of the ns-3.32 all-in-one distribution.

   wget https://www.nsnam.org/release/ns-allinone-3.32.tar.bz2
   tar xjvf ns-allinone-3.32.tar.bz2
   cd ns-allinone-3.32
   python3 ./build.py --enable-examples --enable-tests
   

   Copy

4. Change directories to the contrib/ folder of the ns-3.32 source distribution.

   cd ns-3.32/contrib/
   

   Copy

5. Clone this repository.

   git clone [email protected]:marshallasch/rhpman.git
   

   Copy

6. Change directory back to the ns-3.32 folder of the source distribution and re configure the module through the waf tool.

cd ..
./waf configure --enable-tests --enable-examples

1. Change directory back to the ns-3.32 folder of the source distribution and run this simulation through the waf tool. This will compile the simulation code and start executing the code.

cd ..
./waf --run 'rhpman-example'

⁠Running the simulation

If you're familiar with ns-3, then you should know that the simulation is run via the waf build tool. Arguments to this program must be part of the same string that is passed to ./waf --run (that's just how it works :shrug:).

Every parameter of the simulation is configurable. Run the following to see all the configurable parameters. The default values are as described in the RHPMAN paper cited at the top of this document.

./waf --run 'rhpman-example --printHelp'  # <-- mind the quotes!

You can view an animation of the simulation using NetAnim, which is included with the ns-3 all-in-one distribution. To do so, run the following:

./waf --run 'rhpman-example --animation-xml=path/to/rhpman.xml

This will generate an XML file at the specified path. You can then open this file with NetAnim to view what happens during the simulation run.

⁠Building the container

$ docker build \
         --build-arg VCS_REF=$(git rev-parse -q --verify HEAD) \
         --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
         --build-arg BUILD_PROFILE=debug \
         -t marshallasch/rhpman:latest .

The build variant can be configured using the BUILD_PROFILE build-arg, it can be set to either debug, release, or optimized. It is set to debug by default.

⁠Running the container

For convenience this simulation experiment has also been packaged as a prebuilt docker image so that you do not need to install any of the dependencies or compile the simulator yourself.

There are two ways that the docker container can be used:

1. to run ns-3 simulations directly
2. to get a bash shell in a ns-3 installation

⁠Interactive bash terminal

The interactive shell will put you in the ns-3 root directory. Depending on which docker image tag is used ns-3 can either be built in debug mode or optimized mode. Then the ./waf command can be run manually.

docker run --rm -it marshallasch/rhpman:optimized bash

⁠To run ns-3 simulations

If anything other than bash is given as the command to the Docker container then the command will be passed to ./waf --run "rhpman-example <command>" to run a simulation using the flags.

docker run --rm marshallasch/rhpman:optimized --printHelp

⁠Code style

This project is formatted according to the .clang-format file included in this repository. It intentionally deviates from the code style used by the ns-3 library and simulator developers.

⁠Important assumptions

This MUST be run only on IPv4 based networks, the node ID that is used is a 32 bit identifier that is equal to the IPv4 address of the node. This ID is used to communicate and assign the nodes as replica holder nodes. This could be modified to use IPv6 addresses by using a 128 bit value instead.

⁠License

While ns-3 is itself licensed under the GNU General Public License v2, the code in this repository is made available under the Internet Systems Consortium (ISC) License.

A copy of this license is included in this repository, and embedded in the top of each source file.