1 // -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*-

     2 //

     3 // Copyright (c) 2006 Georgia Tech Research Corporation

     4 //

     5 // This program is free software; you can redistribute it and/or modify

     6 // it under the terms of the GNU General Public License version 2 as

     7 // published by the Free Software Foundation;

     8 //

     9 // This program is distributed in the hope that it will be useful,

    10 // but WITHOUT ANY WARRANTY; without even the implied warranty of

    11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    12 // GNU General Public License for more details.

    13 //

    14 // You should have received a copy of the GNU General Public License

    15 // along with this program; if not, write to the Free Software

    16 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    17 //

    18 // Author: George F. Riley<riley@ece.gatech.edu>

    19 //         Gustavo Carneiro <gjc@inescporto.pt>

    20 //

    21 

    22 #ifndef IPV4_STATIC_ROUTING_H

    23 #define IPV4_STATIC_ROUTING_H

    24 

    25 #include <list>

    26 #include <stdint.h>

    27 #include "ns3/ipv4-address.h"

    28 #include "ns3/ipv4-header.h"

    29 #include "ns3/ptr.h"

    30 #include "ns3/ipv4.h"

    31 

    32 namespace ns3 {

    33 

    34 class Packet;

    35 class NetDevice;

    36 class Ipv4Interface;

    37 class Ipv4Address;

    38 class Ipv4Header;

    39 class Ipv4Route;

    40 class Node;

    41 

    42 

    43 /**

    44  * @brief Static routing protocol for IP version 4 stacks.

    45  *

    46  * In ns-3 we have the concept of a pluggable routing protocol.  Routing

    47  * protocols are added to a list maintained by the Ipv4L3Protocol.  Every 

    48  * stack gets one routing protocol for free -- the Ipv4StaticRouting routing

    49  * protocol is added in the constructor of the Ipv4L3Protocol (this is the 

    50  * piece of code that implements the functionality of the IP layer).

    51  *

    52  * The Ipv4StaticRouting class inherits from the abstract base class 

    53  * Ipv4RoutingProtocol that defines the interface methods that a routing 

    54  * protocol must support.

    55  *

    56  * When a packet arrives in the Ipv4L3Protocol for transmission, it comes

    57  * either from a local source via Ipv4L3Protocol::Send or from a remote 

    58  * source via Ipv4L3Protocol::Forwarding.  In both cases, a function is called

    59  * (Ipv4L3Protocol::Lookup) to look up the routing information for the packet.

    60  *

    61  * The lookup function iterates through the list of routing protocols asking

    62  * each to see if it can find a route and send the packet.  A callback is 

    63  * provided during each of these calls that should be considered a pre-

    64  * packaged send call.  This is done to allow asynchronous calls into 

    65  * routing subsystems in order to support on-demand routing, for example.  The

    66  * method for requesting this operation is Ipv4StaticRouting::RequestRoute for

    67  * the static routing protocol.

    68  *

    69  * Each routing protocol is also free to implement its own methods for managing

    70  * routes which you will find below.  This class manages a set of "static" or

    71  * manually configured routes for host, network and multicast routes.

    72  *

    73  * @see Ipv4RoutingProtocol

    74  * @see Ipv4L3Protocol::AddRoutingProtocol

    75  * @see Ipv4L3Protocol::Ipv4L3Protocol

    76  */

    77 class Ipv4StaticRouting : public Ipv4RoutingProtocol

    78 {

    79 public:

    80 /**

    81  * @brief Construct an empty Ipv4StaticRouting routing protocol,

    82  * @internal

    83  *

    84  * The Ipv4StaticRouting class supports host, network and multicast routes.

    85  * This method initializes the lists containing these routes to empty.

    86  *

    87  * @see Ipv4StaticRouting

    88  */

    89   Ipv4StaticRouting ();

    90 

    91 /**

    92  * @brief Request that a check for a route bw performed and if a route is found

    93  * that the packet be sent on its way using the pre-packaged send callback.

    94  *

    95  * The source and destination IP addresses for the packet in question are found

    96  * in the provided Ipv4Header.  There are two major processing forks depending

    97  * on the type of destination address.  

    98  *

    99  * If the destination address is unicast then the routing table is consulted 

   100  * for a route to the destination and if it is found, the routeReply callback

   101  * is executed to send the packet (with the found route).

   102  * 

   103  * If the destination address is a multicast, then the exact processing steps

   104  * depend on whether or not the packet has been sourced locally.  This is 

   105  * determined by the parameter interface.  This is the interface index over which

   106  * this packet was received.  If the packet has not been received over a

   107  * network interface, this index will be set to 

   108  * Ipv4RoutingProtocol::INTERFACE_INDEX_ANY (a very large number).  In that case, 

   109  * we want to avoid the requirement that an explicit route out of each node 

   110  * must be set, so we don't do anything here.

   111  * 

   112  * If the packet is a multicast destination and has been received over a 

   113  * network interface, a call to this method implies that the packet is being

   114  * forwarded.  In that case, there must be an explicit route out of the node.

   115  * A multicast route references the source address, the destination address

   116  * (the multicast group) and the input interface in order to find a route.

   117  * We consult the multicast routing table and, if a route is found, send the

   118  * packet out of as many interfaces as required using the provided callback

   119  * (think of it as a pre-packaged send call).

   120  *

   121  * @param interface The network interface index over which the packed was 

   122  * received.  If the packet is from a local source, interface will be set to

   123  * Ipv4RoutingProtocol::INTERFACE_ANY.

   124  * @param ipHeader the Ipv4Header containing the source and destination IP

   125  * addresses for the packet.

   126  * @param packet The packet to be sent if a route is found.

   127  * @param routeReply A callback that packaged up the call to actually send the

   128  * packet.

   129  * @return Returns true if a route is found and the packet has been sent,

   130  * otherwise returns false indicating that the next routing protocol should

   131  * be consulted.  In practice, the static routing protocol is the last chance

   132  * protocol.

   133  *

   134  * @see Ipv4StaticRouting

   135  * @see Ipv4RoutingProtocol

   136  */

   137   virtual bool RequestRoute (uint32_t interface,

   138                              Ipv4Header const &ipHeader,

   139                              Ptr<Packet> packet,

   140                              RouteReplyCallback routeReply);

   141 

   142 /**

   143  * @brief Check to see if we can determine the interface index that will be

   144  * used if a packet is sent to this destination.

   145  *

   146  * This method addresses a problem in the IP stack where a destination address

   147  * must be present and checksummed into the IP header before the actual 

   148  * interface over which the packet is sent can be determined.  The answer is

   149  * to implement a known and intentional cross-layer violation.  This is the

   150  * endpoint of a call chain that started up quite high in the stack (sockets)

   151  * and has found its way down to the Ipv4L3Protocol which is consulting the

   152  * routing protocols for what they would do if presented with a packet of the

   153  * given destination.

   154  *

   155  * Note that the a single interface index is returned.  This means that if

   156  * the destination address is a multicast, and an explicit route is present

   157  * that includeds multiple output interfaces, that route cannot be used.

   158  * 

   159  * If there are multiple paths out of the node, the resolution is performed

   160  * by Ipv4L3Protocol::GetInterfaceforDestination which has access to more 

   161  * contextual information that is useful for making a determination.

   162  *

   163  * @param destination The Ipv4Address if the destination of a hypothetical 

   164  * packet.  This may be a multicast group address.

   165  * @param interface A reference to the interface index over which a packet

   166  * sent to this destination would be sent.

   167  * @return Returns true if a route is found to the destination that involves

   168  * a single output interface index, otherwise returns false indicating that

   169  * the next routing protocol should be consulted.  In practice, the static 

   170  * routing protocol is the last chance protocol.

   171  *

   172  * @see Ipv4StaticRouting

   173  * @see Ipv4RoutingProtocol

   174  * @see Ipv4L3Protocol

   175  */

   176   virtual bool RequestInterface (Ipv4Address destination, uint32_t& interface);

   177 

   178 /**

   179  * @brief Add a host route to the static routing table.

   180  *

   181  * @param dest The Ipv4Address destination for this route.

   182  * @param nextHop The Ipv4Address of the next hop in the route.

   183  * @param interface The network interface index used to send packets to the

   184  * destination.

   185  *

   186  * @see Ipv4Address

   187  */

   188   void AddHostRouteTo (Ipv4Address dest, 

   189                        Ipv4Address nextHop, 

   190                        uint32_t interface);

   191 /**

   192  * @brief Add a host route to the static routing table.

   193  *

   194  * @param dest The Ipv4Address destination for this route.

   195  * @param interface The network interface index used to send packets to the

   196  * destination.

   197  *

   198  * @see Ipv4Address

   199  */

   200   void AddHostRouteTo (Ipv4Address dest, 

   201                        uint32_t interface);

   202 

   203 /**

   204  * @brief Add a network route to the static routing table.

   205  *

   206  * @param network The Ipv4Address network for this route.

   207  * @param networkMask The Ipv4Mask to extract the network.

   208  * @param nextHop The next hop in the route to the destination network.

   209  * @param interface The network interface index used to send packets to the

   210  * destination.

   211  *

   212  * @see Ipv4Address

   213  */

   214   void AddNetworkRouteTo (Ipv4Address network, 

   215                           Ipv4Mask networkMask, 

   216                           Ipv4Address nextHop, 

   217                           uint32_t interface);

   218 

   219 /**

   220  * @brief Add a network route to the static routing table.

   221  *

   222  * @param network The Ipv4Address network for this route.

   223  * @param networkMask The Ipv4Mask to extract the network.

   224  * @param interface The network interface index used to send packets to the

   225  * destination.

   226  *

   227  * @see Ipv4Address

   228  */

   229   void AddNetworkRouteTo (Ipv4Address network, 

   230                           Ipv4Mask networkMask, 

   231                           uint32_t interface);

   232 

   233 /**

   234  * @brief Add a default route to the static routing table.

   235  *

   236  * This method tells the routing system what to do in the case where a specific

   237  * route to a destination is not found.  The system forwards packets to the

   238  * specified node in the hope that it knows better how to route the packet.

   239  * 

   240  * If the default route is set, it is returned as the selected route from 

   241  * LookupStatic irrespective of destination address if no specific route is

   242  * found.

   243  *

   244  * @param nextHop The Ipv4Address to send packets to in the hope that they

   245  * will be forwarded correctly.

   246  * @param interface The network interface index used to send packets.

   247  *

   248  * @see Ipv4Address

   249  * @see Ipv4StaticRouting::Lookup

   250  */

   251   void SetDefaultRoute (Ipv4Address nextHop, 

   252                         uint32_t interface);

   253 

   254 /**

   255  * @brief Get the number of individual unicast routes that have been added

   256  * to the routing table.

   257  *

   258  * @warning The default route counts as one of the routes.

   259  */

   260   uint32_t GetNRoutes (void);

   261 

   262 /**

   263  * @brief Get the default route from the static routing table.

   264  *

   265  * @return If the default route is set, a pointer to that Ipv4Route is

   266  * returned, otherwise a zero pointer is returned.

   267  *

   268  * @see Ipv4Route

   269  */

   270   Ipv4Route *GetDefaultRoute (void);

   271 

   272 /**

   273  * @brief Get a route from the static unicast routing table.

   274  *

   275  * Externally, the unicast static routing table appears simply as a table with

   276  * n entries.  The one sublety of note is that if a default route has been set

   277  * it will appear as the zeroth entry in the table.  This means that if you

   278  * add only a default route, the table will have one entry that can be accessed

   279  * either by explicity calling GetDefaultRoute () or by calling GetRoute (0).

   280  * 

   281  * Similarly, if the default route has been set, calling RemoveRoute (0) will

   282  * remove the default route.

   283  *

   284  * @param i The index (into the routing table) of the route to retrieve.  If

   285  * the default route has been set, it will occupy index zero.

   286  * @return If route is set, a pointer to that Ipv4Route is returned, otherwise

   287  * a zero pointer is returned.

   288  *

   289  * @see Ipv4Route

   290  * @see Ipv4StaticRouting::RemoveRoute

   291  */

   292   Ipv4Route *GetRoute (uint32_t i);

   293 

   294 /**

   295  * @brief Remove a route from the static unicast routing table.

   296  *

   297  * Externally, the unicast static routing table appears simply as a table with

   298  * n entries.  The one sublety of note is that if a default route has been set

   299  * it will appear as the zeroth entry in the table.  This means that if the

   300  * default route has been set, calling RemoveRoute (0) will remove the

   301  * default route.

   302  *

   303  * @param i The index (into the routing table) of the route to remove.  If

   304  * the default route has been set, it will occupy index zero.

   305  *

   306  * @see Ipv4Route

   307  * @see Ipv4StaticRouting::GetRoute

   308  * @see Ipv4StaticRouting::AddRoute

   309  */

   310   void RemoveRoute (uint32_t i);

   311 

   312 /**

   313  * @brief Add a multicast route to the static routing table.

   314  *

   315  * A multicast route must specify an origin IP address, a multicast group and

   316  * an input network interface index as conditions and provide a vector of

   317  * output network interface indices over which packets matching the conditions

   318  * are sent.

   319  *

   320  * Typically there are two main types of multicast routes:  routes of the 

   321  * first kind are used during forwarding.  All of the conditions must be

   322  * exlicitly provided.  The second kind of routes are used to get packets off

   323  * of a local node.  The difference is in the input interface.  Routes for

   324  * forwarding will always have an explicit input interface specified.  Routes

   325  * off of a node will always set the input interface to a wildcard specified

   326  * by the index Ipv4RoutingProtocol::INTERFACE_ANY.

   327  *

   328  * For routes off of a local node wildcards may be used in the origin and

   329  * multicast group addresses.  The wildcard used for Ipv4Adresses is that 

   330  * address returned by Ipv4Address::GetAny () -- typically "0.0.0.0".  Usage

   331  * of a wildcard allows one to specify default behavior to varying degrees.

   332  *

   333  * For example, making the origin address a wildcard, but leaving the 

   334  * multicast group specific allows one (in the case of a node with multiple

   335  * interfaces) to create different routes using different output interfaces

   336  * for each multicast group.

   337  *

   338  * If the origin and multicast addresses are made wildcards, you have created

   339  * essentially a default multicast address that can forward to multiple 

   340  * interfaces.  Compare this to the actual default multicast address that is

   341  * limited to specifying a single output interface for compatibility with

   342  * existing functionality in other systems.

   343  * 

   344  * @param origin The Ipv4Address of the origin of packets for this route.  May

   345  * be Ipv4Address:GetAny for open groups.

   346  * @param group The Ipv4Address of the multicast group or this route.

   347  * @param inputInterface The input network interface index over which to 

   348  * expect packets destined for this route.  May be

   349  * Ipv4RoutingProtocol::INTERFACE_ANY for packets of local origin.

   350  * @param outputInterfaces A vector of network interface indices used to specify

   351  * how to send packets to the destination(s).

   352  *

   353  * @see Ipv4Address

   354  */

   355   void AddMulticastRoute (Ipv4Address origin,

   356                           Ipv4Address group,

   357                           uint32_t inputInterface,

   358                           std::vector<uint32_t> outputInterfaces);

   359 

   360 /**

   361  * @brief Add a default multicast route to the static routing table.

   362  *

   363  * This is the multicast equivalent of the unicast version SetDefaultRoute.

   364  * We tell the routing system what to do in the case where a specific route

   365  * to a destination multicast group is not found.  The system forwards 

   366  * packets out the specified interface in the hope that "something out there"

   367  * knows better how to route the packet.  This method is only used in 

   368  * initially sending packets off of a host.  The default multicast route is

   369  * not consulted during forwarding -- exact routes must be specified using

   370  * AddMulticastRoute for that case.

   371  *

   372  * Since we're basically sending packets to some entity we think may know

   373  * better what to do, we don't pay attention to "subtleties" like origin

   374  * address, nor do we worry about forwarding out multiple  interfaces.  If the

   375  * default multicast route is set, it is returned as the selected route from 

   376  * LookupStatic irrespective of origin or multicast group if another specific

   377  * route is not found.

   378  *

   379  * @param outputInterface The network interface index used to specify where

   380  * to send packets in the case of unknown routes.

   381  *

   382  * @see Ipv4Address

   383  */

   384   void SetDefaultMulticastRoute (uint32_t outputInterface);

   385 

   386 /**

   387  * @brief Get the number of individual multicast routes that have been added

   388  * to the routing table.

   389  *

   390  * @warning The default multicast route counts as one of the routes.

   391  */

   392   uint32_t GetNMulticastRoutes (void) const;

   393 

   394 /**

   395  * @brief Get a route from the static multicast routing table.

   396  *

   397  * Externally, the multicast static routing table appears simply as a table 

   398  * with n entries.  The one sublety of note is that if a default route has 

   399  * been set it will appear as the zeroth entry in the table.  This means that 

   400  * if you add only a default route, the table will have one entry that can be

   401  * accessed either by explicity calling GetDefaultMulticastRoute () or by

   402  * calling GetMulticastRoute (0).

   403  * 

   404  * Similarly, if the default route has been set, calling 

   405  * RemoveMulticastRoute (0) will remove the default route.

   406  *

   407  * @param i The index (into the routing table) of the multicast route to

   408  * retrieve.  If the default route has been set, it will occupy index zero.

   409  * @return If route \e i is set, a pointer to that Ipv4MulticastRoute is

   410  * returned, otherwise a zero pointer is returned.

   411  *

   412  * @see Ipv4MulticastRoute

   413  * @see Ipv4StaticRouting::RemoveRoute

   414  */

   415   Ipv4MulticastRoute *GetMulticastRoute (uint32_t i) const;

   416 

   417 /**

   418  * @brief Get the default multicast route from the static routing table.

   419  *

   420  * @return If the default route is set, a pointer to that Ipv4MulticastRoute is

   421  * returned, otherwise a zero pointer is returned.

   422  *

   423  * @see Ipv4Route

   424  */

   425   Ipv4MulticastRoute *GetDefaultMulticastRoute (void) const;

   426 

   427 /**

   428  * @brief Remove a route from the static multicast routing table.

   429  *

   430  * Externally, the multicast static routing table appears simply as a table 

   431  * with n entries.  The one sublety of note is that if a default multicast

   432  * route has been set it will appear as the zeroth entry in the table.  This

   433  * means that the default route may be removed by calling this method with

   434  * appropriate wildcard parameters.

   435  *

   436  * This method causes the multicast routing table to be searched for the first

   437  * route that matches the parameters and removes it.

   438  *

   439  * Wildcards may be provided to this function, but the wildcards are used to

   440  * exacly match wildcards in the routes (see AddMulticastRoute).  That is,

   441  * calling RemoveMulticastRoute with the origin set to "0.0.0.0" will not

   442  * remove routes with any address in the origin, but will only remove routes

   443  * with "0.0.0.0" set as the the origin.

   444  *

   445  * @param origin The IP address specified as the origin of packets for the

   446  * route.

   447  * @param group The IP address specified as the multicast group addres of

   448  * the route.

   449  * @param inputInterface The network interface index specified as the expected

   450  * input interface for the route.

   451  * @returns true if a route was found and removed, false otherwise.

   452  *

   453  * @see Ipv4MulticastRoute

   454  * @see Ipv4StaticRouting::AddMulticastRoute

   455  */

   456   bool RemoveMulticastRoute (Ipv4Address origin,

   457                              Ipv4Address group,

   458                              uint32_t inputInterface);

   459 

   460 /**

   461  * @brief Remove a route from the static multicast routing table.

   462  *

   463  * Externally, the multicast static routing table appears simply as a table 

   464  * with n entries.  The one sublety of note is that if a default multicast

   465  * route has been set it will appear as the zeroth entry in the table.  This 

   466  * means that if the default route has been set, calling 

   467  * RemoveMulticastRoute (0) will remove the default route.

   468  *

   469  * @param index The index (into the multicast routing table) of the route to

   470  * remove.  If the default route has been set, it will occupy index zero.

   471  *

   472  * @see Ipv4Route

   473  * @see Ipv4StaticRouting::GetRoute

   474  * @see Ipv4StaticRouting::AddRoute

   475  */

   476   void RemoveMulticastRoute (uint32_t index);

   477 

   478 protected:

   479   void DoDispose (void);

   480 

   481 private:

   482   typedef std::list<Ipv4Route *> HostRoutes;

   483   typedef std::list<Ipv4Route *>::const_iterator HostRoutesCI;

   484   typedef std::list<Ipv4Route *>::iterator HostRoutesI;

   485   typedef std::list<Ipv4Route *> NetworkRoutes;

   486   typedef std::list<Ipv4Route *>::const_iterator NetworkRoutesCI;

   487   typedef std::list<Ipv4Route *>::iterator NetworkRoutesI;

   488 

   489   typedef std::list<Ipv4MulticastRoute *> MulticastRoutes;

   490   typedef std::list<Ipv4MulticastRoute *>::const_iterator MulticastRoutesCI;

   491   typedef std::list<Ipv4MulticastRoute *>::iterator MulticastRoutesI;

   492 

   493   Ipv4Route *LookupStatic (Ipv4Address dest);

   494   Ipv4MulticastRoute *LookupStatic (Ipv4Address origin, Ipv4Address group,

   495                                     uint32_t interface);

   496 

   497   HostRoutes m_hostRoutes;

   498   NetworkRoutes m_networkRoutes;

   499   Ipv4Route *m_defaultRoute;

   500   Ipv4MulticastRoute *m_defaultMulticastRoute;

   501   MulticastRoutes m_multicastRoutes;

   502 };

   503 

   504 } // Namespace ns3

   505 

   506 #endif /* IPV4_STATIC_ROUTING_H */