Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
5022462a435f25575a898fa8c0f5db13c24f3c42
[simgrid.git] / doc / doxygen / ns3.doc
1 /*! \page pls_ns3 ns-3 as a SimGrid model
2
3 \tableofcontents
4
5 You can use the well-known 
6 <a href="http://www.nsnam.org/"><b>ns-3</b></a> packet-level network
7 simulator as a SimGrid model, for example to investigate the validity
8 of your simulation. Just install ns-3 and recompile SimGrid accordingly.
9
10 \section pls_ns3_install Installing ns-3
11
12 The easiest is to install it with the package manager. Under Debian/Ubuntu, simply type as root:
13
14 \verbatim
15 apt-get install libns3-dev ns3
16 \endverbatim
17
18 You can also install it from scratch with the following commands:
19
20 \verbatim
21 # Download the source
22 wget http://www.nsnam.org/release/ns-allinone-3.26.tar.bz2
23 tar -xf ns-allinone-3.26.tar.bz2
24 cd ns-allinone-3.26/ns-3.26/
25 # Configure, build and install
26 ./waf configure --prefix="/opt/ns3" # or give another path if you prefer
27 ./waf
28 ./waf install
29 \endverbatim
30
31 For more information, please refer to the ns-3 documentation
32 <a href="http://www.nsnam.org/">(official website)</a>.
33
34 \section pls_ns3_config Enabling SimGrid's support for ns-3
35
36 Normally, you just have to enable ns-3 in ccmake or cmake as
37 follows. If you installed ns-3 in a regular path, just drop the
38 NS3_HINT configuration item.
39
40 \verbatim
41 cmake . -Denable_ns3=ON -DNS3_HINT=/opt/ns3 # or change the path if needed
42 \endverbatim
43
44 By the end of the configuration, cmake reports whether ns-3 was found,
45 and this information is also available in <tt>include/simgrid_config.h</tt>
46 If your local copy defines the variable \c SIMGRID_HAVE_NS3 to 1, then NS3
47 was correctly detected. If it's defined to 0, then something went
48 wrong. Explore <tt>CMakeFiles/CMakeOutput.log</tt> and
49 <tt>CMakeFiles/CMakeError.log</tt> to diagnose the problem.
50
51 Afterward, you can test your installation as follows:
52
53 \verbatim
54 $ ctest -R ns3
55 \endverbatim
56
57 \subsection pls_ns3_config_trouble Troubleshooting
58
59 If you have a ns-3 version that is not known to SimGrid yet, edit \c
60 tools/cmake/Modules/FindNS3.cmake in your SimGrid tree, according to
61 the comments on top of this file.
62
63 If the compilation fails on Debian/Ubuntu when linking the library
64 because of some .a file that cannot be used dynamically, then you are
65 probably using a very old (and buggy) <tt>libns3-dev</tt>
66 package. Update it, or install <tt>libns3-3</tt> manually.
67
68 \section pls_ns3_use Using ns-3 from SimGrid
69
70 The SimGrid-ns3 binding only contains features that are common to both
71 systems: ns-3 wireless models are not available, while SimGrid routes
72 cannot be longer than 1. Also, the platform built in ns-3 from the
73 SimGrid description is very basic.
74
75 If your platform have longer routes, simply add some routers to break
76 these routes. SimGrid's routers are similar to hosts, without
77 computational abilities.
78
79 Once your platform is OK, just change the "network/model"
80 configuration option to "NS3". The rest remains unchanged.
81
82 The following should work from the examples/msg/network-ns3 folder,
83 where the \c network-ns3 binary example lives. 
84
85 \verbatim
86 ./network-ns3 ../../platforms/small_platform_one_link_routes.xml 3hosts_2links_d.xml --cfg=network/model:NS3 --log=root.threshold:info
87 \endverbatim
88
89 Many other files from the examples/platform directory are usable with
90 the ns-3 model. Check the file
91 examples/msg/network-ns3/network-ns3.tesh to see which ones are used
92 in our regression tests. You may also be interested in the
93 @ref msg_ex_ns3 "ns-3/SimGrid examples".
94
95 A ns-3 platform is automatically created from the provided SimGrid
96 platform. However, there are some known caveats:
97
98 <ul>
99
100   <li>The default values (e.g., TCP parameters) are the ns3 default
101       values.</li>
102
103   <li>ns-3 networks are routed using the shortest path algorithm, using
104       ns3::Ipv4GlobalRoutingHelper::PopulateRoutingTables.</li>
105
106   <li>End hosts cannot have more than one interface card. So, your
107       SimGrid hosts should be connected to the platform through only
108       one link. Otherwise, your SimGrid host will be considered as a
109       router.</li>
110
111 </ul>
112
113 Our goal is to keep the ns-3 plugin of SimGrid as easy (and hopefully
114 readable) as possible. If the current state does not fit your needs,
115 you should modify this plugin, and/or create your own plugin from the
116 existing one.
117
118 */