\section pls_simgrid_configuration_ns3 Using NS3
-It is possible to use discrete-event network simulator <a href="http://www.nsnam.org/">(ns-3)</a> for Internet systems
-instead of the default one.
+You may want to replace the SimGrid network models by the ones of the
+well known packet-level network simulator <a href="http://www.nsnam.org/">NS-3</a> instead.
+This section explains how to do so.
-A ns-3 platform is created according to the platform file you provide in SimGrid format. However from this configuration, we had to set up some extra parameters :
+\subsection pls_simgrid_configuration_ns3_install Installing NS3
-<ul>
-<li>
-First, whenever possible, we let default ns3 values and we don't changed it ; in case you have doubts on values for those parameters (TCP parameters for example), blame ns-3...
-</li>
-
-<li>
-Second, routing used inside ns-3 is a global and static one, relying on a shortest path algorithm. We did so by using ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.
-</li>
-
-<li>
-Third, we also choose to restrict the way your platform is built : end hosts cannot have more than one interface card (so, only one <link> in your SimGrid platform should link
-an end host to the platform ; if not, your end host will be considered as a router.
-</li>
-
-</ul>
-<i>
-To use ns3 model inside SimGrid you have to install at least the version 3.10 of ns3 simulator.
-</i>
-
-- <b>Download and enter the lateast release (here the 3.12.1)</b>
+The easiest is to install it with the package manager. Under
+Debian/Ubuntu, simply type as root:
\verbatim
-http://www.nsnam.org/release/ns-allinone-3.12.1.tar.bz2
-tar -xf ns-allinone-3.12.1.tar.bz2
-cd ns-allinone-3.12.1/ns-3.12.1/
+apt-get install libns3-dev ns3
\endverbatim
-- <b>Configure, make and install ns3</b>
+You can also install it from scratch with the following commands:
\verbatim
+# Download the source
+wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2
+tar -xf ns-allinone-3.22.tar.bz2
+cd ns-allinone-3.22/ns-3.22/
+# Configure, build and install
./waf configure --prefix="ns-3_install_directory"
./waf
./waf install
\endverbatim
-After install ns-3 you should have directories into your "ns-3_install_directory":
- \li include/ns3/
- \li lib/
- \li bin/ (with 3.12)
+For more information, please refer to the NS-3 documentation.
-In some cases, include/ns3 does not exist, but there is an /include/ns3.XX . Then, a simple symbolic link is enough. From the /path/to/ns3/installation/include directory, run:
-\verbatim
-ln -s -T ns3.XX/ns3 ns3
-\endverbatim
-
-Make sure to replace 3.XX with your version of NS3, e.g., 3.17, or 3.18.
-Check the correct presence of the symbolic link using
-\verbatim
-ls -al
-\endverbatim
-
-and you should see an ns3 link pointing to ns3.XX. E.g., ns3 -> ns3.17/ns3
-You also need to add to the LD_LIBRARY_PATH : "ns-3_install_directory/lib".
+\subsection pls_simgrid_configuration_ns3_config Enabling SimGrid's support for NS3
-- <b>Enable ns-3 support on SimGrid</b>
-
-Enabling ns-3 integration with Simgrid requires several intermediate steps.
--# Modify "simgrid_path/buildtools/CMake/MakeLib.cmake".\n
-The "-lns3.${NS3_VERSION_MINOR}-[module]" should match the library names in your "ns-3_install_directory/lib". The "module" can be one of the following: core, csma, point-to-oint, internet, applications, bridge, mpi, config-store, stats, network. For this, in the "MakeLib.cmake" file find the "else" branch of "if(HAVE_NS3)" statement. Replace the se of "-lns3.${NS3_VERSION_MINOR}-[module]" with "-lns3[version]-[module]-debug" in "SET(SIMGRID_DEP)". On the same branch, add "-I/path/to/ns-3_install_directory/include" to MAKE_C_FLAGS and "CMAKE_CXX_FLAGS".
--# There might be a need for creating symbolic links of each ns3 library from "ns-3_install_directory/lib" to "/usr/lib".
--# In order to enable ns-3 with simgrid you have to give where is ns-3 to the simgrid configuration command. (path to \<ns3_path\>/lib and \<ns3_path\>/include)
+Normally, you just have to enable NS3 in ccmake or cmake as follows.
+If you installed NS3 in a regular path, just drop the ns3_path
+configuration item.
\verbatim
cmake . -Denable_ns3=ON -Dns3_path=<ns3_path>
\endverbatim
-With the output of the configuration you can see if ns-3 is detected (see CFlags: ; CPPFlags: ; Compile NS-3: , NS-3 path:).
+By the end of the configuration, cmake reports whether NS-3 was found.
+You can also double-check by executing the tests after the compilation.
\verbatim
-Configuration of package `simgrid' on arch (=4):
- BUILDNAME : UNIX
- SITE : Linux_2.6.38-11-generic_x86_64
- Release : simgrid-3.6.1
-
- Compiler: c++ : /usr/bin/c++
- version: 4.6.1
- Compiler: c : /usr/bin/gcc
- version: 4.6.1
-
- CFlags : -O3 -finline-functions -funroll-loops -fno-strict-aliasing -L/usr/lib/x86_64-linux-gnu -I/usr/include
- -L/home/navarrop/Install/ns3-3.10/lib -I/home/navarrop/Install/ns3-3.10/include -g3 -D_NS3_3_10
- CPPFlags: -I/home/navarrop/Install/ns3-3.10/include -L/home/navarrop/Install/ns3-3.10/lib
-
- Compile Gtnets : 0
- Compile NS-3 : 1 ---------------------> Be sure this option is "1" otherwise ns-3 is not activated
- Gtnets path :
- NS-3 path : /home/navarrop/Install/ns3-3.10
- Compile Lua :
- Compile Smpi : OFF
- Compile Static : OFF
-
- Maintainer mode: OFF
- Supernovae mode: OFF
- Model checking : OFF
- Tracing mode : OFF
- Jedule mode : OFF
- Latency bound : OFF
- Graphviz mode :
-
- Simgrid dependencies: -lm -lpthread -lns3 -lrt
- Smpi dependencies :
-
- INSTALL_PREFIX: /usr/local
--- Configuring done
--- Generating done
--- Build files have been written to: /home/navarrop/workspace/simgrid/build
+$ ctest -R ns3
+(several tests should be run)
\endverbatim
-Now you can compile SimGrid
-\verbatim
-make
-\endverbatim
+If you have a NS3 version that is not known (yet) to SimGrid, the
+detection may fail. In that case, edit the file
+buildtools/Cmake/Modules/FindNS3.cmake in your SimGrid tree. The
+required changes are very easy, and documented at the beginning of
+this file.
-Then you can see if ns-3 is well activated by testing
-\verbatim
-ctest -R ns3
-\endverbatim
+If the compilation fails when linking the library because of some .a
+file that cannot be used dynamically, that's probably because you only
+installed the libns3-dev library on your Debian, where you also need
+libns3-3. That's probably a bug of the libns3-dev package that should
+depend on the dynamic libraries corresponding to its .so files.
-You should see
-\verbatim
- Start 182: msg-ns3-thread
-1/3 Test #182: msg-ns3-thread ................... Passed 0.35 sec
- Start 183: msg-ns3-ucontext
-2/3 Test #183: msg-ns3-ucontext ................. Passed 0.22 sec
- Start 184: msg-ns3-raw
-3/3 Test #184: msg-ns3-raw ...................... Passed 0.23 sec
-\endverbatim
+\subsection pls_simgrid_configuration_ns3_use Using NS3 from SimGrid
-- <b>Use case</b>
+A working example of NS3/SimGrid interactions can be found in
+examples/msg/ns3. Basically, you just have to run your SimGrid
+simulation with the configuration option "network/model" set to the
+value "NS3". The rest remains unchanged.
-An example of using Simgrid with NS3 can be found in:
+The following should work from the examples/msg/ns3 folder (ns3 here
+is the name of our example binary).
\verbatim
-path/to/simgrid/examples/src/surf/ns3/
+./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
\endverbatim
-From the example folder above, the command line sintax is
+A ns-3 platform is automatically created from the SimGrid platform
+file that you will provide. There is some caveats to know:
-\verbatim
-<simgrid_executable> <platform description file> <deployment file> --cfg=network/model:NS3 --log=surf.threshold:info
-\endverbatim
+<ul>
+ <li>The default values (e.g., TCP parameters) are the ns3
+ values. Don't blame us for them.</li>
+
+ <li>NS3 networks are routed using the shortest path algorithm, using
+ ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
+
+ <li>End hosts cannot have more than one interface card (so, only one
+ <link> in your SimGrid platform should link an end host to
+ the platform ; if not, your end host will be considered as a
+ router. </li>
+</ul>
-This example should work:
-\verbatim
-./ns3 ./3hosts_2links_p.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
-\endverbatim
More about ns-3 simulator <a href="http://www.nsnam.org/">(Official website)</a>
