blob: be27f0b204446334554658080d411d6b9a829e18 [file] [log] [blame]
Alexander Afanasyev4d325162012-06-01 12:28:50 -07001Examples
2========
3
Alexander Afanasyev6cf83432013-02-15 16:02:04 -08004.. role:: red
5
6.. note::
7 :red:`!!! This page only shows up examples of how to config topology and perform basic operations in ndnSIM (an example equivalent to "Hello, world1") !!! These are **NOT** examples of real experimentations (just like "Hello, world!" is not a real program).`
8
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -07009.. _simple-scenario:
10
Alexander Afanasyev4d325162012-06-01 12:28:50 -070011Simple scenario
12---------------
13
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070014The first example (``ndn-simple.cc``) shows very basics of ndnSIM. In the simulated
Alexander Afanasyev4d325162012-06-01 12:28:50 -070015topology there are 3 nodes, connected with point-to-point links, one
Alexander Afanasyev07b00632012-06-01 23:46:47 -070016NDN consumer, and one NDN producer:
Alexander Afanasyev4d325162012-06-01 12:28:50 -070017
Alexander Afanasyev07b00632012-06-01 23:46:47 -070018.. aafig::
19 :aspect: 60
20 :scale: 120
Alexander Afanasyev4d325162012-06-01 12:28:50 -070021
Alexander Afanasyev07b00632012-06-01 23:46:47 -070022 +----------+ +--------+ +----------+
23 | | 1Mbps | | 1Mbps | |
24 | Consumer |<-------------->| Router |<-------------->| Producer |
25 | | 10ms | | 10ms | |
26 +----------+ +--------+ +----------+
Alexander Afanasyev4d325162012-06-01 12:28:50 -070027
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070028Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests towards the producer
Alexander Afanasyev07b00632012-06-01 23:46:47 -070029with frequency of 10 Interests per second (see :doc:`applications`).
30
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070031Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming Interests with virtual payload data (1024 bytes).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070032
33FIB on every node is populated using default routes (see :doc:`helpers`).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070034
35The following code represents all that is necessary to run such a
36simple scenario
37
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080038.. literalinclude:: ../../examples/ndn-simple.cc
39 :language: c++
40 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080041 :lines: 20-27,48-
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080042 :emphasize-lines: 30-33,37-49
Alexander Afanasyev07b00632012-06-01 23:46:47 -070043
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070044If this code is placed into ``scratch/ndn-simple.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
Alexander Afanasyev07b00632012-06-01 23:46:47 -070045simulation using the following command (in optimized mode nothing will be printed out)::
46
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070047 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
Alexander Afanasyev07b00632012-06-01 23:46:47 -070048
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -070049.. _9-node-grid-example:
Alexander Afanasyev6cf83432013-02-15 16:02:04 -080050
Alexander Afanasyev07b00632012-06-01 23:46:47 -0700519-node grid example
52-------------------
53
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080054This scenario (``ndn-grid.cc``) simulates a grid topology, which is constructed using PointToPointLayout NS-3 module
Alexander Afanasyev07b00632012-06-01 23:46:47 -070055
56.. aafig::
57 :aspect: 60
58 :scale: 120
59
60 /--------\ /-\ /-\
61 |Consumer|<---->| |<------->| |
62 \--------/ \-/ \-/
63 ^ ^ ^
64 | | | 1Mbps/10ms delay
65 v v v
66 /-\ /-\ /-\
67 | |<-------->| |<------->| |
68 \-/ \-/ \-/
69 ^ ^ ^
70 | | |
71 v v v
72 /-\ /-\ /--------\
73 | |<-------->| |<---->|Producer|
74 \-/ \-/ \--------/
75
76
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070077FIB is populated using :ndnsim:`GlobalRoutingHelper` (see :doc:`helpers`).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070078
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070079Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests towards the producer
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080080with frequency of 100 interests per second (see :doc:`applications`).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070081
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070082Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming Interests with virtual payload data (1024 bytes).
Alexander Afanasyev07b00632012-06-01 23:46:47 -070083
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080084The following code represents all that is necessary to run such a simple scenario
Alexander Afanasyev07b00632012-06-01 23:46:47 -070085
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -080086.. literalinclude:: ../../examples/ndn-grid.cc
87 :language: c++
88 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080089 :lines: 20-27,53-
90 :emphasize-lines: 28,31-33,35-38,53-57
Alexander Afanasyev6cf83432013-02-15 16:02:04 -080091
Alexander Afanasyev4d325162012-06-01 12:28:50 -070092
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070093If this code is placed into ``scratch/ndn-grid.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
Alexander Afanasyev07b00632012-06-01 23:46:47 -070094simulation using the following command (in optimized mode nothing will be printed out)::
95
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070096 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid
Alexander Afanasyev07b00632012-06-01 23:46:47 -070097
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -070098.. _9-node-grid-example-using-topology-plugin:
99
1009-node grid example using topology plugin
101-----------------------------------------
102
103Instead of defining topology directly as in :ref:`simple-scenario` or using specialized helpers as in :ref:`9-node-grid-example`, ndnSIM provides experimental extended versions of TopologyReader classes: :ndnsim:`AnnotatedTopologyReader` and :ndnsim:`RocketfuelWeightsReader`.
104
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800105While :ndnsim:`RocketfuelWeightsReader` is a specialized version intended to be used with `Rocketfuel <http://www.cs.washington.edu/research/networking/rocketfuel/>`_ topology and link weights files (examples will be provided later), :ndnsim:`AnnotatedTopologyReader` is a more general-use class that uses simple user-readable format.
106
107:ndnsim:`AnnotatedTopologyReader` expects the following format:
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700108
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800109.. literalinclude:: ../../examples/topologies/topo-grid-3x3.txt
110 :language: bash
111 :linenos:
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800112 :lines: 1-2,19-
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800113 :emphasize-lines: 8,24
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700114
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800115
116This scenario (``ndn-grid-topo-plugin.cc``) duplicates the functionality of :ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`.
117
118.. aafig::
119 :aspect: 60
120 :scale: 120
121
122 /--------\ /-\ /-\
123 |Consumer|<---->| |<------->| |
124 \--------/ \-/ \-/
125 ^ ^ ^
126 | | | 1Mbps/10ms delay
127 v v v
128 /-\ /-\ /-\
129 | |<-------->| |<------->| |
130 \-/ \-/ \-/
131 ^ ^ ^
132 | | |
133 v v v
134 /-\ /-\ /--------\
135 | |<-------->| |<---->|Producer|
136 \-/ \-/ \--------/
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700137
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800138.. literalinclude:: ../../examples/ndn-grid-topo-plugin.cc
139 :language: c++
140 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800141 :lines: 20-26,51-
142 :emphasize-lines: 14-16,20,27-30
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800143
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700144As you can see, scenario code became more compact and more readable.
145
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800146:ndnsim:`AnnotatedTopologyReader` provides two ways to access topology nodes.
Alexander Afanasyev6dbacda2012-10-23 17:20:18 -0700147First, you can use the method :ndnsim:`AnnotatedTopologyReader::GetNodes` which returns NodeContainer.
148
149Alternatively, nodes can be accessed by name using `Names::Find<Node> ("nodename")` call, as in the above example.
150For this purpose,:ndnsim:`AnnotatedTopologyReader` automatically registers all created nodes with names specified in topology file.
151For more information about `Names` class, please refer to `NS-3 documentation <.. http://www.nsnam.org/doxygen/classns3_1_1_names.html>`_
152.
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800153
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800154If the topology file is placed into ``src/ndnSIM/examples/topologies/topo-grid-3x3.txt`` and the code is placed into ``scratch/ndn-grid-topo-plugin.cc``, you can run and see progress of the simulation using the following command (in optimized mode nothing will be printed out)::
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800155
156 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-topo-plugin
157
158
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -08001596-node bottleneck topology
160--------------------------
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800161
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800162This scenario (``ndn-congestion-topo-plugin.cc``) can be used for congestion-related scenarios
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800163
164.. aafig::
165 :aspect: 60
166 :scale: 120
167
168 /------\ /------\
169 | Src1 |<--+ +-->| Dst1 |
170 \------/ \ / \------/
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800171 \ /
172 +-->/------\ "bottleneck" /------\<-+
173 | Rtr1 |<===============>| Rtr2 |
174 +-->\------/ \------/<-+
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800175 / \
176 /------\ / \ /------\
177 | Src2 |<--+ +-->| Dst2 |
178 \------/ \------/
179
180.. literalinclude:: ../../examples/topologies/topo-6-node.txt
181 :language: bash
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800182 :linenos:
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800183 :lines: 1-2,15-
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800184 :emphasize-lines: 3,13
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800185
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800186.. literalinclude:: ../../examples/ndn-congestion-topo-plugin.cc
187 :language: c++
188 :linenos:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800189 :lines: 20-26,47-
190 :emphasize-lines: 15,21-22,29-34,41-47,52-62
Alexander Afanasyevaa1c4c32012-11-21 16:17:03 -0800191
192.. :lines: 20-25,53-
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800193
194To run this scenario and see what is happening, use the following command::
195
196 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-topo-plugin
197
198.. _11-node 2-bottleneck topology with custom forwarding strategy:
199
20011-node 2-bottleneck topology with custom forwarding strategy
201-------------------------------------------------------------
202
203To effectively use the example :ref:`custom strategy <Writing your own custom strategy>`, we need to make sure that FIB entries contain at least two entries.
204In the current version of ndnSIM, this can be accomplished using manual route configuration.
205
206The following example illustrates how the strategy can be used in simulation scenario.
207
208Let us first define a meaningful topology:
209
210.. aafig::
211 :aspect: 60
212 :scale: 120
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800213
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800214 /------\ 0 0 /------\
215 | c1 |<-----+ +----->| p1 |
216 \------/ \ / \------/
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800217 \ /-----\ /
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800218 /------\ 0 \ +==>| r12 |<==+ / 0 /------\
219 | c2 |<--+ \ / \-----/ \ / +-->| p2 |
220 \------/ \ \ | | / / \------/
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800221 \ | | 1Mbps links | | /
222 \ 1 v0 v5 1v 2v 3 /
223 +->/------\ /------\<-+
224 2| r1 |<===============>| r2 |4
225 +->\------/4 0\------/<-+
226 / 3^ ^5 \
227 / | | \
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800228 /------\ 0 / / \ \ 0 /------\
229 | c3 |<--+ / \ +-->| p3 |
230 \------/ / \ \------/
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800231 / "All consumer-router and" \
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800232 /------\ 0 / "router-producer links are" \ 0 /------\
233 | c4 |<-----+ "10Mbps" +---->| p4 |
234 \------/ \------/
Alexander Afanasyev6cf83432013-02-15 16:02:04 -0800235
Alexander Afanasyeve97c6072012-11-21 23:51:12 -0800236 "Numbers near nodes denote face IDs. Face ID is assigned based on the order of link"
237 "definitions in the topology file"
238
239The corresponding topology file (``topo-11-node-two-bottlenecks.txt``):
240
241.. literalinclude:: ../../examples/topologies/topo-11-node-two-bottlenecks.txt
242 :language: bash
243 :linenos:
244 :lines: 1-2,28-
245
246Example simulation (``ndn-congestion-alt-topo-plugin.cc``) scenario that utilizes CustomStrategy forwarding strategy:
247
248.. literalinclude:: ../../examples/ndn-congestion-alt-topo-plugin.cc
249 :language: c++
250 :linenos:
251 :lines: 21-28,61-
252 :emphasize-lines: 16,21,49-50,65-79
253
254
255To run this scenario and see what is happening, use the following command::
256
257 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-alt-topo-plugin
258
259You can also run using visualizer module to verify that both bottleneck links are utilized::
260
261 ./waf --run=ndn-congestion-alt-topo-plugin --visualize
Alexander Afanasyev59314802012-11-26 14:56:04 -0800262
Alexander Afanasyevf4a03592012-12-10 16:12:34 -08002633-level binary tree with packet-level trace helpers
264---------------------------------------------------
Alexander Afanasyev59314802012-11-26 14:56:04 -0800265
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -0800266:ref:`packet trace helper example`
Alexander Afanasyev59314802012-11-26 14:56:04 -0800267
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800268
2693-level binary tree with content store trace helper
270---------------------------------------------------
271
Alexander Afanasyevdb64ff12013-01-18 16:37:31 -0800272:ref:`cs trace helper example`
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800273
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800274
Alexander Afanasyev27e365b2013-01-18 18:03:43 -08002753-level binary tree with application-level Interest-Data delay tracer
276----------------------------------------------------------------------
277
278:ref:`app delay trace helper example`
279
280
Alexander Afanasyev71278d42012-12-12 19:16:54 -08002813-node topology with Content Store respecting freshness field of ContentObjects
282-------------------------------------------------------------------------------
283
284:ref:`Content Store respecting freshness field of ContentObjects`
285
2861-node topology with custom application
287---------------------------------------
288
289:ref:`Custom applications`
290
Alexander Afanasyev1ab1aad2013-02-28 11:32:21 -0800291Simple scenario with pcap dump
292------------------------------
293
294The following example (``ndn-simple-with-pcap.cc``) demonstrates how to dump all simulated traffic
295in pcap-formatted data, which can be used for later analysis by conventional tools, like tcpdump and wireshark.
296
297.. literalinclude:: ../../examples/ndn-simple-with-pcap.cc
298 :language: c++
299 :linenos:
300 :lines: 20-
301 :emphasize-lines: 7-29,70-72
302
303If this code is placed into ``scratch/ndn-simple-with-pcap.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
304simulation using the following command (in optimized mode nothing will be printed out)::
305
306 NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple-with-pcap
307
308This will generate ``ndn-simple-trace.pcap``, which can be fed to tcpdump::
309
310 tcpdump -r ndn-simple-trace.pcap
Alexander Afanasyevb99cb6c2013-03-12 13:58:30 -0700311
Alexander Afanasyev27370c52013-03-12 13:54:08 -070031225-node tree topology with L2Tracer
313-----------------------------------
314
315:ref:`Example of packet drop tracer (L2Tracer)`
Alexander Afanasyevb5e77d82013-04-10 15:55:26 -0700316
3173-node topology with periodic tracing of PIT
318--------------------------------------------
319
320:ref:`periodic tracing of Pending Interest Table (PIT) size`