| | 1 | = Topology Description Language = |
| | 2 | |
| | 3 | We introduce topdl (topology description language) as the language for topology description. Our goal is to have a resource independent representation of communicating elements that can be used for experimentation. The basic model underlying topdl is a set of abstract elements that can communicate. To represent topologies at the level of detail that testbeds need to allocate resources and configure hardware, simple topdl descriptions are specialized by adding attributes. |
| | 4 | |
| | 5 | Topdl is testbed independent and, in principle, different testbeds may treat the same topdl slightly differently. Different testbeds may interpret attributes differently. This document will explain how DETER tools interpret the topdl in an effort to encourage interoperability, |
| | 6 | |
| | 7 | There are two primitives in topdl: |
| | 8 | |
| | 9 | '''Elements''':: |
| | 10 | Active resources in the experiment: computers, routers, devices that are programmable. These are subclassed for common kinds of elements |
| | 11 | '''Substrate''':: |
| | 12 | A communications medium to which elements have access. This may be a wired LAN, a shared communication frequency, or may represent the fact that the elements share a line of sight. |
| | 13 | |
| | 14 | The point of contact between these primitives is: |
| | 15 | |
| | 16 | '''Interface''':: |
| | 17 | An indication that a particular element can communicate on one or more substrates. An interface appears on exactly one element. |
| | 18 | |
| | 19 | These are deliberately unconstrained, but are an attempt to capture the idea that most network experiments are about things that can talk to other things in constrained ways. |
| | 20 | |
| | 21 | Each subclass and substrate has parameters which set the specifics of that object. For example, the computer subclass of elements can be parameterized by the operating system, the CPU information, the required software, and the storage (memory, disk, etc) that are required. Additional attribute/value pairs (strings) can be attached to the computer (and to some of the parameters) to specialize it for specific access controllers or other applications. |
| | 22 | |
| | 23 | Substrates and interfaces can also have attributes attached, but are characterized by the communication capacity and latency of the substrate, though neither needs to be specified if unimportant. |
| | 24 | |
| | 25 | By specializing these primitives, topdl can represent many network topologies. A traditional enterprise configuration can be represented as computer elements for each desktop connected by substrates that represent the LANs that are also interfaces to routers and firewalls that model the system. A system of nodes sharing the same wireless infrastructure share interfaces on the same wireless substrate. Machines that can talk on more than one substrate using the same interface - for example a multi-frequency radio - are specified with one interface on several substrates, one for each frequency of interest. |
| | 26 | |
| | 27 | == Representation == |
| | 28 | |
| | 29 | Topdl is encoded in XML. Each substrate and element are encoded as XML elements with interfaces encoded in the elements. Attributes are attached to any of the XML elements. A full [source:browser/wsdl/topdl.xsd XSD encoding] is available for qutomatically generating access code. This section will show some simple examples. |
| | 30 | |
| | 31 | |
| | 32 | |
| | 33 | |
| | 34 | == Substrate == |
| | 35 | |
| | 36 | Substrates are parameterized by: |
| | 37 | |
| | 38 | '''Name''':: |
| | 39 | A unique name to tie interfaces to this substrate. |
| | 40 | '''Capacity''':: |
| | 41 | The rate of information exchange on this substrate. May be given as an average or peak rate. |
| | 42 | '''Latency''':: |
| | 43 | The time required for information to cross this substrate. May be an average or a peak. |
| | 44 | |
| | 45 | An interface may also have those parameters, in which case the element to which the interface is attached is limited by the lower of the interface or substrate values. Corner cases, such as a maximum less than an average are dealt with as errors by the system taking the topology as input. |
| | 46 | |
| | 47 | == Elements == |
| | 48 | |
| | 49 | There are several subclasses in use. The generic element class has no specific parameters, only unstandardized attributes. |
| | 50 | |
| | 51 | Current subclasses include: |
| | 52 | |
| | 53 | ===== Computer ===== |
| | 54 | |
| | 55 | In addition to unstandardized attributes, computers are parameterized by: |
| | 56 | |
| | 57 | '''Name''':: |
| | 58 | An identifier for the computer, primarilty useful to researchers directly. |
| | 59 | '''CPU''':: |
| | 60 | They type and number of CPUs required |
| | 61 | '''Operating System''':: |
| | 62 | Including version, distribution, and patchlevel |
| | 63 | '''Storage''':: |
| | 64 | Amount of persistent and transient storage - usually disk and memory, but new technologues are possible. |
| | 65 | '''Software''':: |
| | 66 | The software to install and the location in the file system. A URI may be given for the software distribution. |
| | 67 | '''Interfaces''':: |
| | 68 | Parameterized as above |
| | 69 | |
| | 70 | ===== Segment ===== |
| | 71 | |
| | 72 | A sgement is an allocation (or future allocation) of resources to a federated experiment. They are useful placeholders in establishing connectivity across a federant that acts as a transit network provider between federants. The optional parameters include: |
| | 73 | |
| | 74 | '''Name''':: |
| | 75 | Name of the segment. Primarily useful to reserachers or debuggers. |
| | 76 | '''Type''':: |
| | 77 | Access controller type, e.g., emulab. |
| | 78 | '''URI''':: |
| | 79 | The URI at which the access controller can be found. |
| | 80 | '''Interfaces''':: |
| | 81 | The parameterized as above |
| | 82 | |
| | 83 | === Attribute Conventions === |
| | 84 | |
| | 85 | Though we expect attribute conventions to evolve, currently the following entension attributes are understood. Several are being used to bridge from the existing experiment description language to current topdl, and are somewhat emulab-specific. |
| | 86 | |
| | 87 | '''failureaction''':: |
| | 88 | What the underlying testbed should do if this node cannot be reserved or configured. Choices are '''fatal''' or '''nonfatal'''. |
| | 89 | '''osid''':: |
| | 90 | The local emulab operating system image. This will become less common as more plugins are capable of mapping from operating system parameters into local image name, but can be used as a low-level escape. |
| | 91 | '''testbed''':: |
| | 92 | The experiment controller's name for the testbed this node will be placed on. This is in place to allow native topdl descriptions to be accepted by experiment controllers - it's not needed by access controllers. As the full experiment description language evolves, this may move into som part of that language or become a standard topdl attribute. |
| | 93 | '''type''':: |
| | 94 | The local emulab machine type. This will become less common as more plugins are capable of mapping from CPU/storage parameters into local machine type, but can be used as a low-level escape. |
| | 95 | |
| | 96 | The following attributes appear in topology descriptions for use by local emulabs in configuration: |
| | 97 | |
| | 98 | '''active''':: |
| | 99 | Attached to a portal computer. If true, this portal initiates connections to the peer. |
| | 100 | '''dragon_vlan''':: |
| | 101 | If assigned, the VLAN tag on which this node will communicate. The name will change. |
| | 102 | '''domain''':: |
| | 103 | Attached to a portal computer. This is the DNS domain of the local emulab resources. |
| | 104 | '''ip4_address''':: |
| | 105 | The IP version 4 address of the interface that the attribute is attached to as a dotted decimal. |
| | 106 | '''masterdomain''':: |
| | 107 | Attached to a portal computer. The DNS domain of the emulab exporting its environment. Used to connect services and forward traffic. |
| | 108 | '''masterexperiment''':: |
| | 109 | Attached to a portal computer. The emulab project/experiment name of the environment being exported from the master testbed. Used to connect services. |
| | 110 | '''masteruser''':: |
| | 111 | Attached to a portal computer. The emulab user that alloacted the exported environment on the master. User to connect to services. |
| | 112 | '''peer''':: |
| | 113 | Attached to a portal computer. DNS name of the portal node used to bridge services and traffic. |
| | 114 | '''peer_segment''':: |
| | 115 | Attached to a portal computer. Fedid of the allocation in which the peer portal lives. |
| | 116 | '''portal''':: |
| | 117 | True if this is a portal computer added by the experiment controller |
| | 118 | '''portal_type'':: |
| | 119 | Attached to a portal computer. Specifies whether this portal exports services, forwards traffic, or both. |
| | 120 | '''smbshare''':: |
| | 121 | Attached to a portal computer. The SMB/CIFS share used to export local file systems (if any) |
| | 122 | '''startup''':: |
| | 123 | The startup command to federate the computer. |
| | 124 | |
| | 125 | |
| | 126 | |
| | 127 | === Example === |
| | 128 | |
| | 129 | As an example, here is the experiment description from the [FeddAbout#FederatedExperimentCreation architecture discussion,] rendered in topdl. |
| | 130 | |
| | 131 | {{{ |
| | 132 | <experiment> |
| | 133 | <substrates> |
| | 134 | <name>link0</name> |
| | 135 | <capacity> |
| | 136 | <rate>100000</rate> |
| | 137 | <kind>max</kind> |
| | 138 | </capacity> |
| | 139 | </substrates> |
| | 140 | <substrates> |
| | 141 | <name>lan0</name> |
| | 142 | <capacity> |
| | 143 | <rate>100000</rate> |
| | 144 | <kind>max</kind> |
| | 145 | </capacity> |
| | 146 | </substrates> |
| | 147 | <substrates> |
| | 148 | <name>link1</name> |
| | 149 | <capacity> |
| | 150 | <rate>100000</rate> |
| | 151 | <kind>max</kind> |
| | 152 | </capacity> |
| | 153 | </substrates> |
| | 154 | <elements> |
| | 155 | <computer> |
| | 156 | <name>d</name> |
| | 157 | <attribute> |
| | 158 | <attribute>type</attribute> |
| | 159 | <value>bvx2200</value> |
| | 160 | </attribute> |
| | 161 | <os> |
| | 162 | <attribute> |
| | 163 | <attribute>osid</attribute> |
| | 164 | <value>FC6-SMB</value> |
| | 165 | </attribute> |
| | 166 | </os> |
| | 167 | <interface> |
| | 168 | <substrate>lan0</substrate> |
| | 169 | <capacity> |
| | 170 | <rate>100000</rate> |
| | 171 | <kind>max</kind> |
| | 172 | </capacity> |
| | 173 | </interface> |
| | 174 | <attribute> |
| | 175 | <attribute>testbed</attribute> |
| | 176 | <value>ucb</value> |
| | 177 | </attribute> |
| | 178 | <attribute> |
| | 179 | <attribute>failureaction</attribute> |
| | 180 | <value>fatal</value> |
| | 181 | </attribute> |
| | 182 | </computer> |
| | 183 | </elements> |
| | 184 | <elements> |
| | 185 | <computer> |
| | 186 | <name>e</name> |
| | 187 | <attribute> |
| | 188 | <attribute>type</attribute> |
| | 189 | <value>bvx2200</value> |
| | 190 | </attribute> |
| | 191 | <os> |
| | 192 | <attribute> |
| | 193 | <attribute>osid</attribute> |
| | 194 | <value>FC6-SMB</value> |
| | 195 | </attribute> |
| | 196 | </os> |
| | 197 | <interface> |
| | 198 | <substrate>lan0</substrate> |
| | 199 | <capacity> |
| | 200 | <rate>100000</rate> |
| | 201 | <kind>max</kind> |
| | 202 | </capacity> |
| | 203 | </interface> |
| | 204 | <attribute> |
| | 205 | <attribute>testbed</attribute> |
| | 206 | <value>ucb</value> |
| | 207 | </attribute> |
| | 208 | <attribute> |
| | 209 | <attribute>failureaction</attribute> |
| | 210 | <value>fatal</value> |
| | 211 | </attribute> |
| | 212 | </computer> |
| | 213 | </elements> |
| | 214 | <elements> |
| | 215 | <computer> |
| | 216 | <name>a</name> |
| | 217 | <attribute> |
| | 218 | <attribute>type</attribute> |
| | 219 | <value>pc</value> |
| | 220 | </attribute> |
| | 221 | <os> |
| | 222 | <attribute> |
| | 223 | <attribute>osid</attribute> |
| | 224 | <value>FC6-STD</value> |
| | 225 | </attribute> |
| | 226 | </os> |
| | 227 | <interface> |
| | 228 | <substrate>link0</substrate> |
| | 229 | <capacity> |
| | 230 | <rate>100000</rate> |
| | 231 | <kind>max</kind> |
| | 232 | </capacity> |
| | 233 | </interface> |
| | 234 | <attribute> |
| | 235 | <attribute>testbed</attribute> |
| | 236 | <value>deter</value> |
| | 237 | </attribute> |
| | 238 | <attribute> |
| | 239 | <attribute>failureaction</attribute> |
| | 240 | <value>fatal</value> |
| | 241 | </attribute> |
| | 242 | </computer> |
| | 243 | </elements> |
| | 244 | <elements> |
| | 245 | <computer> |
| | 246 | <name>b</name> |
| | 247 | <attribute> |
| | 248 | <attribute>type</attribute> |
| | 249 | <value>pc</value> |
| | 250 | </attribute> |
| | 251 | <os> |
| | 252 | <attribute> |
| | 253 | <attribute>osid</attribute> |
| | 254 | <value>FC6-STD</value> |
| | 255 | </attribute> |
| | 256 | </os> |
| | 257 | <interface> |
| | 258 | <substrate>link0</substrate> |
| | 259 | <capacity> |
| | 260 | <rate>100000</rate> |
| | 261 | <kind>max</kind> |
| | 262 | </capacity> |
| | 263 | </interface> |
| | 264 | <interface> |
| | 265 | <substrate>link1</substrate> |
| | 266 | <capacity> |
| | 267 | <rate>100000</rate> |
| | 268 | <kind>max</kind> |
| | 269 | </capacity> |
| | 270 | </interface> |
| | 271 | <attribute> |
| | 272 | <attribute>testbed</attribute> |
| | 273 | <value>deter</value> |
| | 274 | </attribute> |
| | 275 | <attribute> |
| | 276 | <attribute>failureaction</attribute> |
| | 277 | <value>fatal</value> |
| | 278 | </attribute> |
| | 279 | </computer> |
| | 280 | </elements> |
| | 281 | <elements> |
| | 282 | <computer> |
| | 283 | <name>c</name> |
| | 284 | <attribute> |
| | 285 | <attribute>type</attribute> |
| | 286 | <value>bvx2200</value> |
| | 287 | </attribute> |
| | 288 | <os> |
| | 289 | <attribute> |
| | 290 | <attribute>osid</attribute> |
| | 291 | <value>FC6-SMB</value> |
| | 292 | </attribute> |
| | 293 | </os> |
| | 294 | <interface> |
| | 295 | <substrate>lan0</substrate> |
| | 296 | <capacity> |
| | 297 | <rate>100000</rate> |
| | 298 | <kind>max</kind> |
| | 299 | </capacity> |
| | 300 | </interface> |
| | 301 | <interface> |
| | 302 | <substrate>link1</substrate> |
| | 303 | <capacity> |
| | 304 | <rate>100000</rate> |
| | 305 | <kind>max</kind> |
| | 306 | </capacity> |
| | 307 | </interface> |
| | 308 | <attribute> |
| | 309 | <attribute>testbed</attribute> |
| | 310 | <value>ucb</value> |
| | 311 | </attribute> |
| | 312 | <attribute> |
| | 313 | <attribute>failureaction</attribute> |
| | 314 | <value>fatal</value> |
| | 315 | </attribute> |
| | 316 | </computer> |
| | 317 | </elements> |
| | 318 | </experiment> |
| | 319 | }}} |
