Changes between Version 2 and Version 3 of TopDl


Ignore:
Timestamp:
Oct 4, 2012 3:42:20 PM (12 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TopDl

    v2 v3  
    2727== Representation ==
    2828
    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.
     29This section describes what one can say in topdl.  We will be looking at the low-level encoding of the structures, but few experimenters write topdl directly.  We have programmatic libraries and facilities to translate from other representations.  We believe it is helpful to see the basic structures.
     30
     31Topdl 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. 
     32
     33This section will illustrate the encoding through some simple examples.
    3034
    3135This simple, two-computer topology:
    3236
    33 
    34 
    35 
    36 == Substrate ==
    37 
    38 Substrates are parameterized by:
     37[[Image(two.png)]]
     38
     39Can be represented in topdl as:
     40
     41{{{
     42<experiment>
     43 <version>1.0</version>
     44
     45 <!-- Substrate that links the two computers -->
     46 <substrates>
     47  <name>link0</name>
     48 </substrates>
     49
     50
     51 <!-- A computer element named a with an interface on the link0 substrate -->
     52 <elements>
     53  <computer>
     54   <name>a</name>
     55   <interface>
     56    <substrate>link0</substrate>
     57    <name>inf000</name>
     58   </interface>
     59  </computer>
     60 </elements>
     61
     62 <!-- A computer element named b with an interface on the link0 substrate -->
     63 <elements>
     64  <computer>
     65   <name>b</name>
     66   <interface>
     67    <substrate>link0</substrate>
     68    <name>inf000</name>
     69   </interface>
     70  </computer>
     71 </elements>
     72</experiment>
     73
     74}}}
     75
     76=== Substrates ===
     77
     78That topdl represents a very simple representation of the network, with most of the details unbound.  Both substrates and elements can be described in more detail.  We start with substrates.
     79
     80One can extend the representation above by adding parameters to the substrate.  To specify that the interconnection is a 100Mbps link, we add the substrate capacity parameter to link0:
     81
     82{{{
     83<!-- excerpt -->
     84
     85 <substrates>
     86  <name>link0</name>
     87  <capacity>
     88    <rate>100000.0</rate>
     89    <kind>max</kind>
     90  </capacity>
     91 </substrates>
     92
     93<!-- excerpt -->
     94}}}
     95
     96In general, substrates are parameterized by:
    3997
    4098    '''Name'''::
    … …  
    47105An 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.
    48106
    49 == Elements ==
    50 
    51 There are several subclasses in use.  The generic element class has no specific parameters, only unstandardized attributes.
    52 
    53 Current subclasses include:
     107Only the name is required.
     108
     109=== Elements ===
     110
     111Elements are sub-classed and each subclass has more parameters defined.  Extending our example further, an experimenter can choose an operating system - e.g. Ubuntu Linux 12.04 (kernelversion 3.0.0.26) for a computer:
     112
     113{{{
     114<!--excerpt -->
     115<!-- A computer element named a with an interface on the link0 substrate -->
     116 <elements>
     117  <computer>
     118   <name>a</name>
     119   <interface>
     120    <substrate>link0</substrate>
     121    <name>inf000</name>
     122   </interface>
     123   <os>
     124     <name>Linux</name>
     125     <version>3.0.0.26</version>
     126     <distribution>Ubuntu</distribution>
     127     <distributionversion>12.04</distributionversion>
     128   </os>
     129  </computer>
     130 </elements>
     131<!--excerpt -->
     132}}}
    54133
    55134===== Computer =====
    56135
    57 In addition to unstandardized attributes, computers are parameterized by:
     136Computers are the most common element subclass used by DETER.  They are parameterized by:
    58137
    59138 '''Name'''::
    … …  
    62141   They type and number of CPUs required
    63142 '''Operating System'''::
    64   Including version, distribution, and patchlevel
     143  Including version, distribution
    65144 '''Storage'''::
    66145  Amount of persistent and transient storage - usually disk and memory, but new technologues are possible.
    … …  
    68147  The software to install and the location in the file system.  A URI may be given for the software distribution.
    69148 '''Interfaces'''::
    70   Parameterized as above
     149  See below
     150
     151All these parameters, except the name, are optional.
    71152
    72153===== Segment =====
    73154
    74 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:
     155A sgement is an allocation (or future allocation) of resources to a federated experiment, researchers rarely use these directly, but they are included as an example of a non-computer element.  They are useful placeholders in establishing connectivity across a federant that acts as a transit network provider between federants.  The optional parameters include:
    75156
    76157 '''Name'''::
    … …  
    81162  The URI at which the access controller can be found.
    82163 '''Interfaces'''::
    83   The parameterized as above
     164  See below
     165
     166===
     167
     168Interfaces are attached to elements.  Each is parameterized as follows:
     169
     170 '''Name'''::
     171  A unique name for the interface.  (Unique within the interface)
     172 '''Substrates'''::
     173  A list of substrate names to which the interface is attached
     174 '''Capacity''' and '''Latency'''::
     175  These are overrides to the substrate values, as described above.  Both are optional.
     176
     177== Attributes ==
     178
     179The parameters above cover many of the common cases for describing topology elements, but it is helpful to allow applications to attach inormation to topology descriptions, either for tehir use or for the testbed to interpret.  Elements, substrates and interfaces can all have attributes directly attached to them.  In fact, many parameters and parameter blocks can have attributes attached as well.
     180
     181Attribues are name/value pairs attached to a topdl entity.  There is no limit as to how many can be attached, but each must have a unique name per entity.  APplications are encouraged to prefix attributes with their application name.
     182
     183We list some attributes currently respected by the DETER toolchains.
    84184
    85185=== Attribute Conventions ===
    86186
    87 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.
     187Though 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 DETER-specific.
    88188
    89189 '''failureaction'''::
    … …  
    96196  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.
    97197
    98 The following attributes appear in topology descriptions for use by local emulabs in configuration:
     198The following attributes appear in topology descriptions for use by local DETER-like testbeds in configuration:
    99199
    100200 '''active'''::
    … …  
    126226 
    127227
    128 
    129 === Example ===
    130 
    131 As an example, here is the experiment description from the [FeddAbout#FederatedExperimentCreation architecture discussion,] rendered in topdl.
    132 
    133 {{{
    134 <experiment>
    135  <substrates>
    136   <name>link0</name>
    137   <capacity>
    138    <rate>100000</rate>
    139    <kind>max</kind>
    140   </capacity>
    141  </substrates>
    142  <substrates>
    143   <name>lan0</name>
    144   <capacity>
    145    <rate>100000</rate>
    146    <kind>max</kind>
    147   </capacity>
    148  </substrates>
    149  <substrates>
    150   <name>link1</name>
    151   <capacity>
    152    <rate>100000</rate>
    153    <kind>max</kind>
    154   </capacity>
    155  </substrates>
    156  <elements>
    157   <computer>
    158    <name>d</name>
    159    <attribute>
    160     <attribute>type</attribute>
    161     <value>bvx2200</value>
    162    </attribute>
    163    <os>
    164     <attribute>
    165      <attribute>osid</attribute>
    166      <value>FC6-SMB</value>
    167     </attribute>
    168    </os>
    169    <interface>
    170     <substrate>lan0</substrate>
    171     <capacity>
    172      <rate>100000</rate>
    173      <kind>max</kind>
    174     </capacity>
    175    </interface>
    176    <attribute>
    177     <attribute>testbed</attribute>
    178     <value>ucb</value>
    179    </attribute>
    180    <attribute>
    181     <attribute>failureaction</attribute>
    182     <value>fatal</value>
    183    </attribute>
    184   </computer>
    185  </elements>
    186  <elements>
    187   <computer>
    188    <name>e</name>
    189    <attribute>
    190     <attribute>type</attribute>
    191     <value>bvx2200</value>
    192    </attribute>
    193    <os>
    194     <attribute>
    195      <attribute>osid</attribute>
    196      <value>FC6-SMB</value>
    197     </attribute>
    198    </os>
    199    <interface>
    200     <substrate>lan0</substrate>
    201     <capacity>
    202      <rate>100000</rate>
    203      <kind>max</kind>
    204     </capacity>
    205    </interface>
    206    <attribute>
    207     <attribute>testbed</attribute>
    208     <value>ucb</value>
    209    </attribute>
    210    <attribute>
    211     <attribute>failureaction</attribute>
    212     <value>fatal</value>
    213    </attribute>
    214   </computer>
    215  </elements>
    216  <elements>
    217   <computer>
    218    <name>a</name>
    219    <attribute>
    220     <attribute>type</attribute>
    221     <value>pc</value>
    222    </attribute>
    223    <os>
    224     <attribute>
    225      <attribute>osid</attribute>
    226      <value>FC6-STD</value>
    227     </attribute>
    228    </os>
    229    <interface>
    230     <substrate>link0</substrate>
    231     <capacity>
    232      <rate>100000</rate>
    233      <kind>max</kind>
    234     </capacity>
    235    </interface>
    236    <attribute>
    237     <attribute>testbed</attribute>
    238     <value>deter</value>
    239    </attribute>
    240    <attribute>
    241     <attribute>failureaction</attribute>
    242     <value>fatal</value>
    243    </attribute>
    244   </computer>
    245  </elements>
    246  <elements>
    247   <computer>
    248    <name>b</name>
    249    <attribute>
    250     <attribute>type</attribute>
    251     <value>pc</value>
    252    </attribute>
    253    <os>
    254     <attribute>
    255      <attribute>osid</attribute>
    256      <value>FC6-STD</value>
    257     </attribute>
    258    </os>
    259    <interface>
    260     <substrate>link0</substrate>
    261     <capacity>
    262      <rate>100000</rate>
    263      <kind>max</kind>
    264     </capacity>
    265    </interface>
    266    <interface>
    267     <substrate>link1</substrate>
    268     <capacity>
    269      <rate>100000</rate>
    270      <kind>max</kind>
    271     </capacity>
    272    </interface>
    273    <attribute>
    274     <attribute>testbed</attribute>
    275     <value>deter</value>
    276    </attribute>
    277    <attribute>
    278     <attribute>failureaction</attribute>
    279     <value>fatal</value>
    280    </attribute>
    281   </computer>
    282  </elements>
    283  <elements>
    284   <computer>
    285    <name>c</name>
    286    <attribute>
    287     <attribute>type</attribute>
    288     <value>bvx2200</value>
    289    </attribute>
    290    <os>
    291     <attribute>
    292      <attribute>osid</attribute>
    293      <value>FC6-SMB</value>
    294     </attribute>
    295    </os>
    296    <interface>
    297     <substrate>lan0</substrate>
    298     <capacity>
    299      <rate>100000</rate>
    300      <kind>max</kind>
    301     </capacity>
    302    </interface>
    303    <interface>
    304     <substrate>link1</substrate>
    305     <capacity>
    306      <rate>100000</rate>
    307      <kind>max</kind>
    308     </capacity>
    309    </interface>
    310    <attribute>
    311     <attribute>testbed</attribute>
    312     <value>ucb</value>
    313    </attribute>
    314    <attribute>
    315     <attribute>failureaction</attribute>
    316     <value>fatal</value>
    317    </attribute>
    318   </computer>
    319  </elements>
    320 </experiment>
    321 }}}