OESS: NSI

What is NSI?  NSI is "a generic network service interface that can be called by a network's external entity such as end users, middleware, and other network service providers"  Essentially it is a common interface for requesting resources from a network.

NSI 2.0 was implemented natively in OESS since version 1.1.8 of OESS was released in November of 2015. There are 2 parts to providing this support, the NSI cgi (/usr/share/oess-frontend/webservices/idc/nsi.cgi) and the NSI daemon (/usr/bin/oess-nsi).  

Configuring NSI in OESS

To configure NSI in OESS a few steps need to be completed.

1. Creation of an NSI user (for interacting with the OESS web-services)

2. Creation of an NSI workgroup (for ACL permissions to be configured)

3. adding the NSI user to the NSI workgroup.

4. Configuring /etc/oess/nsi.conf

   You will need to specify the nsi user and password, along with the URL to the web-service that you will be using (usually https://<your host>/oess/services/).  You probably will also need SSL certificates to communicate with other SSL authenticated NSI aggregates/instances.

Once all of this is completed, restart (or start) the oess-nsi daemon using the init script (/etc/init.d/oess-nsi [re]start)

5. Topology / ACLs for NSI

  the NSI topology will contain the ACLs for the NSI workgroup.  You most likely will need to submit your topology to an aggregate.  This is configurable in /etc/oess/database.xml file <oscars topo="<url>">

A quick look at the NSI protocol

NSI uses Asynchronous and Synchronous SOAP messages as a transport mechanism between instances.  It is important that the SOAP messages meet and can be validated by the schemas that are specified in the NSI protocol documents.

One of the more difficult to understand aspects of NSI is the Asynchronous Callback mechanism.  Below is a diagram attempting to explain how an Asynchronous request in NSI functions.  This diagram is from the NSI v2.0 protocol definition document.  MTL is Message Transport Layer.  

This diagram shows the request with an immediate ACK reply.  The Provider agent starts processing the request after the ACK has been sent.  Once the Provider agent has completed it sends the Asynchronous reply, and the Requester Agent ACKs the reply.

NSI Messages 

NSI messages have 2 components to them.  The NSI Header, and the actual message / method to be called.  All NSI messages must have the NSI header.  The header consists of the requesterNSA the providerNSA, a replyTo SOAP endpoing, a correlationId to relate asynchronous messages back back and forth, and a protocol version.  Optionally there is a sessionSecurityAttr which can also be specified.

State Machines

There are 3 state machines inside of NSI (LifeCycle, Provisioning, Reservation), each state machine tracks different aspects of NSI connections.  

NSI terminology

  • Requester Agent (RA) - an NSI client
  • Provider Agent (PA) (also ultimate provider agent uPA) - an instance of a network that provides an implementation of NSI
  • Aggregator - an instance of a  PA which the talks to uPAs to aggregate requests together
  • STP - Service Termination Point - places you can provision to on the network
  • MTL - Message Transport Layer
  • Connection - a Circuit

OESS NSI Implementation Details

There are 2 parts to the OESS NSI Implementation.  The NSI cgi (webservices/idc/nsi.cgi) and the OESS NSI Daemon (/usr/bin/oess-nsi).

The NSI CGI is a SOAP endpoint that provides a place for RAs to send request to OESS (essentially it is a transparent proxy to the oess-nsi daemon).  The NSI CGI parses and sends the NSI message over the org.nddi.nsi DBus channel which is handled by the NSI daemon.  

The NSI Daemon then processes the request and pushes an event onto it's queue to handle the event.  Once the event is queued a success/fail value is returned to the CGI through the DBus channel.  At which point the CGI will reply with the ACK message to the requester.

The NSI Daemon then processes its request queue on a timer, and handles all messages in the queue.  Once the request is completed (or fails) the Daemon then sends it reply message to the requester.

NSI Topology/Permissions

Permissions and Topology for NSI are determined through the NSI workgroup (see configuring NSI for OESS).  All requests for NSI are sent to OESS via web-services so if the NSI workgroup doesn't have permission to use a VLAN tag or interface than the provisioning request will fail.

Additional Notes

A few things to note based on this architecture.  This implementation is not an Aggregator or a Requester Agent.  This implementation is only a Provider Agent for the OESS application. 

NSI Aggregator

An NSI Aggregator can take a single request to provision across X domains and translate it into NSI requests across each of those domains.  This prevents the requestor for having to handle requests and state across all of the different domains involved with their request.  

NSI uses a tree structure instead of a chaining structure (like IDCP) which allows the aggregator to better handle errors from errors in other domains.  This prevents a single NSA from causing all of the other NSA to get into a failed state.

Below is an example diagram of an NSA aggregator handling the request from a requestor and proxying the request to the provider agent.  This shows the request making its way from the reuqester through the Aggregator and to the provider agent.  It also shows what happens if there is a SOAP fault between the provider and the Aggregator and how this gets filtered down to the requester.