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 The SimGrid/ns-3 binding only contains features that are common to both systems.
12 Not all ns-3 models are available from SimGrid (only the TCP and WiFi ones are),
13 while not all SimGrid platform files can be used in conjunction ns-3 (routes
14 must be of length 1). Also, the platform built in ns-3 from the SimGrid
15 description is very basic. Finally, communicating from a host to
16 itself is forbidden in ns-3, so every such communication completes
17 immediately upon startup.
20 Compiling the ns-3/SimGrid binding
21 **********************************
26 SimGrid requires ns-3 version 3.26 or higher, and you probably want the most
27 recent version of both SimGrid and ns-3. While the Debian package of SimGrid
28 don't have the ns-3 bindings activated, you can still use the packaged version
29 of ns-3 by grabbing the ``libns3-dev ns3`` packages. Alternatively, you can
30 install ns-3 from scratch (see the `ns-3 documentation <http://www.nsnam.org>`_).
32 Enabling ns-3 in SimGrid
33 ========================
35 SimGrid must be recompiled with the ``enable_ns3`` option activated in cmake.
36 Optionally, use ``NS3_HINT`` to tell cmake where ns3 is installed on
41 cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
43 By the end of the configuration, cmake reports whether ns-3 was found,
44 and this information is also available in ``include/simgrid/config.h``
45 If your local copy defines the variable ``SIMGRID_HAVE_NS3`` to 1, then ns-3
46 was correctly detected. Otherwise, explore ``CMakeFiles/CMakeOutput.log`` and
47 ``CMakeFiles/CMakeError.log`` to diagnose the problem.
49 Test that ns-3 was successfully integrated with the following (from your SimGrid
50 build directory). It will run all SimGrid tests that are related to the ns-3
51 integration. If no test is run at all, you probably forgot to enable ns-3 in cmake.
60 If you use a version of ns-3 that is not known to SimGrid yet, edit
61 ``tools/cmake/Modules/FindNS3.cmake`` in your SimGrid tree, according to the
62 comments on top of this file. Conversely, if something goes wrong with an old
63 version of either SimGrid or ns-3, try upgrading everything.
67 Using ns-3 from SimGrid
68 ***********************
70 Platform files compatibility
71 ============================
73 Any route longer than one will be ignored when using ns-3. They are
74 harmless, but you still need to connect your hosts using one-hop routes.
75 The best solution is to add routers to split your route. Here is an
76 example of an invalid platform:
81 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
82 <platform version="4.1">
83 <zone id="zone0" routing="Floyd">
84 <host id="alice" speed="1Gf" />
85 <host id="bob" speed="1Gf" />
87 <link id="l1" bandwidth="1Mbps" latency="5ms" />
88 <link id="l2" bandwidth="1Mbps" latency="5ms" />
90 <route src="alice" dst="bob">
91 <link_ctn id="l1"/> <!-- !!!! IGNORED WHEN USED WITH ns-3 !!!! -->
92 <link_ctn id="l2"/> <!-- !!!! ROUTES MUST CONTAIN ONE LINK ONLY !!!! -->
97 This can be reformulated as follows to make it usable with the ns-3 binding.
98 There is no direct connection from alice to bob, but that's OK because ns-3
99 automatically routes from point to point (using
100 ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``).
104 <?xml version='1.0'?>
105 <!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
106 <platform version="4.1">
107 <zone id="zone0" routing="Full">
108 <host id="alice" speed="1Gf" />
109 <host id="bob" speed="1Gf" />
111 <router id="r1" /> <!-- routers are compute-less hosts -->
113 <link id="l1" bandwidth="1Mbps" latency="5ms"/>
114 <link id="l2" bandwidth="1Mbps" latency="5ms"/>
116 <route src="alice" dst="r1">
120 <route src="r1" dst="bob">
126 Once your platform is OK, just change the :ref:`network/model
127 <options_model_select>` configuration option to `ns-3` as follows. The other
128 options can be used as usual.
130 .. code-block:: shell
132 ./network-ns3 --cfg=network/model:ns-3 (other parameters)
134 Many other files from the ``examples/platform`` directory are usable with the
135 ns-3 model, such as `examples/platforms/dogbone.xml <https://framagit.org/simgrid/simgrid/tree/master/examples/platforms/dogbone.xml>`_.
136 Check the file `examples/cpp/network-ns3/network-ns3.tesh <https://framagit.org/simgrid/simgrid/tree/master/examples/cpp/network-ns3/network-ns3.tesh>`_
137 to see which ones are used in our regression tests.
142 In SimGrid, WiFi networks are modeled with WiFi zones, where a zone contains
143 the access point of the WiFi network and the hosts connected to it (called
144 station in the WiFi world). Links inside WiFi zones are modeled as regular
145 links with a specific attribute, and these links are then added to routes
146 between hosts. The main difference When using ns-3 WiFi networks is that
147 the network performance is not given by the link bandwidth and latency but
148 by the access point WiFi characteristics, and the distance between the access
151 So, to declare a new WiFi network, simply declare a zone with the ``WIFI``
156 <zone id="SSID_1" routing="WIFI">
158 Inside this zone you must declare which host or router will be the access point
163 <prop id="access_point" value="alice"/>
165 Afterward simply declare the hosts and routers inside the WiFi network. Remember
166 that one must have the same name as declared in the property "access point".
170 <router id="alice" speed="1Gf"/>
171 <host id="STA0-0" speed="1Gf"/>
172 <host id="STA0-1" speed="1Gf"/>
174 Finally, close the WiFi zone.
180 The WiFi zone may be connected to another zone using a traditional link and
181 a zoneRoute. Note that the connection between two zones is always wired.
185 <link id="wireline" bandwidth="100Mbps" latency="2ms" sharing_policy="SHARED"/>
187 <zoneRoute src="SSID_1" dst="SSID_2" gw_src="alice" gw_dst="bob">
188 <link_ctn id="wireline"/>
191 WiFi network performance
192 ^^^^^^^^^^^^^^^^^^^^^^^^
195 The performance of a wifi network is controlled by 3 property that can be added
196 to hosts connected to the wifi zone:
198 * ``mcs`` (`Modulation and Coding Scheme <https://en.wikipedia.org/wiki/Link_adaptation>`_)
199 Roughly speaking, it defines the speed at which the access point is
200 exchanging data with all stations. It depends on its model and configuration,
201 and the possible values are listed for example on Wikipedia.
202 |br| By default, ``mcs=3``.
203 It is a property of the WiFi zone.
204 * ``nss`` (Number of Spatial Streams, or `number of antennas <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Number_of_antennas>`_)
205 defines the amount of simultaneous data streams that the AP can sustain.
206 Not all value of MCS and NSS are valid nor compatible (cf. `802.11n standard <https://en.wikipedia.org/wiki/IEEE_802.11n-2009#Data_rates>`_).
207 |br| By default, ``nss=1``.
208 It is a property of the WiFi zone.
209 * ``wifi_distance`` is the distance from the station to the access point. Each
210 station can have a specific value.
211 |br| By default, ``wifi_distance=10``.
212 It is a property of stations of the WiFi network.
214 Here is an example of a zone changing ``mcs`` and ``nss`` values.
218 <zone id="SSID_1" routing="WIFI">
219 <prop id="access_point" value="alice"/>
220 <prop id="mcs" value="2"/>
221 <prop id="nss" value="2"/>
225 Here is an example of a host changing ``wifi_distance`` value.
229 <host id="STA0-0" speed="1Gf">
230 <prop id="wifi_distance" value="37"/>
233 Random Number Generator
234 =======================
236 It is possible to define a fixed or random seed to the ns3 random number
237 generator using the config tag.
241 <?xml version='1.0'?><!DOCTYPE platform SYSTEM "https://simgrid.org/simgrid.dtd">
242 <platform version="4.1">
244 <prop id = "network/model" value = "ns-3" />
245 <prop id = "ns3/seed" value = "time" />
250 The first property defines that this platform will be used with the ns3 model.
251 The second property defines the seed that will be used. Defined to ``time``
252 it will use a random seed, defined to a number it will use this number as
258 A ns-3 platform is automatically created from the provided SimGrid
259 platform. However, there are some known caveats:
261 * The default values (e.g., TCP parameters) are the ns-3 default values.
262 * ns-3 networks are routed using the shortest path algorithm, using ``ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables``.
263 * End hosts cannot have more than one interface card. So, your SimGrid hosts
264 should be connected to the platform through only one link. Otherwise, your
265 SimGrid host will be considered as a router (FIXME: is it still true?).
267 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully readable)
268 as possible. If the current state does not fit your needs, you should modify
269 this plugin, and/or create your own plugin from the existing one. If you come up
270 with interesting improvements, please contribute them back.
275 If your simulation hangs in a communication, this is probably because one host
276 is sending data that is not routable in your platform. Make sure that you only
277 use routes of length 1, and that any host is connected to the platform.
278 Arguably, SimGrid could detect this situation and report it, but unfortunately,
279 this is still to be done.