User Tools

Site Tools


tutorials:sfawrapper

Tutorial: Interacting with the Community-Lab SFA wrapper using Probe

Obsolete page. This page is being updated.

Introduction

This tutorial explains how to interact with the SFA interface of Community-Lab, which is exposed by the Community-Lab SFA wrapper. To use the SFA interface, a SFA client application is needed. This tutorial uses jFed, a java SFA client tool developed by iMinds.

The SFA wrapper of Community-Lab exposes a SFA interface to enable the usage of the testbed in a federation scenario. In such scenario, the Community-Lab testbed can be used together with other federated facilities and testbeds. Thus, our SFA wrapper trusts a central authority through which all the federated testbeds can be used. An account in the central authority and its corresponding certificate are required to use jFed with the Community-Lab SFA wrapper.

Prerequisites

Account in central authority

Currently there is only one trusted central authority whose for Community-Lab SFA wrapper, Wall2 Emulab Authority (hosted in http://www.wall2.ilabt.iminds.be). An account and credential from this authority are needed to use jFed with our SFA wrapper. Follow the manual to create an account and get the credential: Get a Fed4FIRE account

Download jFed

The SFA client tool used in this tutorial is jFed, a Java based framework developed by iMinds to support SFA testbed federation client tools. jFed provides a Probe client tool, with a GUI or command-line version. Download jFed application at jFed website.

Start and Login in jFed

Start the downloaded jFed-Probe-GUI.jar application.

java -jar jFed-probe-GUI.jar 

In the Login window, load the file that contains the client certificate and the private key (.pem file). Enter the passphrase to unlock the key and press Login.

Add Community-Lab SFA Wrapper to the Authority List

In the jFed Probe window press the button Edit List… to edit the list of authorities that are configured to be used with jFed. The list will be edit locally. Select the option Add New by scanning AM URL. In the emerging window introduce the information of the Community-Lab SFA wrapper AM interface:

The jFed scanner will automatically detect the configuration of our SFA wrapper. Once the scanner finishes, accept to “trust all of the certificates” and open the scan result as new Authority. The detected configuration should look like that:

 Configuration of SFA wrapper authority for C-Lab and jFed

Otherwise, modify manually. Save the list and close the Edit list window.

Interaction with SFA wrapper of Community-Lab

Although the tutorial is focused on the jFed SFA client, the SFA interaction process explained can be taken as general.

This interaction process describe the creation of a new slice in the central authority and the allocation of a new sliver in the Community-Lab testbed for this slice, using the jFed tool. To get more generic information about the the usage of SFA wrapper see SFA Wrapper Usage.

The interaction process consists of the following steps:

1. Get User credential from the central authority

First step is to get the user credential that corresponds to the .pem file certificate that was used for Login. To get the user credential select the interface User and Slice APIs –> ProtoGeni SA and the operation getCredential.

In the Server to use section select Server of Logged in users Authority, which will correspond to iMinds Virual Wall 2 (the central federation authority). Call the operation. The result will be the user credential that corresponds to the used certificate.

 jFed getCredential operation

2. Register a new slice in the central authority

The user credential retrieved in the previous step can now be used to register a new slice in the central authority. To register the new slice select the operation register in the interface User and Slice APIs –> ProtoGeni SA. Then Call the operation on the server iMinds Virtual Wall 2.

The register call replies with the slice credential of the registered credential.

 jFed Resgister slice operation

3. Allocate a new sliver in the Community-Lab AM for the registered slice

Once the slice is registered in the central authority, its slice credential can be used to allocate slivers in any federated testbed that accepts credentials issued by this authority. The Community-Lab SFA wrapper is federated with the iMinds Virtual Wall 2 authority, so it accepts and trusts credentials issued by this authority.

To allocate a new sliver for the registered slice in the Community-Lab testbed, select the operation allocate from the Aggregate Manager APIs –> Aggregate Manager v3 interface.

To work with the Community-Lab SFA wrapper AM change the server in the section Server to use. Select the Authority that you added in the step Add Community-Lab SFA wrapper to the Authority List section for the Community-Lab SFA wrapper AM.

In the allocate operation select the credential from the credentialList that corresponds to the SliceCredential, and the URN of the slice. By default, the parameters will correspond to the slice registered on the previous step.

Enter a Request RSpec for describing the sliver to be allocated. Examples of request RSpecs can be found in the usage section: Examples of request RSpecs for C-Lab SFA AM. To allocate a sliver in a random node of the testbed use the following Request RSpec:

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

Note that the (optional) field client_id of the element node is used by the user to give an identifier to the node/sliver, so that the user will be able to identify such node/sliver in subsequent operations.

The result of the allocate call is a GENI Reply struct with the following fields:

  • geni_slivers, a list of allocated slivers with information about their allocation and operational state.
  • geni_urn, the URN of the slice in which the sliver has been allocated.
  • geni_rspec, a Manifest RSpec describing the allocated resources, that is, the allocated sliver. Note that this Manifest RSpec specifies in which node the sliver has been allocated (also identified by the client_id specified in the call).

 jFed allocate sliver operation

4. Provision the created sliver

Next step in the process of sliver creation is to provision the sliver. Select the operation Provision from the Aggregate Manager APIs –> Aggregate Manager v3 interface, and select the authority server of Community-Lab SFA wrapper AM.

Select the URN that corresponds to the allocated sliver in the urns section, and select the Slice credential as in the previous operation.

in the users section select the user that corresponds to the certificate used to Login. Then add the SSH keys that will be uploaded to the created sliver, so that the user will be able to access the sliver via ssh. Enter the Public Key of a SSH key-pair and press Save. Multiple keys can be added to the same user, one per line. All the added keys will be uploaded to the sliver for ssh access.

Once the key information is properly completed, call the provision operation on the C-Lab SFA AM authority.

The result will be a GENI Reply struct very similar to the one in the Allocate call. However, note that the geni_rspec returned in this operation shows more information about the node/sliver. The node element includes a services element with the Login information of the sliver. The login element specifies the authentication method to access the sliver, the hostname, the port and the user name to access the sliver.

 jFed Provision sliver operation

5. Start the created sliver

Last operation in the sliver creation process in to start the sliver. To do so, select the performOperationalAction operation from the Aggregate Manager APIs –> Aggregate Manager v3 interface, and select the authority server of Community-Lab SFA wrapper AM.

As in the previous operation, select the URN of the sliver in the urns section, and select the slice credential in the credentialList section.

In the action section the user specifies which action (according to the GENI AM API v3) that wants to perform on the sliver. To start the sliver leave the default value geni_start. Call the operation on the C-Lab SFA AM authority.

The result of this operation is a GENI Reply struct that only contains the geni_slivers field (a list of slivers with information about their allocation and operational state). In this case the list will only contain one element, corresponding to the sliver that is being created.

 jFed PerformOperationalAction Start sliver operation

Note that immediately after the PerformOperationAction replies, the geni_operational_state of the sliver is geni_notready. The SFA wrapper exposes an interface with asynchronous/non-blocking operations; the start operation will eventually lead to a geni_ready operational state for the sliver and the sliver will be then ready to use.

6. Wait for sliver to be ready. Check its status

To check the operational status of the sliver and see if it is ready, a user can call the operation status.

Select the status operation from the Aggregate Manager APIs –> Aggregate Manager v3, and select the authority server of Community-Lab SFA wrapper AM

As in the previous operation, select the URN of the sliver in the urns section, and select the slice credential in the credentialList section.

The result of the status operation is a GENI Reply struct GENI Reply struct that only contains the geni_slivers field, as in the the previous operation. Check in the list if the geni_operational_status of the sliver has the value geni_ready. Then the sliver will be ready to use.

 jFed Status sliver operation

7. Describe the sliver to obtain its SSH Login information

Once the operational state of the sliver is geni_ready the sliver is ready to be used and the creation process is finished. As outcome of the creation process of the sliver, the user should keep the Login information of the sliver, which will be used to access the sliver and deploy experiments.

The Login information of the sliver was given in the reply of the provision operation, in the geni_rspec field. However, a user can retrieve again this information by calling the operation Describe.

Select the describe operation from the Aggregate Manager APIs –> Aggregate Manager v3, and select the authority server of Community-Lab SFA wrapper AM.

As in previous operation, select the URN of the sliver in the urns section, and select the slice credential in the credentialList section. Uncheck also the compressed box to receive the Rspec without any compression in the Reply.

The describe operation returns a complete GENI Reply struct with the fields geni_slivers, geni_urn and geni_rspec. The RSpec field contains a Manifest RSpec that includes again the Login information of the sliver.

 jFed Describe sliver operation

Access the created sliver in Community-Lab testbed

To access the sliver via SSH, the user needs to install and configure a tinc client. The setup of the tinc client gives the machine access to the Management Network overlay, through which the slivers can be reached. The setup process of tinc is explained here: tinc setup

The Login information retrieved from the creation process of the sliver allows the user to access the sliver. The sliver can be accessed via ssh using the private key that corresponds to the public key that was uploaded to the sliver in the provision step.

To access the sliver via ssh, run the following command:

ssh -i PRIVATE_KEY_FILE  USERNAME@HOSTNAME

The username for accessing the sliver is always root (which gives root permissions). The hostname of the sliver is an IPv6 address that corresponds to the address of the sliver in the tinc Management Network overlay. Therefore, the machine used to access the sliver needs to have the tinc client installed and properly configured (tinc setup).

Once inside the sliver, the user can for example examine the ssh authorized keys and check that his/her key is in the list of authorized keys.

cd ~/.ssh/
cat authorized_keys 

The SSH access to the sliver is used from the testbed point of view, to allow the user to deploy experiments on the slivers.


tutorials/sfawrapper.txt · Last modified: 2014/10/21 16:41 by esunly