3 ns-3 as a SimGrid model
4 #######################
6 You can use the well-known `ns-3 packet-level network simulator
7 <http://www.nsnam.org>`_ as a SimGrid model, for example to investigate the
8 validity of your simulation. Just install ns-3 and recompile SimGrid
11 Compiling the ns-3/SimGrid binding
12 **********************************
17 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
18 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
19 don't have the ns-3 bindings activated, you can still use the packaged version
20 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
21 install ns-3 from scratch as follows:
26 wget http://www.nsnam.org/release/ns-allinone-3.29.tar.bz2
27 tar -xf ns-allinone-3.29.tar.bz2
28 cd ns-allinone-3.29/ns-3.29/
29 # Configure, build and install
30 ./waf configure --prefix="/opt/ns3" # or give another path if you prefer
34 For more information, please refer to the ns-3 documentation
35 (`official website <http://www.nsnam.org>`_).
37 Enabling ns-3 in SimGrid
38 ========================
40 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
41 Optionally, use ``NS3_HINT`` to hint cmake about where to find ns-3.
45 cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
47 By the end of the configuration, cmake reports whether ns-3 was found,
48 and this information is also available in ``include/simgrid/config.h``
49 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
50 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
51 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
53 Test your installation after compilation as follows:
62 If you use a version of ns-3 that is not known to SimGrid yet, edit
63 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
64 comments on top of this file. Conversely, if something goes wrong with an old
65 version of either SimGrid or ns-3, try upgrading everything.
69 Using ns-3 from SimGrid
70 ***********************
72 The SimGrid/ns-3 binding only contains features that are common to both
73 systems: ns-3 wireless models are not available, while SimGrid routes
74 cannot be longer than 1. Also, the platform built in ns-3 from the
75 SimGrid description is very basic.
77 Platform files compatibility
78 ============================
80 Any route longer than one will be ignored when using ns-3. They are
81 harmless, but you still need to connect your hosts using one-hop routes.
82 The best solution is to add routers to split your route. Here is an
83 example of invalid platform:
88 <host id="alice" speed="1Gf" />
89 <host id="bob" speed="1Gf" />
91 <link id="l1" bw="1Mbps" />
92 <link id="l2" bw="1Mbps" />
94 <route src="alice" dst="bob">
95 <link_ctn id="l1"/> <!-- !!!! INVALID WITH ns-3 !!!! -->
96 <link_ctn id="l2"/> <!-- !!!! length=2 IS TOO MUCH !!!! -->
100 This can be reformulated as follows to make it usable with the ns-3 binding.
101 There is no direct connection from alice to bob, but that's OK because
102 ns-3 automatically routes from point to point.
104 .. code-block:: shell
107 <host id="alice" speed="1Gf" />
108 <host id="bob" speed="1Gf" />
110 <router id="r1" /> <!-- routers are compute-less hosts -->
112 <link id="l1" bw="1Mbps" />
113 <link id="l2" bw="1Mbps" />
115 <route src="alice" dst="r1">
119 <route src="r1" dst="bob">
124 Once your platform is OK, just change the :ref:`network/model
125 <options_model_select>` configuration option to "ns-3" as follows. The rest
128 .. code-block:: shell
130 ./network-ns3 --cfg=network/model:ns-3 (other parameters)
132 Many other files from the ``examples/platform directory`` are usable with the
133 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
134 Check the file `examples/deprecated/msg/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/deprecated/msg/network-ns3/network-ns3.tesh>`_
135 to see which ones are used in our regression tests.
140 A ns-3 platform is automatically created from the provided SimGrid
141 platform. However, there are some known caveats:
143 * The default values (e.g., TCP parameters) are the ns-3 default values.
144 * ns-3 networks are routed using the shortest path algorithm, using
145 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
146 * End hosts cannot have more than one interface card. So, your
147 SimGrid hosts should be connected to the platform through only
148 one link. Otherwise, your SimGrid host will be considered as a
151 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
152 as possible. If the current state does not fit your needs, you should modify
153 this plugin, and/or create your own plugin from the existing one. If you come up
154 with interesting improvements, please contribute them back
159 If your simulation hangs in a communication, this is probably because one host
160 is sending data that is not routable in your platform. Make sure that you only
161 use routes of length 1, and that any host is connected to the platform.
162 Arguably, SimGrid could detect this situation and report it, but unfortunately,
163 this is still to be done.