blob: a1f88f8de23706d4406b44185950e6d779bd09d5 [file] [log] [blame]
Alexander Afanasyev6315ef72012-06-01 20:56:31 -07001ndnSIM helpers
2==============
3
4Helpers are very important components of ndnSIM, especially for writing simulation scenarios.
5The following summarizes helpers and their basic usage.
6
Alexander Afanasyevf6807a52012-08-10 18:11:43 -07007StackHelper
Alexander Afanasyev6315ef72012-06-01 20:56:31 -07008---------------
9
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070010:ndnsim:`StackHelper` is used to install ndnSIM network stack on requested nodes, as well to provide a simple way configure several important parameters of NDN simulation.
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070011
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080012Example:
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070013
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080014.. code-block:: c++
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070015
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080016 ndn::StackHelper ndnHelper;
17 NodeContainer nodes;
18 ...
19 ndnHelper.Install (nodes);
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070020
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080021Routing
22+++++++
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070023
Alexander Afanasyeve6852122013-01-21 11:54:47 -080024All forwarding strategies require knowledge of where Interests can be forwarded (Forwarding Information Base).
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080025Unlike IP routing, this knowledge may be imprecise, but without such knowledge forwarding strategies will not be able to make any decision and will drop any Interests.
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070026
27.. note::
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080028 By default, all nodes have empty FIB. You need either to manually configure routes, use global routing controller, or (not recommended) enable default routes.
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070029
30Manually routes
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080031^^^^^^^^^^^^^^^
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070032
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070033Routes can be configured manually using :ndnsim:`StackHelper::AddRoute` static methods of :ndnsim:`StackHelper`.
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070034
35These routes **should** be created **after** installing NDN stack on a node:
36
37 .. code-block:: c++
38
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070039 ndnHelper.Install (nodes);
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070040 ...
41 Ptr<Node> node = ... // FIB entry will be added to FIB on this node
42 std::string prefix = ... // some prefix
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070043 Ptr<ndn::Face> face = ... // NDN face that belongs to the node and through which prefix is accessible
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070044 int32_t metric = ... // some routing metric
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070045 ndn::StackHelper::AddRoute (node, prefix, face, metric);
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070046
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080047Global routing controller
48^^^^^^^^^^^^^^^^^^^^^^^^^
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070049
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070050To simplify FIB management in large topologies, ndnSIM contains a global routing controller (:ndnsim:`helper <GlobalRoutingHelper>` and :ndnsim:`special interface <GlobalRouter>`), similar in spirit to ``Ipv4GlobalRoutingHelper``.
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070051
52There are several necessary steps, in order to take advantage of the global routing controller:
53
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070054* install :ndnsim:`special interfaces <GlobalRouter>` on nodes
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070055
56 .. code-block:: c++
Alexander Afanasyeve6852122013-01-21 11:54:47 -080057
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070058 NodeContainer nodes;
59 ...
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070060 ndn::GlobalRoutingHelper ndnGlobalRoutingHelper;
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070061 ndnGlobalRoutingHelper.Install (nodes);
Alexander Afanasyeve6852122013-01-21 11:54:47 -080062
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070063* specify which node exports which prefix using :ndnsim:`GlobalRoutingHelper::AddOrigins`
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070064
65 .. code-block:: c++
Alexander Afanasyeve6852122013-01-21 11:54:47 -080066
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070067 Ptr<Node> producer; // producer node that exports prefix
68 std::string prefix; // exported prefix
69 ...
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070070 ndnGlobalRoutingHelper.AddOrigins (prefix, producer);
Alexander Afanasyeve6852122013-01-21 11:54:47 -080071
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070072* calculate and install FIBs on every node using :ndnsim:`GlobalRoutingHelper::CalculateRoutes`
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070073
74 .. code-block:: c++
Alexander Afanasyeve6852122013-01-21 11:54:47 -080075
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070076 cdnGlobalRoutingHelper.CalculateRoutes ();
Alexander Afanasyeve6852122013-01-21 11:54:47 -080077
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080078Default routes
79^^^^^^^^^^^^^^
80
81In simple topologies, like in :doc:`examples <examples>`, or when
82simulating broadcast environment, it is possible to set up *default*
83FIB entries using :ndnsim:`StackHelper::SetDefaultRoutes` call.
84More specifically, every installed NDN stack will have a FIB entry to ``/`` prefix, containing all available faces.
85
86The following should be done before installing stack on a node:
87
88 .. code-block:: c++
89
90 ndnHelper.SetDefaultRoutes (true);
91 ...
92 ndnHelper.Install (nodes);
93
94
95Content Store
96+++++++++++++
97
98ndnSIM comes with several different in-memory :ndnsim:`content store <ndn::ContentStore>` implementations, featuring different cache replacement policies.
99
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800100To select a particular content store and configure its capacity, use :ndnsim:`SetContentStore <ndn::StackHelper::SetContentStore>` helper method:
101
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800102 .. code-block:: c++
103
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800104 ndnHelper.SetContentStore ("<content store implementation>",
105 ["<optional parameter>", "<optional parameter's value>" [, ...]]);
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800106 ...
107 ndnHelper.Install (nodes);
108
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800109In simulation scenarios it is possible to select one of :ref:`the existing implementations of the content store or implement your own <content store>`.
Alexander Afanasyevf4a03592012-12-10 16:12:34 -0800110
111
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800112Pending Interest Table
113++++++++++++++++++++++
114
115The current version of ndnSIM provides :ndnsim:`templated realizations <ndn::pit::PitImpl>` of :ndnsim:`PIT abstraction <ndn::Pit>`, allowing optional bounding the number of PIT entries and different replacement policies (i.e., perform different actions when limit on number of PIT entries is reached).
116
117To select a particular PIT implementation and configure its policies, use :ndnsim:`SetPit <ndn::StackHelper::SetPit>` helper method:
118
119- :ndnsim:`persistent <ndn::pit::Persistent>` (default):
120
121 New entries will be rejected if PIT size reached its limit
122
123 .. code-block:: c++
124
125 ndnHelper.SetPit ("ns3::ndn::pit::Persistent",
126 "MaxSize", "0");
127 ...
128 ndnHelper.Install (nodes);
129
130- :ndnsim:`random <ndn::pit::Random>`:
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800131
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800132 when PIT reaches its limit, random entry (could be the newly created one) will be removed from PIT;
133
134 .. code-block:: c++
135
136 ndnHelper.SetPit ("ns3::ndn::pit::Random",
137 "MaxSize", "0");
138 ...
139 ndnHelper.Install (nodes);
140
141- :ndnsim:`least-recently-used <ndn::pit::Lru>`:
142
143 the least recently used entry (the oldest entry with minimum number of incoming faces) will be removed when PIT size reached its limit.
144
145 .. code-block:: c++
146
147 ndnHelper.SetPit ("ns3::ndn::pit::Lru",
148 "MaxSize", "0");
149 ...
150 ndnHelper.Install (nodes);
151
152Forwarding strategy
153+++++++++++++++++++
154
155A desired :ndnsim:`forwarding strategy <ForwardingStrategy>` parameter need to be set before installing stack on a node.
156
Alexander Afanasyevdc794a32013-09-26 14:34:18 -0700157To select a particular forwarding strategy implementation and configure its parameters, use :ndnsim:`SetForwardingStrategy <ndn::StackHelper::SetForwardingStrategy>` helper method:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800158
159 .. code-block:: c++
160
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800161 ndnHelper.SetForwardingStrategy ("<forwarding strategy implementation>",
162 ["<optional parameter>", "<optional parameter's value>" [, ...]]);
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800163 ...
164 ndnHelper.Install (nodes);
165
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800166In simulation scenarios it is possible to select one of :ref:`the existing implementations of the forwarding strategy or implement your own <forwarding strategies>`.
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800167
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800168
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800169.. Currently, there are following forwarding strategies that can be used in simulations:
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800170
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800171.. - :ndnsim:`Flooding` (default)
172
173.. Interests will be forwarded to all available faces available for a route (FIB entry).
174.. If there are no available GREEN or YELLOW faces, interests is dropped.
175
176.. .. code-block:: c++
177
178.. ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::Flooding");
179.. ...
180.. ndnHelper.Install (nodes);
181
182
183.. - :ndnsim:`SmartFlooding`
184
185.. If GREEN face is available, Interest will be sent to the highest-ranked GREEN face.
186.. If not, Interest will be forwarded to all available faces available for a route (FIB entry)/
187.. If there are no available GREEN or YELLOW faces, interests is dropped.
188
189.. .. code-block:: c++
190
191.. ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::SmartFlooding");
192.. ...
193.. ndnHelper.Install (nodes);
194
195.. - :ndnsim:`BestRoute`
196
197.. If GREEN face is available, Interest will be sent to the highest-ranked GREEN face.
198.. If not, Interest will be forwarded to the highest-ranked YELLOW face.
199.. If there are no available GREEN or YELLOW faces, interests is dropped.
200
201.. .. code-block:: c++
202
203.. ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute");
204.. ...
205.. ndnHelper.Install (nodes);
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800206
207
208
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700209
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700210AppHelper
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700211---------------
212
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700213:ndnsim:`AppHelper` simplifies task of creating, configuring, and installing ndnSIM applications.
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700214
215
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700216The basic usage of the :ndnsim:`AppHelper`:
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700217
218* Create helper for specific applications class:
219
220 .. code-block:: c++
221
222 // Create helper for the consumer generating Interests with constant rate
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700223 ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700224
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700225* Assign prefix on which application operates (either generating Interests using this name or satisfying Interests for this name) using :ndnsim:`AppHelper::SetPrefix`:
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700226
227 .. code-block:: c++
228
229 consumerHelper.SetPrefix (prefix);
230
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700231* Assign application-specific attributes using :ndnsim:`AppHelper::SetAttribute`:
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700232
233 .. code-block:: c++
234
235 // Set frequency parameter
236 consumerHelper.SetAttribute ("Frequency", StringValue ("10")); // 10 interests a second
237
238* Install application on one or more nodes:
239
240 .. code-block:: c++
241
242 NodeContainer nodes;
243 ...
244 consumerHelper.Install (nodes)
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800245
246
247In simulation scenarios it is possible to select one of :ref:`the existing applications or implement your own <applications>`.