User Tools

Site Tools


soft:sfawrapper

SFA Wrapper for Community-Lab

Introduction

SFA (Slice-based Facility Architecture) has been adopted as the main standard for testbed federation. Thus, heterogeneous testbeds that provide a SFA-compliant interface can be federated with each other so that their capabilities are combined to enable a wider and richer range of experiments. As a contribution for the Fed4FIRE project (Fed4FIRE), a SFA interface was developed for Community-Lab testbed.

This documentation describes the Community-Lab SFA Wrapper, a software component that offers a standard SFA interface for the testbed so that it can be federated with other testbeds. This section focuses on technical, architectural and implementation details. Another section of the wiki describes the usage of the Wrapper. There is also a tutorial about how to use the SFA Wrapper with a specific client tool called jFed.

Aggregate Manager

The SFA interface provided by Community-Lab consists of an Aggregate Manager component that exposes the GENI AM API v3 (GENI AM API v3).

The URL of the Community-Lab Aggregate Manager is: https://84.88.85.16:12346

The Aggregate Manager is the SFA entity responsible for managing the resources of the testbed, that is, nodes and slivers. The AM API provides a set of operations to interact with nodes and slivers. This set includes: GetVersion, ListResources, Describe, Allocate, Renew, Provision, Status, PerformOperationalAction, Delete, Shutdown.

Warning: Renew operation does not behave as expected in SFA. The Community-Lab testbed allows the user to set the expiration date to a maximum of 30 days from the current date. Attempts to set the expiration date beyond this limit will fail. Moreover, the registry may only accept renewal requests happening within a given time span before the expiration date (e.g. 15 days) to avoid repeated renewal requests to extend the slice's expiration time without limits.

RSpecs

Any SFA operation (call or reply) that needs to describe nodes and/or slivers uses a RSpec document. A RSpec is an XML document that describes physical resources. More information about RSPecs here.

Depending on the operation and the purpose of the RSpec, there are three types of RSpecs:

  • Advertisement: used in the reply of listResources operation to describe of advertise available resources.
  • Request: used in the call of Allocate operation to describe the resources being allocated.
  • Manifest: used in the reply of other operations to describe the resources associated with the operation call.

Note that the only RSpec written by the user is the Request RSpec. The Request RSpec describe the resources that the user want to use. Therefore it will describe the slivers that will be created, and optionally the nodes in which these slivers will be hosted.

There are different RSpecs formats according to the XML schema that they obey. The Community-Lab AM works with the following types of RSpec:

GENI RSpec v3

In the GENI RSpec v3 there is an element sliver_type that identifies the type of the sliver. Since the slivers in Community-Lab are homogeneous, this field is always the same for Community-Lab. The name of the sliver_type element in the Rspecs of Community-Lab is “RD_sliver”, which stands for Research Device sliver.

Some examples of Request RSpecs:

Unbound RSpec with 1 sliver

In this RSpec the sliver defined is not associated with any specific node. The wrapper will select a random node (in PRODUCTION state) to host the sliver.

<rspec type="request" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd " xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.geni.net/resources/rspec/3"> 
     <node client_id="IdSpecifiedByUser" component_manager_id="urn:publicid:IDN+clab+authority+am" exclusive="false"> 
         <sliver_type name="RD_sliver"/> 
     </node> 
   </rspec>

Bound RSpec with 1 sliver

The user can specify a particular node in which the sliver will be hosted. For this, it is necessary to specify the field component_id in the node element. The component_id value is the URN of the node in which the sliver is willing to be hosted.

<rspec type="request" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd " xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.geni.net/resources/rspec/3"> 
     <node client_id="IdSpecifiedByUser" component_id="urn:publicid:IDN+clab+node+UPC-D6-105-RD1" component_manager_id="urn:publicid:IDN+clab+authority+am" exclusive="false"> 
         <sliver_type name="RD_sliver"/> 
     </node> 
   </rspec>

Mixed RSpec with 2 slivers

With a single Request RSpec a user can define more than one slice. Each slice may or may not be associated with a particular node.

<rspec type="request" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd " xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.geni.net/resources/rspec/3"> 
     <node client_id="IdSpecifiedByUser" component_manager_id="urn:publicid:IDN+clab+authority+am" exclusive="false"> 
         <sliver_type name="RD_sliver"/> 
     </node> 
     <node client_id="UPC-D6-105-RD1" component_id="urn:publicid:IDN+clab+node+UPC-D6-105-RD1" component_manager_id="urn:publicid:IDN+clab+authority+am" exclusive="false"> 
         <sliver_type name="RD_sliver"/> 
     </node> 

CLab v1 RSpec

This is a particular version of RSpec designed by and for Community-Lab testbed. It aims at providing a suitable RSpec type to utilize all the specific features offered by the Community-Lab testbed. This RSpec type allows to refer to such features when performing operations through the C-Lab SFA Wrapper.

C-Lab v1 RSpec is implemented as an extension of the GENI v3 RSpec. Basically, it consists of the GENI v3 RSPec with an extended namespace in which Community-Lab specific fields are defined. Thus, the wrapper is able to understand both the raw GENI v3 RSpec and the GENI v3 RSpec extended with Community-Lab namespace (CLab v1 RSpec). The standard GENI v3 RSpec is extensible by default. The new elements defined by the C-Lab v1 RSpec are therefore added to the standard RSpec, with the only need for specifying the new namespace.

The C-Lab v1 RSpec is currently extended with the following elements:

Node-related elements

  • group, which defines the group that the node belongs to. It describes the group by its name and id.
  • management_network, which shows the IPv6 address of the node in the Management Network overlay.
  • network_interface, which describes the network interfaces of the node by their name and type.

Sliver-related elements

  • sliver_parameters, an element that contains information about the sliver. It contains the elements template and a set of network_interface of the sliver.
  • template, which identifies the OS template used in the sliver. The template is identified by its name, id and type.
  • network_interface, which describes the network interfaces of the sliver by their name, type and number.

The XML Schema defining all the elements can be found here: CLab v1 RSpec Schema

The C-Lab fields listed above extend the standard RSpec. The user (through the wrapper) can specify the template or network interfaces for the sliver on the Request RSpec. On the other hand, the wrapper can describe better nodes and slivers, by showing testbed-specific information on the Advertisement and Manifest RSpecs.

Below there are some examples of how to use the C-Lab v1 RSpec elements.

Select the CLab v1 RSpec type

In the SFA client application used to interact with the wrapper the type of the RSpec must be specified. Such specification usually consists of the type and the version of the RSpec used. For selecting Clab v1 RSpec:

  • type = clab
  • version = 1

To identify the RSpec type and version the Wrapper expects the following element in the options field:

"geni_rspec_version": {"version": "VERSION_OF_RSPEC", "type": "TYPE_OF_RSPEC"}

Most of the SFA client tools offer in their GUI a place for specifying the RSpec. For example, jFed client application includes the fields rspecType and rspecVersion in the input form of the operation to select the RSpec.

The specification of the RSpec version might not be required in the Allocate operation (the whole RSpec is provided in this operation). Operations where an RSpec document is returned do require the specification of the RSpec type. The, if C-Lab v1 RSpec version selected, the returned RSpec will be a standard GENI v3 RSpec extended with elements from C-Lab v1 RSpec.

List Resources with CLab v1 RSpec Ad

When selecting the Clab v1 RSpec for the opertion List Resources, the wrapper replies with a Advertisement RSpec in which the node information of GENI v3 RSpec is extended with fields from Clab v1 RSpec. In particular, the added fields are group, management_network and a set of network_interface. This is an example of how the node is described in this RSpec:

  <node component_manager_id="urn:publicid:IDN+clab+authority+cm" component_id="urn:publicid:IDN+clab+node+UPC-D6-105-RD1" exclusive="false" component_name="UPC-D6-105-RD1">
    <hardware_type name="i686"/>
    <available now="true"/>
    <sliver_type name="RD_sliver"/>
    <clab:group id="6" name="UPC"/>
    <clab:management_network addr="fdf5:5351:1dfd:7e::2"/>
  </node>

And a node with network interfaces:

<node component_manager_id="urn:publicid:IDN+clab+authority+cm" component_id="urn:publicid:IDN+clab+node+AWMN-HQ-LAB-01" exclusive="false" component_name="AWMN-HQ-LAB-01">
    <hardware_type name="i686"/>
    <clab:network_interface name="wlan0" type="direct"/>
    <clab:network_interface name="eth1" type="direct"/>
    <available now="true"/>
    <sliver_type name="RD_sliver"/>
    <clab:group id="4" name="AWMN"/>
    <clab:management_network addr="fdf5:5351:1dfd:90::2"/>
  </node>

Allocate a new sliver with CLab v1 RSpec Request

The user uses a Request RSpec to describe the desired resources in the Allocate operation. Basically, the user specifies the description of the desired sliver. Using the Clab v1 RSpec the user can specify particular features of the Community-Lab slivers. For example, it can specify the template of the sliver, or the list of network interfaces that the sliver will have. Below there are some examples.

Specify a particular template for the sliver
<rspec xmlns="http://www.geni.net/resources/rspec/3 xmlns:clab="https://wiki.confine-project.eu/_media/sfa:clab.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="request" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd">
   <node component_manager_id="urn:publicid:IDN+clab+authority+am" exclusive="false">
     <sliver_type name="RD_Sliver"/>
     <clab:sliver_parameters>
       <clab:template name="Debian Squeeze" />
     </clab:sliver_parameters>
   </node>
</rspec>

In the CLab v1 Request RSpec above the particular template “Debian Squeeze” is selected for the sliver. The template element inside the sliver_parameters element allows the user to choose the template. The template can be specified by name (like in the example) or by id (unique numeric identifier of the template). This is the list of available templates (more details in the Template List of REST API):

  • Debian Squeeze (name=“Debian Squeeze”, id=“2”)
  • Debian BitTorrent (name=“Debian BitTorrent”, id=“4”)
  • Cloudy (name=“Cloudy”, id=“15”)
  • AdLeaks Template (name=“AdLeaks Template”, id=“13”)
  • openwrt-slice-test (name=“openwrt-slice-test”, id=“5”)
  • debian7 for NodeVers gr 20131115 (name=“debian7 for NodeVers gr 20131115”, id=12)
Specify a list of network interfaces for the sliver
<rspec xmlns="http://www.geni.net/resources/rspec/3 xmlns:clab="https://wiki.confine-project.eu/_media/sfa:clab.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="request" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd">
     <sliver_type name="RD_Sliver"/>
     <clab:sliver_parameters>
       <clab:network_interface name="priv1" type="private" />
       <clab:network_interface name="mgmt" type="management" />
       <clab:network_interface name="debug" type="debug" />
     </clab:sliver_parameters>
   </node>
</rspec>

In the CLab v1 Request RSpec above a list of three network interfaces is specified for the sliver. To define the network interfaces is necessary to specify the name and the type of the interface. There are different types of network interfaces that can be defined in the slivers: public4, public6, private, management, debug (more information in Node and sliver connectivity). To define the sliver network interfaces there some rules for the network interfaces definition that have to be respected:

  • Types public4 and public6 are only available if the node has public ipv4 or ipv6 addresses.
  • There must be exactly one interface of type private.
  • There must be exactly one interface of type management. It is needed for accessing the sliver.
  • The maximum length of the name of an interface is 10 characters.
Complete example

This is a complete example combining the specification of a concrete template and a list of network interfaces for the sliver.

<rspec xmlns="http://www.geni.net/resources/rspec/3 xmlns:clab="https://wiki.confine-project.eu/_media/sfa:clab.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="request" xsi:schemaLocation="http://www.geni.net/resources/rspec/3 http://www.geni.net/resources/rspec/3/request.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd https://wiki.confine-project.eu/_media/sfa:clab.xsd">
   <node client_id="MyId1" component_manager_id="urn:publicid:IDN+clab+authority+am" exclusive="false">
     <sliver_type name="RD_Sliver"/>
     <clab:sliver_parameters>
       <clab:template name="Debian Squeeze" />
       <clab:network_interface name="priv1" type="private" />
       <clab:network_interface name="mgmt" type="management" />
       <clab:network_interface name="debug" type="debug" />
     </clab:sliver_parameters>
   </node>
</rspec>

The features offered by the C-Lab v1 RSpec can be combined with the ones offered by the GENI v3 RSpec. For example, a concrete node can be specify using the attribute component_id with the element node of the GENI RSpec, as well as specify features from C-Lab RSpec, such as template and interfaces.

Supported accounts and credentials

To invoke operations in the AM the user needs to present a credential. This credential is used for authentication and authorization. It contains information about the permissions that a certain user has, so the AM can determine if the user is allowed to perform the requested operation. More info here.

The credentials are issued by a SFA entity Slice Authority. The Community-Lab SFA wrapper does not provide a Slice Authority entity. Instead, it uses credentials issued by a federated authority. To get a a valid credential you need to login at a slice authority federated with Community-Lab and retrieve the credential, which will be signed by this Slice Authority. If the Slice Authority is federated with Community-Lab, the the AM of Community-Lab will accept the credential issued by this Slice Authority.

Currently the AM of Community-Lab accepts credentials from the following authorities:

Architecture of the Wrapper

The wrapper is implemented as a software layer on top of the REST API of the testbed controller. It is based on the SFAWrap software, which helps testbeds to develop a SFA interface. The wrapper uses the Python library Confine-ORM to interact with the testbed controller.

The picture below (SVG source) shows an overview of the wrapper architecture.

SFAWrap

SFAWrap ( SFAWrap) is a free software that allows to federate a testbed into the emerging SFA-based global federation of testbeds. The software package provides a set of general components to help any testbed to expose a SFA-compliant interface, which integrate the generic part of the code. It also includes a set of skeleton classes to be implemented for each particular testbed, which integrate the testbed-specific part.

Generic part

The generic part of the code implements all the standard processing related to SFA that does not depend on the testbed. It basically consists of modules that implement SFA interface and XML RPC servers, credential management and validation, generic SFA registry and Rspec management.

It also includes a generic command-line client tool for SFA: sfi.py.

Testbed-specific

This part of the code acts as a “glue” between the generic part of the wrapper and the testbed. It is in charge of translating the API of the specific testbed and adapt it to the SFA operations as the wrapper requires. The testbed-specific part consists of a driver module that exposes the standard SFA operations that the generic part requires and some other modules that implement the SFA components (AM, Registry, SM). In the testbed-specific part the modules interact with the testbed to apply the requested operations. In the case of Community-Lab this interaction is carried out using the Confine-ORM library.

CONFINE-ORM

Confine-ORM ( Confine-ORM) is a high-level Python library that provides an object-oriented programmatic framework to interact with the Confine REST API. Basically, it encapsulates the interaction with the REST API into object oriented concepts, such as objects and methods. In the wrapper the ORM library it is used to perform operations on the testbed, according to the SFA requested operations.

External users management and Action Log

This section explains how the C-Lab SFA Wrapper manages the external users. It also presents a problem derived from such management and how the effect of this problem is minimized.

External User Management

C-Lab SFA Wrapper allows users from the federation domain to use the testbed. These users are external, they do not belong to the Community-Lab domain but to other authorities/domains that have a trust relation with Community-Lab. Therefore, the users interacting with the Wrapper do not have an account in the domain of Community-Lab. They have accounts from other trusted authorities and they have to present their credentials to be able to interact with the testbed through the wrapper.

To interact with the testbed and perform any action, a user has to be logged in with a Community-Lab account. This implies the need of mapping somehow the external users interacting with the Wrapper into the Community-Lab domain. To achieve this purpose the Wrapper uses a very simple solution: it uses a generic usersfawrap” of the Community-Lab domain for all the external users. This way, the wrapper can log in with the generic user account and perform any requested action in behalf of the external users.

Anonymous usage

The simple solution explained above has however an important drawback: the Wrapper makes an anonymous usage of the testbed. From the testbed side, any external user performing an action is seen as the generic “sfawrap” user. With this solution the testbed (controller) does not have any information of which external user performed the action.

Action Log

A possibility to overcome the drawback of the anonymous usage is to maintain an Action Log in the Wrapper. The Wrapper will keep track of which external user performs which action and it will store such information in a log file. Although in the testbed side all the actions will be still performed by the same generic user “sfawrap”, the action log in the wrapper will give enough information to identify which external user performed an action, thus minimizing the effect of the anonymous usage.

To implement this feature the Wrapper needs to get a unique identifier for each external user. As said before, any external user interacting with the Wrapper uses the credentials issued by its authority for authentication and authorization. Among other parameters, the credentials contain the URN (Uniform Resource Name) of the user, which acts as a unique identifier. The URN has the following format:

urn:publicid:IDN+<authority>+<resource_type>+<name>

In the case of a user resource:

urn:publicid:IDN+<authority>+user+<name>

The Wrapper can then get the URN of the user from the credentials and use it as a unique identifier to generate the entries of the Action Log.

Credentials Passing

The Wrapper is based on th SFAWrap software and it consists of two different parts. The Generic part, which implements the common components that all the testbed needs; the Testbed-specific part, which depends on each testbed and adapts the generic part to the underlying testbed API. Since the maintenance of the Action Log is a specific feature of the Community-Lab testbed, it should be implemented in the testbed-specific part. The problem is that the testbed-specific part does not receive the credentials of the user.

The validation of the user credentials is done in the generic part of SFAWrap because is a common feature that all the testbeds implement. Once the credentials are validated the generic components invoke the testbed-specific components to perform the requested actions on the testbed. However, the user credentials are not passed to the testbed-specific part, leading to an anonymous usage in the testbed-specific components that should maintain the action log.

To solve this problem the source code of the SFAWrap was modified locally. The changes in the code allowed to pass the user credentials from the generic components of the SFAWrap to the testbed-specific components. Actually, the modifications required were very simple and they are explained in the next section.

SFAWrap Generic part modifications

To accommodate the pass of credentials from the generic part of SFAWrap to the testbed-specific part, the AggregateManager class of /sfa/managers/aggregate_manager.py needs to be modified. The AggregateManager is the object from the generic part that invokes the first object in the testbed-specific part, which is the ClabDriver in /sfa/clab/clab_driver.py. Moreover, the AggregateManager object has access to the credentials of the user. The AggregateManager object makes calls to the different methods of the ClabDriver object depending on the action requested by the user. In all these methods calls there is an optional parameter called options. This parameter is a dictionary that includes different options that the user can specify. Since the options parameter contains extra information for the call and it is easily extensible, it is suitable to be used for passing the credentials to the CLabDriver object, without implying any modification to the implementation of the methods in the driver object. In summary, the modifications done in the AggregateManager generic component consist of adding the user credentials in the options parameters for every call to the methods of ClabDriver object.

For example, for the Allocate methods of the AggregateManager:

...
options['creds']=creds
return api.driver.allocate(xrn, rspec_string, expiration, options)

In general, the piece of code

options['creds']=creds 

has to be added just before any call to the api.driver.ANY_METHOD(…) methods.

Action log file and entries

The modification presented in the previous section allow to pass the user credentials to the CLabDriver component, that is, to the testbed-specific part of the SFAWrap. The ClabDriver can therefore maintain an Action Log to keep track of the actions that the wrapper performed in the testbed, as well as the external users that invoked these actions.

The action log file is stored in the server machine that runs the C-Lab SFA Wrapper. The file can be found under the path /var/log/clab_sfawrap.log.

A part from this log file, the generic part of the wrapper also generates another log file by default, that can be found under the path /var/log/sfa.log.

The ClabDriver object maintains the Action Log file. It creates a new entry for each action that that the Wrapper performs. The format of these entries is:

<YYYY-MM-DD hh:mm:ss,ms> INFO C-Lab Aggregate Manager 
	ACTION: <name_of_action>
	PARAMETERS: {<dict_containing_parameters_of_call>}
	OPTIONS: {<dict_containing_options_of_call>}
	BY USER: <urn_of_external_user>
	AS C-LAB USER:  <username_in_clab_domain>  IN GROUP: <group_in_clab_domain>

As an example, check the following entry for the Describe action performed by the external user user1 from the wall2.ilabt.iminds.be authority. Note that the wrapper performs the describe action using the generic user sfawrap of the group fed4fire in the Community-Lab domain:

2014-09-23 14:48:23,773 INFO C-Lab Aggregate Manager 
	ACTION: Describe
	PARAMETERS: {'urns': ['urn:publicid:IDN+clab+sliver+704a164']}
	OPTIONS: {'geni_rspec_version': {'version': '3', 'type': 'geni'}, 'geni_compressed': True}
	BY USER: urn:publicid:IDN+wall2.ilabt.iminds.be+user+user1
	AS C-LAB USER: sfawrap  IN GROUP: fed4fire

Controller API and Dashboard

As a last step for the implementation of this feature that prevents the anonymous usage of the tesbted by the wrapper, we though of how to include the information about the external user that performed the action in the controller API. In other words, how to make this information available from the Dashboard or the controller API. The simplest solution here was to use the the properties field of the slices and slivers objects that the controller API offers. The properties field is a dictionary (name : value) store for slices and slivers that allows the users to store any information that they consider useful. Thus, when the Wrapper creates slivers (or slices) in behalf of external users, it will add a new property to specify the URN of the external user that invoked this creation action. The format of this property is:

Name Value
external_user_urn urn:publicid:IDN+<authority>+user+<username>

Remember that an external user cannot directly create slices using the C-Lab SFA Wrapper (it only exposes an Aggregate Manager interface); however the wrapper automatically creates equivalent slices in the domain of Community-Lab to map external slices in which the external user wants to create slivers. Therefore, the creation of such equivalent slices is also invoked by the external user and they will have the external_user_urn property.


soft/sfawrapper.txt · Last modified: 2014/09/23 17:09 by gerardmn