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
\tstands for a tab character - Terms within a
<>pair must be a string or number that does not contain any\tcharacter - 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.