Changes between Initial Version and Version 1 of HowTo/WriteOFv3Rspecs


Ignore:
Timestamp:
09/30/11 09:11:20 (9 years ago)
Author:
nriga@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HowTo/WriteOFv3Rspecs

    v1 v1  
     1[[PageOutline]]
     2
     3This page describes how to write [http://www.protogeni.net/trac/protogeni/wiki/RSpecSchema2 GENI compliant] Openflow rspecs. These new rspecs are supported by FOAM, the new Openflow AM. This page also provides instructions and how to convert Expedient rspecs to the new form of rspecs.
     4
     5= Openflow Slivers =
     6In an Openflow Aggregate, an experimenter can control how the packets are forwarded within the network,
     7using a custom controller running in an external compute resource. In the general case an Openflow Aggregate
     8consists of Openflow-enabled devices(e.g. switches) which forward packets based on instructions received by the controllers.
     9
     10The traffic of an Openflow network can be sliced, using matching rules on the traversing packets. A set of rules
     11 that describes part of the passing traffic is called a ''flowspace''. A flowspace can be defined based on the
     12datapath ids (aka dpids) and ports that the packets are going through, and/or based on their headers.
     13Datapath is a virtual network device that is controlled using the Openflow protocol and can forward packets.
     14So for example a switch running an Openflow compatible firmware might be a datapath.
     15
     16More details about how Openflow works and about which fields of the packet headers can be used in flowspaces
     17can be found in the [http://www.openflow.org/documents/openflow-spec-v1.0.0.pdf Openflow Spec 1.0.0] and
     18in the [http://www.openflow.org/ Openflow website].
     19
     20For example a sliver on an Openflow network might request for :
     21    ''"All packets coming in port 5 on datapath 15, and have a source IP address in subnet 10.10.10.0/24."'''
     22
     23= FOAM rspecs =
     24
     25An Openflow rspec is describing the flowspace for an experiment and thus it has ways of
     26describing datapaths, ports and rules to filter packets based on packet headers.
     27
     28FOAM, that is an Openflow Aggregate Manager, is using GENI compliant rspecs, with an Openflow extention(v2).
     29You can find an example rspec [https://openflow.stanford.edu/display/FOAM/rspec here].
     30
     31Here a list of supported tag is provided. The shorthand notations used in the description is:
     32|| ![1]|| An element is mandatory and it can only appear once ||
     33|| [?] || An element is optional, but it can appear at most once ||
     34|| [*] || An element is optional but it can appear multiple times in the rspec   ||
     35|| [+] || An element is mandatory , but it can appear multiple times in the rspec ||
     36
     37=== <openflow:sliver> ===
     38![1] This element contains all the information about the requested sliver.
     39                            ''Attributes''::
     40    * '''description''' : [?] a short description of your experiment
     41    * '''ref''' : [?] A URL pointing to a page describing your project
     42    * '''email''' : [?] user's email address that is used by FOAM to send notifications about the sliver.
     43                           ''Children tags''::
     44    * <openflow:controller> [+]
     45    * <openflow:group> [+]
     46    * <openflow:match> [+]
     47                           '' Parent tags'':: <rspec>
     48
     49=== <openflow:controller> ===
     50[+] This element provides information about the controller for the sliver.
     51It is MANDATORY to have one and only one primary controller.
     52              ''Attributes''::
     53   * '''url''' : ![1] the information about where your openflow controller is running in the form of tcp:<hostname/ip address>:<tcp port>. Examples : tcp:10.0.0.1:6633 , tcp:myctrl.geni.net:6637
     54   * '''type''' : ![1] this defines what type of controller this is. There can be only three types of controllers:
     55      * '''primary''' : this is the controller that handles the network traffic and makes decisions about how packets should be forwarded. [MANDATORY to have one and only one primary controller].
     56      * '''monitor''' : a monitor controller can not make decisions about how packets are forwarded, but it has the capability of creating and sending packets in the network, e.g. LLDP packets for performing topology discovery. [An rspec can have more than one monitor controllers]
     57      * backup : a backup controller is used if the primary controller goes down, multiple backup controllers can be defined and they are used in the order they appear in the request rspec. Right now defining backup monitors will have no effect. [An rspec can have more than one backup controllers]
     58               ''Children tags'':: None
     59               '' Parent tags'':: <openflow:sliver>
     60
     61=== <openflow:group> ===
     62[+] This tag is used to group multiple datapath resources together, so they can be used as a bundle in defining matches.
     63So if this sliver is interested in packets that go through some ports on datapaths A, B and C then the group should contain three <openflow:datapath> elements on for each of A, B and C. 
     64                          ''Attributes''::
     65  * '''name''' : ![1] this is the name of the group. 
     66                     ''Children tags'':: <openflow:datapath>[*], a group element with no children implies ALL datapaths.
     67                     '' Parent tags'':: <openflow:sliver>
     68
     69=== <openflow:datapath> ===
     70[*] This tag provides information about a single datapath resource.
     71                             ''Attributes''::
     72   * component_id : ![1] the urn of the component, the best way to get this is from the advertisement rspec
     73   * component_manager_id : ![1] is urn of the Openflow Aggregate Manager that manages this resource as listed in the advertisement rspec
     74                             '' Children tags'':: <openflow:port>[*], a datapath element with no children implies ALL ports
     75                             '' Parent tags'':: <openflow:group>, <openflow:match>
     76
     77=== <openflow:port> ===
     78[*] This provides information about a port on a datapath.
     79                        ''Attributes''::
     80   * num : ![1] the number of the port, the best way to get this is from the advertisement rspec
     81   * name : [?] the name of the port as defined in the advertisement rspec
     82                        '' Children tags'':: None
     83                        '' Parent tags'':: <openflow:datapath>
     84
     85=== <openflow:match> ===
     86[+] This is the tag for describing requested matches. Conceptually this tag has two parts, one for describing the datapaths in which we would like to control the forwarding of packets and another part that defines filters on which packets to control.
     87The first part is mandatory and uses the <openflow:use-group> and <openflow:datapath> tags. The second part is optional and uses the <openflow:packet> tag. If no filters are defined, ALL packets in the specified datapaths are requested.
     88                        ''Attributes'':: None
     89                        '' Children tags''::
     90   [AT LEAST ONE OF THE <openflow:use-group> or <openflow:datapath> MUST BE PRESENT]
     91   * <openflow:use-group> [*]
     92   * <openflow:datapath> [*]
     93   * <openflow:packet> [?]
     94                        '' Parent tags'':: <openflow:sliver>
     95
     96=== <openflow:use-group> ===
     97[*] This tag specifies which group of datapaths should be used for this match.
     98                        ''Attributes''::
     99   * '''name''' : ![1] the name of the group as it is defined in the corresponding <openflow:group> tag, if the group has not been defined the rspec will be rejected.
     100                        '' Children tags'':: None
     101                        '' Parent tags'':: <openflow:match>
     102
     103
     104=== <openflow:packet> ===
     105[?] This tag describes the packet filters for defining this match. 
     106                        ''Attributes'':: None
     107                        '' Children tags'':: [AT LEAST ONE OF THOSE SHOULD BE PRESENT]
     108   * <openflow:dl_src> [*]
     109   * <openflow:dl_dst> [*]
     110   * <openflow:dl_type> [*]
     111   * <openflow:dl_vlan> [*]
     112   * <openflow:nw_src> [*]
     113   * <openflow:nw_dst> [*]
     114   * <openflow:dl_proto> [*]
     115   * <openflow:tp_src> [*]
     116   * <openflow:tp_dst> [*]
     117                        '' Parent tags'':: <openflow:match>
     118   
     119=== Filter elements ===
     120
     121In order to filter the traffic that will be delegated to this sliver packets can be filtered based on the following packet header fields. Each field corresponds to an element. In all of them you can specify a list of values by using a comma separated list (e.g. a,b,c) , or if ranges are supported to use the dash (e.g a-c), or a mixture of the two (e.g. a-c, f-j). Each element can appear multiple times within a packet element. If an element appears more than once, then the union of all the requested values is requested. All of the match elements have the same structure so we will describe it here :
     122
     123
     124                        ''Attributes''::
     125   * '''value''' : ![1] A list or a range of values, the value format id different for each element
     126                        '' Children tags'':: None
     127                        '' Parent tags'':: <openflow:match>
     128
     129
     130 
     131==== <openflow:dl_src> ====
     132[*] Matches on the source ethernet address of  the packet. Format xx:xx:xx:xx:xx:xx, does NOT support ranges. For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here]
     133
     134==== <openflow:dl_dst> ====
     135[*] Matches on the destination ethernet address of  the packet. Format xx:xx:xx:xx:xx:xx, does NOT support ranges. For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here]
     136
     137==== <openflow:dl_type> ====
     138[*] Matches on the ethernet type of the packet. Format is numbers, does NOT support ranges. For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here]
     139
     140==== <openflow:dl_vlan> ====
     141[*] Matches on the vlan id of the packet. Format is numbers, supports ranges.  For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here]                       
     142
     143==== <openflow:nw_src> ==== 
     144[*]Matches on the IP source address of the packet. IP addresses or subnets in CIDR format (e.g. 10.43.123.0/24), does not support ranges. If this is used then <openflow:dl_type> should be matching IP (0x0806) and/or ARP (0x806) packets. For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here]
     145
     146==== <openflow:nw_dst> ====
     147[*]Matches on the IP destination address of the packet. IP addresses or subnets in CIDR format (e.g. 10.43.123.0/24), does NOT support ranges. If this is used then <openflow:dl_type> should be matching IP (0x0800) and/or ARP (0x806) packets. For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here]
     148
     149==== <openflow:nw_proto> ==== 
     150[*]Matches on the IP protocol. Protocol numbers (e.g. 17 for UDP), supports ranges. If this is used then <openflow:dl_type> should be matching IP (0x0800) and/or ARP (0x806) packets. For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here] 
     151
     152==== <openflow:tp_src> ====
     153[*]Matches on the source port of TCP or UDP headers. Format is numbers, supports ranges. If this is used then <openflow:nw_proto> should be matching TCP (6) and/or UDP (17) packets.For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here.]
     154   
     155==== <openflow:tp_dst> ====
     156[*]Matches on the destination port of TCP or UDP headers. Format is numbers, supports ranges. If this is used then <openflow:nw_proto> should be matching TCP (6) and/or UDP (17) packets. For details on the structure look [wiki:HowTo/ConvertExpedientToFoamRspecs#Matchelements here.]
     157
     158= Writing FOAM request rspecs =
     159The best way to understand and write FOAM rspecs is by looking at example rspecs. Keep in mind that
     160the rspec is merely a structured representation of flowspaces that describe the traffic that an experiment wants to control.
     161
     162This [https://openflow.stanford.edu/display/FOAM/rspec example rspec], is a complete example. Here there is also a list of
     163simpler example rspecs :
     164   * [attachment:of_one_match.rspec Rspec with only one match element]
     165   * [Rspec with multiple match elements]
     166   * [Rspec with two groups]
     167
     168In essence your rspec should:
     169   1. start with the <rspec> and the <openflow:sliver> tags :
     170{{{
     171#!xml
     172<?xml version="1.0" encoding="UTF-8"?>
     173
     174<rspec xmlns="http://www.protogeni.net/resources/rspec/2"
     175       xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
     176       xmlns:openflow="http://www.geni.net/resources/rspec/ext/openflow/2"
     177       xs:schemaLocation="http://www.protogeni.net/resources/rspec/2
     178                          http://www.protogeni.net/resources/rspec/2/request.xsd
     179                          http://www.geni.net/resources/rspec/ext/openflow/2
     180                          http://wwww.geni.net/resources/rspec/ext/openflow/2/of-resv.xsd"
     181       type="request">
     182   
     183    <openflow:sliver email="user@geni.net" description="My GENI experiment" ref="http://www.geni.net" />
     184
     185        <!-- rest of rspec -->
     186
     187    </openflow:sliver>
     188</rspec>
     189}}}
     190
     191   2. Specify where your controller is running. E.g.:
     192{{{
     193 #!xml
     194<openflow:controller url="tcp:myctrl.geni.net:9933" type="primary" />
     195}}}
     196
     197   3. Organize the datapaths that are relevant to this sliver within groups. The best way to construct the <openflow:datapath> elements is by copying them from the advertisement rspecs. E.g if [attachment:ad-sample.rspec this] is the advertisement rspec, and you want :
     198   * ports 7 and 20 of datapath with dpid 06:a4:00:12:e2:b8:a5:d0
     199   * ports 50 and 71 of datapath with dpid 06:af:00:24:a8:c4:b9:00
     200
     201Then you can construct a group that looks like :
     202{{{
     203 #!xml
     204 <openflow:group name="mygrp">
     205   <openflow:datapath component_id="urn:publicid:IDN+openflow:foam:uxmal.gpolab.bbn.com+datapath:06:a4:00:12:e2:b8:a5:d0" dpid="06:a4:00:12:e2:b8:a5:d0">
     206     <openflow:port name="GBE0/7" num="7"/>
     207     <openflow:port name="GBE0/20" num="20"/>
     208   </openflow:datapath>
     209
     210
     211   <openflow:datapath component_id="urn:publicid:IDN+openflow:foam:uxmal.gpolab.bbn.com+datapath:06:af:00:24:a8:c4:b9:00" dpid="06:af:00:24:a8:c4:b9:00">
     212     <openflow:port name="26" num="50"/>
     213     <openflow:port name="47" num="71"/>
     214     <openflow:port name="local" num="65534"/>
     215   </openflow:datapath>
     216
     217 </openflow:group>
     218}}}
     219
     220   4. Specify your flowspace. E.g. if you want for the above group to get all traffic that is sourced or destined to the IP subnet 10.1.1.0/24 and uses tcp port 80, then you will need two <openflow:match> tags, one to match the packets that are sourced from that subnet and one to match the packets that are destined to that subnet. Keep in mind that your flowspace is the union of the traffic that is described by each 
     221{{{
     222#!xml
     223 <openflow:match>
     224   <openflow:use-group name="mygrp" />
     225   <openflow:packet>
     226     <openflow:nw_src value="10.1.1.0/24" />
     227     <openflow:tp_src value="80" />
     228   <openflow:packet />
     229 <openflow:match>
     230
     231 <openflow:match>
     232   <openflow:use-group name="mygrp" />
     233   <openflow:packet>
     234     <openflow:nw_dst value="10.1.1.0/24" />
     235     <openflow:tp_dst value="80" />
     236   <openflow:packet />
     237 <openflow:match>
     238}}}
     239
     240
     241Done! The complete rspec looks like :
     242{{{
     243#!xml
     244<rspec xmlns="http://www.protogeni.net/resources/rspec/2"
     245       xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
     246       xmlns:openflow="http://www.geni.net/resources/rspec/ext/openflow/2"
     247       xs:schemaLocation="http://www.protogeni.net/resources/rspec/2
     248                          http://www.protogeni.net/resources/rspec/2/request.xsd
     249                          http://www.geni.net/resources/rspec/ext/openflow/2
     250                          http://wwww.geni.net/resources/rspec/ext/openflow/2/of-resv.xsd"
     251       type="request">
     252   
     253    <openflow:sliver email="user@geni.net" description="My GENI experiment" ref="http://www.geni.net" />
     254
     255       <openflow:controller url="tcp:myctrl.geni.net:9933" type="primary" />
     256
     257       <openflow:group name="mygrp">
     258           <openflow:datapath component_id="urn:publicid:IDN+openflow:foam:uxmal.gpolab.bbn.com+datapath:06:a4:00:12:e2:b8:a5:d0" dpid="06:a4:00:12:e2:b8:a5:d0">
     259             <openflow:port name="GBE0/7" num="7"/>
     260             <openflow:port name="GBE0/20" num="20"/>
     261           </openflow:datapath>
     262
     263
     264           <openflow:datapath component_id="urn:publicid:IDN+openflow:foam:uxmal.gpolab.bbn.com+datapath:06:af:00:24:a8:c4:b9:00" dpid="06:af:00:24:a8:c4:b9:00">
     265             <openflow:port name="26" num="50"/>
     266             <openflow:port name="47" num="71"/>
     267             <openflow:port name="local" num="65534"/>
     268           </openflow:datapath>
     269
     270       </openflow:group>
     271
     272       <openflow:match>
     273           <openflow:use-group name="mygrp" />
     274           <openflow:packet>
     275             <openflow:nw_src value="10.1.1.0/24" />
     276             <openflow:tp_src value="80" />
     277           <openflow:packet />
     278         <openflow:match>
     279
     280         <openflow:match>
     281           <openflow:use-group name="mygrp" />
     282           <openflow:packet>
     283             <openflow:nw_dst value="10.1.1.0/24" />
     284             <openflow:tp_dst value="80" />
     285           <openflow:packet />
     286         <openflow:match>
     287
     288    </openflow:sliver>
     289
     290</rspec>
     291}}}
     292= FOAM and Expedient rspecs =
     293Although the FOAM and the Expedient
     294