Topology API Overview

The topology import/export API allows you to programmatically import/export a network topology into/out of an Riverbed application from/to a self-describing text file that follows the Topology Exchange File (TEF) format. A TEF file includes information about nodes and links in the network. To make the TEF file format flexible enough to be used for different types of networks, the file also includes meta-information about how the nodes and links are described in the file.

Topology Exchange File (TEF) Format

The file format is formally described below.

  • The \t stands for a tab character
  • Terms within a <> pair must be a string or number that does not contain any \t character
  • Text outside the <> or {} pairs are literal keywords (and must be spelled exactly as shown)
  • Any line that starts with a # is a comment line and is ignored

Figure 20: Topology Exchange File (TEF) Format

Number of Node Attributes:  <number of node attributes>
# This section describes which node attributes are to be imported
{Node Attribute Description Section}
Number of Nodes:  <number of nodes in network>
# Here starts the attribute values for the nodes
<node1 name>\t<node1 model>\t<node1 attribute1 value>\t<node1 attribute2 value> …
<node2 name>\t<node2 model>\t<node2 attribute1 value>\t<node2 attribute2 value> …
……
……
Number of Link Attributes: <number of link attributes>
{Link Attribute Description Section}
<link1 name>\t<link1 model>\t<link1 source node name>\t
	<link1 destination node name>\t <link1 attribute1 value>\t
	<link1 attribute2 value> …
<link2 name>\t<link2 model>\t<link2 source node name>\t
	<link2 destination node name>\t <link2 attribute1 value>\t
	<link2 attribute2 value> …
……
……

As shown in Figure 20, a TEF consists of two main sections: one for nodes and one for links. Within the node section, the Node Attribute Description Section defines a schema for the nodes and describes a common subset of the attributes of the nodes. When an application imports the file, it will create the nodes and then set the values of those attributes on each node according to this schema and the attribute values that are in the following lines in the file. More specifically, in the Node Attribute Description Section, each line defines one attribute’s name and type.

For example, suppose all nodes have x position, y position, and icon name attributes, and we wish to set these values as part of the import operation. The section should be:

icon name: string
x position: double
y position: double

Attributes imported or exported through this feature must be of datatype int, string, or double.

The Number of Nodes line specifies how many nodes the network has. Following that, there is one line for each node, listing the node’s attribute values (in the above case, icon, x position, and y position). Node name and node model values are always listed at the beginning of each line, followed by the attribute values. For example, Figure 21 shows a node section specifying five nodes, where one node’s model is a switch and the other’s is a site.

Figure 21: Example Node Attribute Description Section for a TEF File

Number of Node Attributes : 3
icon name: string
x position: double
y position: double
Number of Nodes: 5
# name,		model,		icon, 			x position, 				y position
node_0		switch		cabletv			-77.370000				39.760000
node_1		site		cabletv			-75.690000				38.490000
node_2		site		cabletv			-76.310000				36.490000
node_3		site		cabletv			-78.440000				36.490000
node_4		site		cabletv			-79.090000				38.510000

When the Imex package is used to import this file, it will create 5 nodes, all of which have icon set to “cabletv” and positions set to the specified numbers.

When using this file format, the network imported is “flat”. That is, all nodes and links are in the top level; no subnets can be created.

Now suppose each node has a new attribute called “cost” that is a double value. Figure 22 shows the previous TEF with this attribute added (note that both the switch and site models must have a double value “cost” attribute for the import to be error-free; otherwise an error message will be generated stating that the package cannot set “cost” for some nodes).

Figure 22: Adding a New Attribute to a TEF File

Number of Node Attributes : 4
icon name: string
x position: double
y position: double
cost: double
Number of Nodes 5
# name,		model,		icon, 			x position, 				y position,			cost
node_0		switch		cabletv			-77.370000				39.760000			1000.0
node_1		site		cabletv			-75.690000				38.490000			2000.0
node_2		site		cabletv			-76.310000				36.490000			2000.0
node_3		site		cabletv			-78.440000				36.490000			2000.0
node_4		site		cabletv			-79.090000				38.510000			2000.0

The links section is very similar to the node section, except that the number of the links is not needed (Imex assumes every line after the Link Attribute Description Section stands for a link). Also there are two additional attributes that are mandatory: source node name and destination node name. The values for these two attributes must be consistent with node names in the node section so that the application can know which two nodes each link connects to. The links are bi-directional. Figure 23 contains a sample link section.

Figure 23: Example Link Attribute Description Section for a TEF File

Number of Link Attributes : 4
Number of Fibers: int
Number of Wavelengths per Fiber : int
Bandwidth per Wavelength (Mbps) : double
Actual Length : double
# name,   model,       source,  dest,   wave,  fibers,  Mbps,      length (km)
duplex_0  fiber_bundle  node_0   node_1  1      4        51.840000  80.000000
duplex_4  SONET         node_0   node_4  1      4        150.40000  80.000000
duplex_1  fiber_bundle  node_1   node_2  1      4        51.840000  80.000000
duplex_2  fiber_bundle  node_2   node_3  1      4        51.840000  80.000000
duplex_3  fiber_bundle  node_3   node_4  1      4        51.840000  80.000000

From the first link line, we can tell there is a link called duplex_0 whose model is “fiber_bundle” and which connects node_0 and node_1. Also, it has 1 wavelength per fiber and 4 fibers. Its bandwidth per wavelength is 51.84 Mbps and its length is 80.0.