NED File src/inet/networklayer/configurator/ipv4/IPv4NetworkConfigurator.ned

Name	Type	Description
IPv4NetworkConfigurator	simple module	This module assigns IP addresses and sets up static routing for an IPv4 network. It assigns per-interface IP addresses, strives to take subnets into account, and can also optimize the generated routing tables by merging routing entries.

Source code

//
// Copyright (C) 2012 Opensim Ltd.
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public License
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
//
// 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 Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with this program; if not, see <http://www.gnu.org/licenses/>.
//
//
// Authors: Levente Meszaros (primary author), Andras Varga, Tamas Borbely
//

package inet.networklayer.configurator.ipv4;

import inet.networklayer.configurator.base.NetworkConfiguratorBase;

//
// This module assigns IP addresses and sets up static routing for an IPv4 network.
// It assigns per-interface IP addresses, strives to take subnets into account,
// and can also optimize the generated routing tables by merging routing entries.
//
// IMPORTANT: as of INET 2.2, this module does NOT assign addresses or add
// routes directly, just stores them in its internal data structures.
// Network nodes are supposed to contain an instance of ~IPv4NodeConfigurator
// (normally part of the network layer compound module) that actually
// configures the node's interface table and routing table based on the
// information stored in the global network configurator module.
//
// The configurator supports both manual and automatic address assignment,
// and their combinations. You can provide address and netmask templates
// with unspecified parts, and the configurator automatically completes
// them by trying to put nodes on the same LAN into the same subnet.
// It also supports manual routes, and automatic routes that follow the
// shortest paths. By default, the configurator adds default routes where
// applicable (e.g. in hosts) and does subnet-based routing.
//
// Hierarchical routing can be set up by using only a fraction of configuration
// entries compared to the number of nodes. The configurator also does
// routing table optimization that significantly decreases the size of routing
// tables in large networks.
//
// Most of the above features can be turned on and off using NED parameters.
// The details (interface address and netmask templates, manual routes, etc.)
// can be configured in a single XML file for the whole network.
//
// Modules that represent network nodes (host, hub, bus, switch, access point,
// router, etc.) are expected to have the @networkNode property, becaue that's how the
// configurator recognizes them in the model. All nodes must have their
// interface table (~InterfaceTable module) as their "interfaceTable" submodule.
// All routers must have their routing table (~IPv4RoutingTable module) as their
// "routingTable" or "networkLayer.routingTable" submodule.
//
// By default all interfaces in all nodes will have a unique IPv4 address
// assigned. Routing tables will be configured so that there's a route
// following the shortest path from any node to any interface. In other words,
// all interfaces will be reachable from all nodes (e.g. ping).
//
// The configurator doesn't connect to any other modules (it has no gates),
// and should have only one instance in the whole model. The configuration
// takes place in initialization stage 2 after the interfaces are registered
// in the ~InterfaceTable modules.
//
// The configurator goes through the following configuration steps:
//
// -# Builds a graph representing the network topology. The graph
// will have a vertex for every module that has a @networkNode property (this
// includes hosts, routers, and L2 devices like switches, access points,
// Ethernet hubs, etc.) It also assigns weights to vertices and edges that
// will be used by the shortest path algorithm when setting up routes.
// Weights will be infinite for IP nodes that have IP forwarding disabled
/// (to prevent routes from transiting them), and zero for all other nodes
// (routers and and L2 devices). Edge weights are chosen to be inversely
// proportional to the bitrate of the link, so that the configurator
// prefers connections with higher bandwidth. For internal purposes,
// the configurator also builds a table of all "links" (the link data
// structure consists of the set of network interfaces that are
// on the same point-to-point link or LAN)
//
// -# Assigns IP addresses to all interfaces of all nodes. The
// assignment process takes into consideration the addresses and netmasks
// already present on the interfaces (possibly set in earlier initialize
// stages), and the configuration provided in the XML format (described
// below). The configuration can specify "templates" for the address
// and netmask, with parts that are fixed and parts that can be chosen
// by the configurator (e.g. "10.0.x.x"). In the most general case,
// the configurator is allowed to choose any address and netmask for all
// interfaces (which results in automatic address assignment). In the most
// constrained case, the configurator is forced to use the requested addresses
// and netmasks for all interfaces (which translates to manual address assignment).
// There are many possible configuration options between these two extremums. The
// configurator assigns addresses in a way that maximizes the number of
// nodes per subnet. Once it figures out the nodes that belong to a single
// subnet it, will optimize for allocating the longest possible netmask.
// The configurator might fail to assign netmasks and addresses according
// to the given configuration parameters; if that happens, the assignment
// process stops and an error is signalled.
//
// -# Adds the manual routes that are specified in the configuration.
//
// -# Adds static routes to all routing tables in the network. The
// configurator uses Dijkstra's weighted shortest path algorithm to find
// the desired routes between all possible node pairs. The resulting
// routing tables will have one entry for all destination interfaces in the
// network. The configurator can be safely instructed to add default routes
// where applicable, significantly reducing the size of the host routing
// tables. It can also add subnet routes instead of interface routes further
// reducing the size of routing tables. Turning on this option requires
// careful design to avoid having IP addresses from the same subnet on
// different links. CAVEAT: Using manual routes and static route generation
// together may have unwanted side effects, because route generation ignores
// manual routes.
//
// -# Then it optimizes the routing tables for size. This optimization allows
// configuring larger networks with smaller memory footprint and makes the
// routing table lookup faster. The resulting routing table might be
// different in that it will route packets that the original routing table
// did not. Nevertheless the following invariant holds: any packet routed
// by the original routing table (has matching route) will still be routed
// the same way by the optimized routing table.
//
// -# Finally it dumps the requested results of the configuration. It can
// dump network topology, assigned IP addresses, routing tables and its
// own configuration format.
//
// The following example configures all interfaces in the IPv4 address range
// 10.0.0.0 - 10.255.255.255, and netmask range 255.0.0.0 - 255.255.255.255.
// This is the default configuration.
//
// <pre>
// <config>
// <interface hosts='**' address='10.x.x.x' netmask='255.x.x.x'/>
// </config>
// </pre>
//
// The following example configures a hierarchical network in a way that keeps
// routing tables small.
// <pre>
// <config>
// <interface hosts="area11.lan1.*" address="10.11.1.x" netmask="255.255.255.x"/>
// <interface hosts="area11.lan2.*" address="10.11.2.x" netmask="255.255.255.x"/>
// <interface hosts="area12.lan1.*" address="10.12.1.x" netmask="255.255.255.x"/>
// <interface hosts="area12.lan2.*" address="10.12.2.x" netmask="255.255.255.x"/>
// <interface hosts="area*.router*" address="10.x.x.x" netmask="x.x.x.x"/>
// <interface hosts="*" address="10.x.x.x" netmask="255.x.x.0"/>
// </config>
// </pre>
//
// The XML configuration must contain exactly one <config> element. Under the
// root element there can be multiple of the following elements.
//
// - <interface>
// The interface element provides configuration parameters for one or more
// interfaces in the network. The selector attributes limit the scope where
// the interface element has effects. The parameter attributes limit the
// range of assignable addresses and netmasks.
//
// - @hosts
// Optional selector attribute that specifies a list of host name patterns.
// Only interfaces in the specified hosts are affected. The pattern might
// be a full path starting from the network, or a module name anywhere in
// the hierarchy, and other patterns similar to ini file keys. The default
// value is "*" that matches all hosts.
// e.g. "subnet.client*" or "host* router[0..3]" or "area*.*.host[0]"
//
// - @names
// Optional selector attribute that specifies a list of interface name
// patterns. Only interfaces with the specified names are affected. The
// default value is "*" that matches all interfaces.
// e.g. "eth* ppp0" or "*"
//
// - @towards
// Optional selector attribute that specifies a list of host name patterns.
// Only interfaces connected towards the specified hosts are affected. The
// specified name will be matched against the names of hosts that are on
// the same LAN with the one that is being configured. This works even if
// there's a switch between the configured host and the one specified here.
// For wired networks it might be easier to specify this parameter instead
// of specifying the interface names. The default value is "*".
// e.g. "ap" or "server" or "client*"
//
// - @among
// Optional selector attribute that specifies a list of host name patterns.
// Only interfaces in the specified hosts connected towards the specified
// hosts are affected.
// The 'among="X Y Z"' is same as 'hosts="X Y Z" towards="X Y Z"'.
//
// - @address
// Optional parameter attribute that limits the range of assignable
// addresses. Wildcards are allowed with using 'x' as part of the address
// in place of a byte. Unspecified parts will be filled automatically be
// the configurator. The default value "" means that the address will not
// be configured. Unconfigured interfaces still have allocated addresses
// in their subnets allowing them to become configured later very easily.
// e.g. "192.168.1.1" or "10.0.x.x"
//
// - @netmask
// Optional parameter attribute that limits the range of assignable
// netmasks. Wildcards are allowed with using 'x' as part of the netmask
// in place of a byte. Unspecified parts will be filled automatically be
// the configurator. The default value "" means that any netmask can be
// configured.
// e.g. "255.255.255.0" or "255.255.x.x" or "255.255.x.0"
//
// - @mtu number
// Optional parameter attribute to set the MTU parameter in the interface.
// When unspecified the interface parameter is left unchanged.
//
// - @metric number
// Optional parameter attribute to set the Metric parameter in the interface.
// When unspecified the interface parameter is left unchanged.
//
// - @groups
// Optional parameter attribute; it may contain a list of (multicast)
// IP addresses that will be added to the multicast groups of the interface.
// See also the <multicast-group> element.
//
// - @add-static-route
// Optional bool parameter (default=true).
// Add static route to the routing table.
//
// - @add-default-route
// Optional bool parameter (default=true).
// Add default route to the routing table if the node has only one non-loopback interface.
//
// - @add-subnet-route
// Optional bool parameter (default=true).
// Add subnet route to the routing table.
//
// - <wireless>
// The wireless element specifies the members of a wireless network. It is
// primarily useful when the members cannot be automatically determined using
// the SSID parameters.
//
// - @id (optional)
// identifies wireless network, unique value used if missed
//
// - @hosts
// Optional selector attribute that specifies a list of host name patterns.
// Only interfaces in the specified hosts are affected. The default value
// is "*" that matches all hosts.
//
// - @interfaces
// Optional selector attribute that specifies a list of interface name
// patterns. Only interfaces with the specified names are affected. The
// default value is "*" that matches all interfaces.
//
// - <multicast-group>
// The multicast group element provides multicast network addresses for one
// or more interfaces in the network.
//
// - @hosts
// Optional selector attribute that specifies a list of host name patterns.
// Only interfaces in the specified hosts are affected. The default value
// is "*" that matches all hosts.
//
// - @interfaces
// Optional selector attribute that specifies a list of interface name
// patterns. Only interfaces with the specified names are affected. The
// default value is "*" that matches all interfaces.
//
// - @towards
// Optional selector attribute that specifies a list of host name patterns.
// Only interfaces connected towards the specified hosts are affected.
// The default value is "*".
//
// - @among
// Optional selector attribute that specifies a list of host name patterns.
// Only interfaces in the specified hosts connected towards the specified
// hosts are affected.
// The 'among="X Y Z"' is same as 'hosts="X Y Z" towards="X Y Z"'.
//
// - @address
// Mandatory parameter attribute that specifies a list of multicast group
// addresses to be assigned. Values must be selected from the valid range
// of multicast addresses.
// e.g. "224.0.0.1 224.0.1.33"
//
// - <route>
// The route element provides routing table entries for multiple nodes
// in the network. The selector attributes limit the scope where the route
// element has effects.
//
// - @hosts
// Optional selector attribute that specifies a list of host name patterns.
// Only routing tables in the specified hosts are affected. The default
// value "" means all hosts will be affected.
// e.g. "host* router[0..3]"
//
// - @destination
// Optional parameter attribute that specifies the destination address in
// the route (L3AddressResolver syntax). The default value is "*".
// e.g. "192.168.1.1" or "subnet.client[3]" or "subnet.server(ipv4)" or "*"
//
// - @netmask
// Optional parameter attribute that specifies the netmask in the route.
// The default value is "*".
// e.g. "255.255.255.0" or "/29" or "*"
//
// - @gateway
// Optional parameter attribute that specifies the gateway (next-hop)
// address in the route (L3AddressResolver syntax). When unspecified
// the interface parameter must be specified. The default value is "*".
// e.g. "192.168.1.254" or "subnet.router" or "*"
//
// - @interface
// Optional parameter attribute that specifies the output interface name
// in the route. When unspecified the gateway parameter must be specified.
// This parameter has no default value.
// e.g. "eth0"
//
// - @metric
// Optional parameter attribute that specifies the metric in the route.
// The default value is 0.
//
// - <multicast-route>
// The multicast-route elements add entries to multicast routing tables.
//
// - @hosts
// Optional selector attribute that specifies a list of host name patterns.
// Only routing tables in the specified hosts are affected.
// e.g. "host* router[0..3]"
//
// - @source
// Optional parameter attribute that specifies the address of the source
// network. The default value is "*" that matches all sources.
//
// - @netmask
// Optional parameter attribute that specifies the netmask of the source
// network. The default value is "*" that matches all sources.
//
// - @groups
// Optional List of IPv4 multicast addresses specifying the groups this entry
// applies to. The default value is "*" that matches all multicast groups.
// e.g. "225.0.0.1 225.0.1.2".
//
// - @metric
// Optional parameter attribute that specifies the metric in the route.
//
// - @parent
// Optional parameter attribute that specifies the name of the interface
// the multicast datagrams are expected to arrive. When a datagram arrives
// on the parent interface, it will be forwarded towards the child interfaces;
// otherwise it will be dropped. The default value is the interface on the
// shortest path towards the source of the datagram.
//
// - @children
// Mandatory parameter attribute that specifies a list of interface name
// patterns:
// - a name pattern (e.g. "ppp*") matches the name of the interface
// - a 'towards' pattern (starting with ">", e.g. ">router*") matches the interface
// by naming one of the neighbour nodes on its link.
// Incoming multicast datagrams are forwarded to each child interface except the
// one they arrived in.
//
// - <autoroute>
// The autoroute element specifies parameters for the automatic static routing.
// If this element is not specified then the configurator assumes a default.
// The default specifies that all routing tables will be modified and all the
// shortest path to all interfaces will be computed.
//
// - @sourceHosts
// Optional selector attribute that specifies a list of host full path patterns.
// It determines the set of routing tables that will be modified. The default
// value is "**".
//
// - @destinationInterfaces
// Optional parameter attribute that specifies a list of interface full path
// patterns. It determines the set of destination interfaces for which the
// shortest path will be computed. The default value is "**".
//
// - @metric
// Optional parameter attribute that determines the metric that is used to
// compute the shortest paths. Valid values are: "hopCount", "delay", "dataRate",
// and "errorRate". The default value is "hopCount".
//
// - <node>
// The node optional subelement specifies cost parameters for the shortest
// path algorithm. If this subelement is not specified then the configurator
// determines cost by default according to the selected metric.
//
// - @hosts
// Mandatory selector attribute that specifies a list of node full path
// patterns. It determines the affected set of nodes.
//
// - @cost
// Mandatory parameter attribute that specifies the cost. Valid values are
// "infinite" and numbers.
//
// - <link>
// The node subelement specifies cost parameters for the shortest path algorithm.
// If this subelement is not specified then the configurator determines link
// cost by default according to the selected metric.
//
// - @interfaces
// Mandatory selector attribute that specifies a list of interface full
// path patterns. It determines the affected set of links connected to
// the given interfaces.
//
// - @cost
// Mandatory parameter attribute that specifies the cost. Valid values are
// "infinite" and numbers.
//
simple IPv4NetworkConfigurator extends NetworkConfiguratorBase
{
parameters:
@class(IPv4NetworkConfigurator);
@display("i=block/cogwheel_s");
xml config = default(xml("<config><interface hosts='**' address='10.x.x.x' netmask='255.x.x.x'/></config>")); // XML configuration parameters for IP address assignment and adding manual routes
bool assignAddresses = default(true); // assign IP addresses to all interfaces in the network
bool assignDisjunctSubnetAddresses = default(true); // avoid using the same address prefix and netmask on different links when assigning IP addresses to interfaces
bool addStaticRoutes = default(true); // add static routes to the routing tables of all nodes to route to all destination interfaces (only where applicable; turn off when config file contains manual routes)
bool addDefaultRoutes = default(true); // add default routes if all routes from a source node go through the same gateway (used only if addStaticRoutes is true)
bool addSubnetRoutes = default(true); // add subnet routes instead of destination interface routes (only where applicable; used only if addStaticRoutes is true)
bool optimizeRoutes = default(true); // optimize routing tables by merging routes, the resulting routing table might route more packets than the original (used only if addStaticRoutes is true)
bool dumpTopology = default(false); // print extracted network topology to the module output
bool dumpLinks = default(false); // print recognized network links to the module output
bool dumpAddresses = default(false); // print assigned IP addresses for all interfaces to the module output
bool dumpRoutes = default(false); // print configured and optimized routing tables for all nodes to the module output
string dumpConfig = default(""); // write configuration into the given config file that can be fed back to speed up subsequent runs (network configurations)
}