ns-3 as a SimGrid model¶
You can use the well-known ns-3 packet-level network simulator as a SimGrid model, for example to investigate the validity of your simulation. Just install ns-3 and recompile SimGrid accordingly.
Compiling the ns-3/SimGrid binding¶
SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
recent version of both SimGrid and ns-3. While the Debian package of SimGrid
don’t have the ns-3 bindings activated, you can still use the packaged version
of ns-3 by grabbing the
libns3-dev ns3 packages. Alternatively, you can
install ns-3 from scratch as follows:
# Download the source wget http://www.nsnam.org/release/ns-allinone-3.29.tar.bz2 tar -xf ns-allinone-3.29.tar.bz2 cd ns-allinone-3.29/ns-3.29/ # Configure, build and install ./waf configure --prefix="/opt/ns3" # or give another path if you prefer ./waf ./waf install
For more information, please refer to the ns-3 documentation (official website).
Enabling ns-3 in SimGrid¶
SimGrid must be recompiled with the
enable_ns3 option activated in cmake.
NS3_HINT to hint cmake about where to find ns-3.
cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
By the end of the configuration, cmake reports whether ns-3 was found,
and this information is also available in
If your local copy defines the variable
SIMGRID_HAVE_NS3 to 1, then ns-3
was correctly detected. Otherwise, explore
CMakeFiles/CMakeError.log to diagnose the problem.
Test your installation after compilation as follows:
ctest -R ns3
If you use a version of ns-3 that is not known to SimGrid yet, edit
tools/cmake/Modules/FindNS3.cmake in your SimGrid tree, according to the
comments on top of this file. Conversely, if something goes wrong with an old
version of either SimGrid or ns-3, try upgrading everything.
Using ns-3 from SimGrid¶
The SimGrid/ns-3 binding only contains features that are common to both systems: ns-3 wireless models are not available, while SimGrid routes cannot be longer than 1. Also, the platform built in ns-3 from the SimGrid description is very basic.
Platform files compatibility¶
Any route longer than one will be ignored when using ns-3. They are harmless, but you still need to connect your hosts using one-hop routes. The best solution is to add routers to split your route. Here is an example of invalid platform:
<platform> <host id="alice" speed="1Gf" /> <host id="bob" speed="1Gf" /> <link id="l1" bw="1Mbps" /> <link id="l2" bw="1Mbps" /> <route src="alice" dst="bob"> <link_ctn id="l1"/> <!-- !!!! INVALID WITH ns-3 !!!! --> <link_ctn id="l2"/> <!-- !!!! length=2 IS TOO MUCH !!!! --> </route> </platform>
This can be reformulated as follows to make it usable with the ns-3 binding. There is no direct connexion from alice to bob, but that’s OK because ns-3 automatically routes from point to point.
<platform> <host id="alice" speed="1Gf" /> <host id="bob" speed="1Gf" /> <router id="r1" /> <!-- routers are compute-less hosts --> <link id="l1" bw="1Mbps" /> <link id="l2" bw="1Mbps" /> <route src="alice" dst="r1"> <link_ctn id="l1"/> </route> <route src="r1" dst="bob"> <link_ctn id="l2"/> </route> </platform>
Once your platform is OK, just change the network/model configuration option to “ns-3” as follows. The rest is unchanged.
./network-ns3 --cfg=network/model:ns-3 (other parameters)
Many other files from the
examples/platform directory are usable with the
ns-3 model, such as examples/platforms/dogbone.xml.
Check the file examples/deprecated/msg/network-ns3/network-ns3.tesh
to see which ones are used in our regression tests.
A ns-3 platform is automatically created from the provided SimGrid platform. However, there are some known caveats:
The default values (e.g., TCP parameters) are the ns-3 default values.
ns-3 networks are routed using the shortest path algorithm, using
End hosts cannot have more than one interface card. So, your SimGrid hosts should be connected to the platform through only one link. Otherwise, your SimGrid host will be considered as a router.
Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable) as possible. If the current state does not fit your needs, you should modify this plugin, and/or create your own plugin from the existing one. If you come up with interesting improvements, please contribute them back
If your simulation hangs in a communication, this is probably because one host is sending data that is not routable in your platform. Make sure that you only use routes of length 1, and that any host is connected to the platform. Arguably, SimGrid could detect this situation and report it, but unfortunately, this is still to be done.