create new tag
, view all tags

Network Stitching with GENI API and RSPEC - Best Practices Proposal

This page examines the network stitching design against GENI AM API v2 and RSpec v3 standards (including upcoming revisions). It describes how the GENI API may be used to support stitching workflow and proposes convention-based switching semantics in GENI Request and Manifest RSPECs. It also provides an example for multi-aggregate stitching workflow that involves bandwidth and VLAN negotiation.

Network Stitching by GENI AM API

Stitching Advertisement

  • GetVersion -- An AM that supports Network Stitching should include the NetworkStitching RSpec in both geni_request_rspec_versions and geni_ad_rspec_versions arrays in return to the GetVersion call. The values of the version parameter strings are TBD.
  • ListResources -- When the geni_rspec_version option is set to a Network Stitching version type, ListResources shall return the advertisement of stitching resources for the aggregate. Using this advertisement together with advertisement of AM internal resources, the Stitching Topology Service will be able to construct global aggregate-to-aggregate topology view.

Stitching with Negotiation

  • Stitching negotiation is performed by using the following Ticket calls: GetTicket, UpdateTicket, ReleaseTicket, RedeemTicket
  • Below is Rob Ricci's Ticket States diagram


  • Full implementation of left half of above diagram will allow arbitrary phases of stitching negotiation.
    • GetTicket initiates the negotiation with a Request RSpec. The returned Ticket contains a Manifest RSpec in response to the initial request.
    • The workflow may either take the return Manifest as is or modify it to proceed a follow-up phase of negotiation.
    • In each follow-up phase of negotiation, UpdateTicket has to be used instead of GetTicket.
    • Failed follow-up negotiation will result in ReleaseTicket call to terminate the procedure.
  • Successful negotiation will lead to the Commit Phase that uses RedeemTicket to create resource sliver for the stitching.
  • Note that RSPec in any Ticket may include both regular and stitching resources. During stitching negotiation, regular RSpec part may remain unchanged.

Stitching without Negotiation

  • Negotiation may not be desired for some AMs, especially those who have no negotiable resources.
  • A direct CreateSliver call will be used to commit stitching resources for such AMs.

Convention-Based Semantics for Stitching RSpec

The GENI Network Stitching schema provides a common description for stitching resource advertisement and request. The purpose is to regulate AM behaviors related to aggregate-to-aggregate stitching.
In addition the general API calls, we define the following set of rules to serve as convention-based semantics to complete the stitching protocol for AM.

  1. Every aggregate must advertise its stitching links following the schema. No aggregate- or vendor-specific alteration information is allowed.
    • For example, an OpenFlow aggregate may have an Ethernet link of type in its internal RSpec, For stitching advertisement, it has to describe it using GeniStitch:GeniStitchSwitchingCapabilitySpecificInfo_Lsc in the stitching schema
  2. In <stitching><aggregate>, the <negotiatedservices> element has value "true" along with a GetTicket or UpdateTicket negotiation. In CreateSliver, the <negotiatedservices> value must be "false".
  3. Only bandwidth and VLAN are negotiable. The negotiation semantics are defined next.
  4. A stitching Request RSPEC will provide a deterministic bandwidth value. If agreed, the Manifest will use the same value. Otherwise, a smaller value may be returned in Manifest with negotiation. Or rejected without.
  5. A stitching Request RSPEC will provide both vlanRangeAvailability and suggestedVLANRange for VLAN negotiation.
    • suggestedVLANRange here always contains zero or one single VLAN.
    • If vlanRangeAvailability is a single VLAN (equal to suggestedVLANRange), the AM can only choose to accept or reject that.
    • If vlanRangeAvailability is 'any' or a range, the AM can choose to use the suggested VLAN, reject, or return a subset of the vlanRangeAvailability and another suggested VLAN.
  6. A non-negotiable Request RSPEC will have vlanRangeAvailability of single VLAN, range or 'any'. The AM should ignore suggestedVLANRange and allocate a random VLAN in vlanRangeAvailability.

Multi-Point Stitching Extension

The current version of Network Stitching schema can describe an arbitrary multi-point network topology. However, certain features such as description of bridging capability and support for bridged multi-point path in Request and Manifest are missing. We propose the following additions for initial multi-point stitching implementation.

Aggregate Bridge Capability Advertisement

To support multi-point stitching that requires bridge more than one next-hop branches, we first need to advertise such bridging capability at node or aggregate level.

  • In current design we only advertise bridging capability per aggregate. We initially only care about bandwidth and VLANs. The below schema extension tells whether an aggregate can bridge VLANs and if so at what capacity and VLAN range.
      <xs:complexType name="GeniStitchAggregateContent">
              <xs:element minOccurs="0" name="capability" type="GeniStitch:GeniStitchAggregateCapability"/>
      <xs:complexType name="GeniStitchAggregateCapability">
              <xs:element minOccurs="0" name="multiPointBridge" type="GeniStitch:GeniStitchMultiPointBridge"/>
      <xs:complexType name="GeniStitchMultiPointBridge">
              <xs:element minOccurs="0" name="capacity" type="xs:string"/>
              <xs:element minOccurs="0" name="vlanAvailabilityRange" type="xs:string"/>

Multi-Point Stitching <path> in Request and Manifest RSPEC

To describe a multi-point stitching Request in <path> format, we propose the following.

  • Decompose the request into separate connections that have no bridge relations. Use multiple <path> elements to describe them, one for each.
  • If a <path> element is Point-to-Point, we already know how to describe it.
  • If a <path> element is Bridged Multi-Point, we describe it as follows:
    • A <hop> of <link> type can have multiple <nextHop> elements of <link> type if we do not know the exact bridging location. This could be at the very begging of stitching workflow.
    • A <hop> of <link> type has a <nextHop> element of <aggregate> type to indicate a bridging aggregate, which in turn has multiple <nextHop> elements of <link> type. Identifying specific bridging aggregates can be in result from workflow path computation or in Manifest.
    • Any hops related by <nextHop> references should be included in a VLAN bridge.
  • The same convention applies to both Request and Manifest RSPEC although Manifest may include more detailed hops than Request.

Stitching Workflow Examples

To better explain the recommended beset practices for network stitching using standard GENI AM API and RSPEC, we provide examples that involve the ProtoGENI, ORCA, ION/DCN, MAX and OpenFlow aggregates.


We have previously composed advertisement RSPECs for ProtoGENI, ION and MAX.

  • These used ProtoGENI RSPECv2 plus the Stitching RSPEC.
  • With GENI RSPECv3 and above recommendations, the changes are very little.
    • The ProtoGENI RSPECv2 part can be directly treated as GENI RSPECv3. No change is required.
    • The <stitching><aggregate><negotiatedServices> element will change value from "false" to "true" to indicate capability to support stitching negotiation.
    • An experimental element is added to ION and MAX advertisement to describe VLAN bridging capability at aggregate level.
  • Note that in internal resource description, similar devices may have different <hardware_type>, e.g., "ethernet" vs. "lan" vs. "switch". Such difference is handled by AM internally when mapped to stitching resources and therefore is not a concern for stitching operations.
  • The modified advertisement GENI RSPEC v3 Ads:

ORCA also supports GENI RSPEC v3 and Stitching extension through its latest ExoGENI rack distribution.

An OpenFlow aggregate will use extended information in GENI RSPECv3 to advertise native OpenFlow resources.

  • Here is an example: OpenFlow Sample Ad RSpec
  • We modify this example by adding a PLC node and stitching resources. One link in the native topology now points to ION. Similarly peer link should be added in ION topology advertisement to point back.
  • The new Example OpenFlow advertisement RSPEC:

Stitching P2P Path with Negotiation

This Stitching Workflow is similar to what has been described HERE. Here we stitch three aggregates in a Point-to-Point path: ProtoGENI-ION-BBN/OF. In this example, we also explain how the Stitching Negotiation procedure works.

Note that the below example RSPECs are for vision description and proof of concept. They were composed based on old version RSPECs and API terminology. We will update them once the features are actually implemented.

Step 1: Client sends Request RSPEC

Step 2: Request RSpec is explained after Path Computation

Step 3: Workflow Agent negotiates VLAN with ProtoGENI using the RSpec from Step 2

  • The RSpec is wrapped in GetTicket to start negotiation
  • A Manifest RSpec is return by GetTicket from ProtoGENI: p2p-protogeni-manifest-v1.xml
  • In the Manifest, ProtoGENI assigned VLAN407 to the Ethernet link stitching to ION rtr.salt router.

Step 4: Workflow Agent then negotiates VLAN with ION

  • Based on the Manifest from Step 3, a Request RSpec is sent to ION via GetTicket: p2p-ion-request-v1.xml
  • This requests for VLAN 407 at ingress rtr.salt and VLAN 'any' at egress rtr.newy.
  • A Manifest RSpec is return by GetTicket from ION: p2p-ion-manifest-v1.xml
  • In the Manifest, ION provide a range of VLANs at rtr.newy egress edge and suggests VLAN 3738.

Step 5: Workflow Agent then negotiates VLAN with BBN/OF

  • Based on the Manifest from Step 4, a Request RSpec is sent to BBN/OF via GetTicket: p2p-bbnof-request-v1.xml
  • This requests for a VLAN in range "670,3726-3750" and suggests 3738 at ingress datapath:06:d6:00:12:e2:b8:a5:d0:GBE0/1.
  • A Manifest RSpec is return by GetTicket from BBN/OF: p2p-bbnof-manifest-v1.xml
  • In the Manifest, BBN/OF suggested another VLAN 3750.

Step 6: Finalize Request RSPECs by UpdateTicket

  • Workflow Agent accepts the suggested VLAN 3750 from BBN/OF. Then the negotiation is finished.
  • Wrapped in UpdateTicket a final RSpec is sent to every aggregates with the negotiated results: final-request-v1.xml

Step 7: Commit RSPEC with RedeemTicket

  • At last the sliver will get instantiated with all regular and stitching resources allocated.


  • Compared to previous design, Workflow Agent does not need to be hardcoded for dependencies between aggregates. It may simply start negotiation with any aggregate and follow through others.
  • This example is the most common case that requires one negotiation phase per aggregate. But there could be cases that multiple rounds of negotiation are required.
  • There is also chances that GetTicket or UpdateTicket got rejected that fails the negotiation and lead to ReleaseTicket to terminate process.

Stitching Multi-Point by VLAN Bridge

The client request includes a PC for each of the three aggregates: ProtoGENI, ION, BBN/OF and MAX. They must be bridged by a common VLAN connection.

We assume non-negotiation operations to simplify this example. Request RSpec after computation will be sent to AMs via CreateSliver. Manifest RSpec will be returned by CreateSliver and by ListResources query.

Request RSPEC:

  • Client Request RSpec: mp-request-from-client-v1.xml
    • The initial Request is abstract that only three end points are listed. They are requested to be put into a same link which implies VLAN bridging.

  • Request RSpec after Path Computation: mp-request-after-computation-v1.xml
    • After path/topology computation, Workflow Agent finds out that the three aggregates can be bridged via the middle ION aggregate, where VLAN bridge capability is available.
    • The RSpec shows a common VLAN 408 for bridging. It is translated into VLAN 3750 to the BBN branch and VLAN 3106 to the MAX branch. The RSpec does not call out the specific bridging node.
    • Note that this example is hypothetical. ION currently does not have such VLAN bridging capability.

Manifest RSPECs:

Topic revision: r13 - 2013-06-25 - XiYang
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback