diff --git a/doc/models/source/index.rst b/doc/models/source/index.rst index 260308ddb..dd5e8495b 100644 --- a/doc/models/source/index.rst +++ b/doc/models/source/index.rst @@ -40,6 +40,7 @@ This document is written in `reStructuredText `_) OSPF implementation was used as the -basis for the routing computation logic. One benefit of following an existing -OSPF SPF implementation is that OSPF already has defined link state -advertisements for all common types of network links: - -* point-to-point (serial links) -* point-to-multipoint (Frame Relay, ad hoc wireless) -* non-broadcast multiple access (ATM) -* broadcast (Ethernet) - -Therefore, we think that enabling these other link types will be more -straightforward now that the underlying OSPF SPF framework is in place. - -Presently, we can handle IPv4 point-to-point, numbered links, as well as shared -broadcast (CSMA) links. Equal-cost multipath is also supported. Although -wireless link types are supported by the implementation, note that due -to the nature of this implementation, any channel effects will not be -considered and the routing tables will assume that every node on the -same shared channel is reachable from every other node (i.e. it will -be treated like a broadcast CSMA link). - -The GlobalRouteManager first walks the list of nodes and aggregates -a GlobalRouter interface to each one as follows:: - - typedef std::vector < Ptr >::iterator Iterator; - for (Iterator i = NodeList::Begin (); i != NodeList::End (); i++) - { - Ptr node = *i; - Ptr globalRouter = CreateObject (node); - node->AggregateObject (globalRouter); - } - -This interface is later queried and used to generate a Link State -Advertisement for each router, and this link state database is -fed into the OSPF shortest path computation logic. The Ipv4 API -is finally used to populate the routes themselves. - .. _Unicast-routing: Unicast routing @@ -285,52 +156,135 @@ the list of routing protocols, in priority order, until a route is found. Such routing protocol will invoke the appropriate callback and no further routing protocols will be searched. -Optimized Link State Routing (OLSR) -+++++++++++++++++++++++++++++++++++ +.. _Global-centralized-routing: -This IPv4 routing protocol was originally ported from the OLSR-UM implementation -for ns-2. The implementation is found in the src/olsr directory, and an -example script is in examples/simple-point-to-point-olsr.cc. +Global centralized routing +++++++++++++++++++++++++++ -Typically, OLSR is enabled in a main program by use of an OlsrHelper class that -installs OLSR into an Ipv4ListRoutingProtocol object. The following sample -commands will enable OLSR in a simulation using this helper class along with -some other routing helper objects. The setting of priority value 10, ahead of -the staticRouting priority of 0, means that OLSR will be consulted for a route -before the node's static routing table.:: +Global centralized routing is sometimes called "God" routing; it is a special +implementation that walks the simulation topology and runs a shortest path +algorithm, and populates each node's routing tables. No actual protocol overhead +(on the simulated links) is incurred with this approach. It does have a few +constraints: - NodeContainer c: - ... - // Enable OLSR - NS_LOG_INFO ("Enabling OLSR Routing."); - OlsrHelper olsr; +* **Wired only:** It is not intended for use in wireless networks. +* **Unicast only:** It does not do multicast. +* **Scalability:** Some users of this on large topologies (e.g. 1000 nodes) + have noticed that the current implementation is not very scalable. The global + centralized routing will be modified in the future to reduce computations and + runtime performance. - Ipv4StaticRoutingHelper staticRouting; +Presently, global centralized IPv4 unicast routing over both point-to-point and +shared (CSMA) links is supported. - Ipv4ListRoutingHelper list; - list.Add (staticRouting, 0); - list.Add (olsr, 10); +By default, when using the |ns3| helper API and the default InternetStackHelper, +global routing capability will be added to the node, and global routing will be +inserted as a routing protocol with lower priority than the static routes (i.e., +users can insert routes via Ipv4StaticRouting API and they will take precedence +over routes found by global routing). - InternetStackHelper internet; - internet.SetRoutingHelper (list); - internet.Install (c); +Global Unicast Routing API +~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once installed,the OLSR "main interface" can be set with the SetMainInterface() -command. If the user does not specify a main address, the protocol will select -the first primary IP address that it finds, starting first the loopback -interface and then the next non-loopback interface found, in order of Ipv4 -interface index. The loopback address of 127.0.0.1 is not selected. In addition, -a number of protocol constants are defined in olsr-routing-protocol.cc. +The public API is very minimal. User scripts include the following:: -Olsr is started at time zero of the simulation, based on a call to -Object::Start() that eventually calls OlsrRoutingProtocol::DoStart(). Note: a -patch to allow the user to start and stop the protocol at other times would be -welcome. + #include "ns3/internet-module.h" + +If the default InternetStackHelper is used, then an instance of global routing +will be aggregated to each node. After IP addresses are configured, the +following function call will cause all of the nodes that have an Ipv4 interface +to receive forwarding tables entered automatically by the GlobalRouteManager:: + + Ipv4GlobalRoutingHelper::PopulateRoutingTables (); + +*Note:* A reminder that the wifi NetDevice will work but does not take any +wireless effects into account. For wireless, we recommend OLSR dynamic routing +described below. + +It is possible to call this function again in the midst of a simulation using +the following additional public function:: + + Ipv4GlobalRoutingHelper::RecomputeRoutingTables (); + +which flushes the old tables, queries the nodes for new interface information, +and rebuilds the routes. + +For instance, this scheduling call will cause the tables to be rebuilt +at time 5 seconds:: + + Simulator::Schedule (Seconds (5), + &Ipv4GlobalRoutingHelper::RecomputeRoutingTables); + + +There are two attributes that govern the behavior. The first is +Ipv4GlobalRouting::RandomEcmpRouting. If set to true, packets are randomly +routed across equal-cost multipath routes. If set to false (default), only one +route is consistently used. The second is +Ipv4GlobalRouting::RespondToInterfaceEvents. If set to true, dynamically +recompute the global routes upon Interface notification events (up/down, or +add/remove address). If set to false (default), routing may break unless the +user manually calls RecomputeRoutingTables() after such events. The default is +set to false to preserve legacy |ns3| program behavior. + +Global Routing Implementation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section is for those readers who care about how this is implemented. A +singleton object (GlobalRouteManager) is responsible for populating the static +routes on each node, using the public Ipv4 API of that node. It queries each +node in the topology for a "globalRouter" interface. If found, it uses the API +of that interface to obtain a "link state advertisement (LSA)" for the router. +Link State Advertisements are used in OSPF routing, and we follow their +formatting. + +It is important to note that all of these computations are done before +packets are flowing in the network. In particular, there are no +overhead or control packets being exchanged when using this implementation. +Instead, this global route manager just walks the list of nodes to +build the necessary information and configure each node's routing table. + +The GlobalRouteManager populates a link state database with LSAs gathered from +the entire topology. Then, for each router in the topology, the +GlobalRouteManager executes the OSPF shortest path first (SPF) computation on +the database, and populates the routing tables on each node. + +The quagga (``_) OSPF implementation was used as the +basis for the routing computation logic. One benefit of following an existing +OSPF SPF implementation is that OSPF already has defined link state +advertisements for all common types of network links: + +* point-to-point (serial links) +* point-to-multipoint (Frame Relay, ad hoc wireless) +* non-broadcast multiple access (ATM) +* broadcast (Ethernet) + +Therefore, we think that enabling these other link types will be more +straightforward now that the underlying OSPF SPF framework is in place. + +Presently, we can handle IPv4 point-to-point, numbered links, as well as shared +broadcast (CSMA) links. Equal-cost multipath is also supported. Although +wireless link types are supported by the implementation, note that due +to the nature of this implementation, any channel effects will not be +considered and the routing tables will assume that every node on the +same shared channel is reachable from every other node (i.e. it will +be treated like a broadcast CSMA link). + +The GlobalRouteManager first walks the list of nodes and aggregates +a GlobalRouter interface to each one as follows:: + + typedef std::vector < Ptr >::iterator Iterator; + for (Iterator i = NodeList::Begin (); i != NodeList::End (); i++) + { + Ptr node = *i; + Ptr globalRouter = CreateObject (node); + node->AggregateObject (globalRouter); + } + +This interface is later queried and used to generate a Link State +Advertisement for each router, and this link state database is +fed into the OSPF shortest path computation logic. The Ipv4 API +is finally used to populate the routes themselves. -Presently, OLSR is limited to use with an Ipv4ListRouting object, and does not -respond to dynamic changes to a device's IP address or link up/down -notifications; i.e. the topology changes are due to loss/gain of connectivity -over a wireless channel. RIP and RIPng +++++++++++++ @@ -451,6 +405,21 @@ tables and route advertisements may be larger than necessary. Prefix aggregation may be added in the future. +Other routing protocols ++++++++++++++++++++++++ + +Other routing protocols documentation can be found under the respective +modules sections, e.g.: + +* AODV +* Click +* DSDV +* DSR +* NixVectorRouting +* OLSR +* etc. + + .. _Multicast-routing: Multicast routing diff --git a/src/internet/doc/routing-specialization.dia b/src/internet/doc/routing-specialization.dia index 9c8122593..bfa08262b 100644 Binary files a/src/internet/doc/routing-specialization.dia and b/src/internet/doc/routing-specialization.dia differ diff --git a/src/nix-vector-routing/doc/nix-vector-routing.h b/src/nix-vector-routing/doc/nix-vector-routing.h deleted file mode 100644 index f3fca4e15..000000000 --- a/src/nix-vector-routing/doc/nix-vector-routing.h +++ /dev/null @@ -1,52 +0,0 @@ -/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ -/* - * Copyright (c) 2009 The Georgia Institute of Technology - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 as - * published by the Free Software Foundation; - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - * - * Authors: Josh Pelkey - */ - -/** - * \defgroup nix-vector-routing Nix-Vector Routing - * - * \section model Model - * - * Nix-vector routing is a simulation specific routing protocol and is - * intended for large network topologies. The on-demand nature of this - * protocol as well as the low-memory footprint of the nix-vector provides - * improved performance in terms of memory usage and simulation run time - * when dealing with a large number of nodes. - * - * Currently, the ns-3 model of nix-vector routing supports IPv4 p2p links - * as well as CSMA links. It does not (yet) provide support for - * efficient adaptation to link failures. It simply flushes all nix-vector - * routing caches. Finally, IPv6 is not supported. - * - * \section impl Implementation - * - * ns-3 nix-vector-routing performs on-demand route computation using - * a breadth-first search and an efficient route-storage data structure - * known as a nix-vector. When a packet is generated at a node for - * transmission, the route is calculated, and the nix-vector is built. - * The nix-vector stores an index for each hop along the path, which - * corresponds to the neighbor-index. This index is used to determine - * which net-device and gateway should be used. To route a packet, the - * nix-vector must be transmitted with the packet. At each hop, the - * current node extracts the appropriate neighbor-index from the - * nix-vector and transmits the packet through the corresponding - * net-device. This continues until the packet reaches the destination. - * - */ - diff --git a/src/nix-vector-routing/doc/nix-vector-routing.rst b/src/nix-vector-routing/doc/nix-vector-routing.rst new file mode 100644 index 000000000..83b35f433 --- /dev/null +++ b/src/nix-vector-routing/doc/nix-vector-routing.rst @@ -0,0 +1,63 @@ +Nix-Vector Routing Documentation +-------------------------------- + +.. include:: replace.txt +.. highlight:: cpp + +.. heading hierarchy: + ------------- Chapter + ************* Section (#.#) + ============= Subsection (#.#.#) + ############# Paragraph (no number) + + +Nix-vector routing is a simulation specific routing protocol and is +intended for large network topologies. The on-demand nature of this +protocol as well as the low-memory footprint of the nix-vector provides +improved performance in terms of memory usage and simulation run time +when dealing with a large number of nodes. + +Model Description +***************** + +The source code for the NixVectorRouting module lives in +the directory ``src/nix-vector-routing``. + +|ns3| nix-vector-routing performs on-demand route computation using +a breadth-first search and an efficient route-storage data structure +known as a nix-vector. + +When a packet is generated at a node for transmission, the route is +calculated, and the nix-vector is built. +The nix-vector stores an index for each hop along the path, which +corresponds to the neighbor-index. This index is used to determine +which net-device and gateway should be used. To route a packet, the +nix-vector must be transmitted with the packet. At each hop, the +current node extracts the appropriate neighbor-index from the +nix-vector and transmits the packet through the corresponding +net-device. This continues until the packet reaches the destination. + +Scope and Limitations +===================== + +Currently, the ns-3 model of nix-vector routing supports IPv4 p2p links +as well as CSMA links. It does not (yet) provide support for +efficient adaptation to link failures. It simply flushes all nix-vector +routing caches. Finally, IPv6 is not supported. + + +Usage +***** + +The usage pattern is the one of all the Internet routing protocols. +Since NixVectorRouting is not installed by default in the +Internet stack, it is necessary to set it in the Internet Stack +helper by using ``InternetStackHelper::SetRoutingHelper`` + + +Examples +======== + +The examples for the NixVectorRouting module lives in +the directory ``src/nix-vector-routing/examples``. + diff --git a/src/nix-vector-routing/model/ipv4-nix-vector-routing.h b/src/nix-vector-routing/model/ipv4-nix-vector-routing.h index fb793be45..a2e2aa1dd 100644 --- a/src/nix-vector-routing/model/ipv4-nix-vector-routing.h +++ b/src/nix-vector-routing/model/ipv4-nix-vector-routing.h @@ -35,6 +35,13 @@ namespace ns3 { +/** + * \defgroup nix-vector-routing Nix-Vector Routing + * + * Nix-vector routing is a simulation specific routing protocol and is + * intended for large network topologies. + */ + /** * \ingroup nix-vector-routing * Map of Ipv4Address to NixVector diff --git a/src/olsr/doc/olsr.rst b/src/olsr/doc/olsr.rst index 3c82c5956..647bb3725 100644 --- a/src/olsr/doc/olsr.rst +++ b/src/olsr/doc/olsr.rst @@ -47,6 +47,41 @@ The usage pattern is the one of all the Internet routing protocols. Since OLSR is not installed by default in the Internet stack, it is necessary to set it in the Internet Stack helper by using ``InternetStackHelper::SetRoutingHelper`` +Typically, OLSR is enabled in a main program by use of an OlsrHelper class that +installs OLSR into an Ipv4ListRoutingProtocol object. The following sample +commands will enable OLSR in a simulation using this helper class along with +some other routing helper objects. The setting of priority value 10, ahead of +the staticRouting priority of 0, means that OLSR will be consulted for a route +before the node's static routing table.:: + + NodeContainer c: + ... + // Enable OLSR + NS_LOG_INFO ("Enabling OLSR Routing."); + OlsrHelper olsr; + + Ipv4StaticRoutingHelper staticRouting; + + Ipv4ListRoutingHelper list; + list.Add (staticRouting, 0); + list.Add (olsr, 10); + + InternetStackHelper internet; + internet.SetRoutingHelper (list); + internet.Install (c); + +Once installed,the OLSR "main interface" can be set with the SetMainInterface() +command. If the user does not specify a main address, the protocol will select +the first primary IP address that it finds, starting first the loopback +interface and then the next non-loopback interface found, in order of Ipv4 +interface index. The loopback address of 127.0.0.1 is not selected. In addition, +a number of protocol constants are defined in olsr-routing-protocol.cc. + +Olsr is started at time zero of the simulation, based on a call to +Object::Start() that eventually calls OlsrRoutingProtocol::DoStart(). Note: a +patch to allow the user to start and stop the protocol at other times would be +welcome. + Examples ++++++++ @@ -94,6 +129,11 @@ The available traces are: Caveats +++++++ +Presently, OLSR is limited to use with an Ipv4ListRouting object, and does not +respond to dynamic changes to a device's IP address or link up/down +notifications; i.e. the topology changes are due to loss/gain of connectivity +over a wireless channel. + The code does not present any known issue. Validation