Implementation details and user guide

This section provides an overview on the XMPP protocol implementation in ONOS. In order to understand XMPP-specific terminology please refer to https://xmpp.org/rfcs/rfc6120.html#streams-fundamentals. 

Model architecture and abstraction

NOTE! The model architecture and abstraction presented below is the draft version. The new architecture using core ONOS abstractions and Route subsystem is in progress. However, the most important component (XmppController being responsible for XMPP protocol handling) will remain unchanged.

The eXtensible Messaging and Presence Protocol (XMPP) is a general-purpose, universal protocol. The main feature of XMPP is its extensibility and payload-agnosticism, what makes XMPP very powerful and high-level protocol that may carry various information such as routing, configuration or monitoring.

The main assumption of XMPP protocol implementation design for ONOS was to provide extensibility of XMPP protocol, as Publish/Subscribe extension is not the only use case for XMPP. The current implementation allows to re-use the core implementation of basic XMPP mechanisms (such as stream establishment or handling of basic XML stanzas) and based on that develop the new XEPs that are needed for particular use case.

The XMPP Stanza is composed of header, extension-specific (XEP-specific) part and optionally payload. In order to make our implementation architecture extensible and make possible to add new XMPP extensions seamlessly we made a decision to divide XMPP parsing process into three parts. The basic part is implemented in Protocols layer (XmppController) and handles core XMPP functionalities (such as Stream negotiation). It is also responsible for recognizing XMPP messages and parsing XMPP Stanza headers. The handling of the XEP-specific part is moved to Providers layer. We assume that for the each XEP the new XMPP Provider will be created. We have already created XmppPubSubProvider being responsible for XMPP Publish/Subscribe message handling. Additionally, the XmppDeviceProvider is common for all XEP-specific Providers. The payload of the XMPP messages (if exists) is handled by XmppDriver, which is responsible for translating XML payload into Java abstractions. These objects returned by XmppDriver are passed to the PubSub Subsystem. Then, they are encapsulated in PubSub Event and all PubSub listeners are notified about new incoming PubSub message. Each future XEP implementation should follow this architecture. The payload parsing logic should be moved to Driver subsystem. Moreover, the new subsystem, which will provide XEP-specific abstractions for ONOS applications, should be created for every new XEP.

The core part of the implementation architecture is XmppController, which is responsible for:

• Establishing XMPP stream
• Stream errors handling
• Decoding/encoding XMPP Stanzas
• Maintaining the state of connected XMPP devices

The XmppPubSubProvider listens to IQ stanzas based on that:

• parses XMPP messages into PubSub abstractions. The Subscribe and Unsubscribe XMPP messages are passed directly, while the Publish/Retract XMPP messages are parsed using methods provided by XmppDriver. For BGP-signaled End System IP VPNs use case, XmppDriver translates XML data carried in XMPP body into BgpInfo ONOS Java object.
• handles PubSub errors
• constructs XMPP Event Notification messages and sends them to underlaying XMPP devices

The PubSub Subsystem is newly created ONOS subsystem, which provides Publish/Subscribe abstractions. It provides interface between Providers and Apps layer and is responsible for notifying listeners observing the PubSub Events. The Device Subsystem is the standard ONOS core subsystem storing status of connected devices. The abstractions provides by both PubSub and Device Subsystems may be used by ONOS applications.

Key implementation pieces of code

The code implementing XMPP protocol is located in Protocols and Providers layers. The source code is available at: https://github.com/osinstom/onos/tree/xmpp-1.0.

The XMPP implementation follows ONOS code convention. The folder structure includes “api” subfolder  containing interface definitions and “ctl” containing implementation classes. The implementation uses also several external libraries:

• Tinder, which provides XMPP abstractions. It is also used in open source XMPP server implementations such as Openfire
• Aalto-XML, which provides asynchronous, non-blocking XML parsing mechanism
• Netty, which provides multi-threaded and efficient TCP Java-based server

Interfaces and classes

• XmppController.java interface implemented by XmppControllerImpl.java tracks all connected XMPP devices, provides interface to obtain XMPP device and register/unregister listeners.

• XmppDevice.java interface implemented by AbstractXmppDevice.java represents underlaying XMPP devices and allows to perform operations on them. With each XmppDevice.java object there is a Netty channel associated.

• XmppDeviceId.java class implements identifier representation based on XMPP JID address.

• XmppServer.java and XmppChannelInitializer.java implements Netty TCP server listening on XMPP connection on TCP 5269 port and configures Netty channel pipeline.

• XMPP encoding and decoding is implemented by several classes in order to provide efficient XML stream parsing. XmlStreamDecoder.java class reads asynchronously incoming XML data using Aalto-XML library. XmlMerger.java class accumulates incoming XML events from XmlStreamDecoder.java and creates XML document. The XmppDecoder.java class translates XML document into XMPP stanzas. The XmppEncoder.java class translates Tinder objects into bytes ready to send over a network socket.

• The XmppChannelHandler.java class implements XMPP protocol state machine.

• The XmppPubSubProvider.java implements XMPP Publish/Subscribe mechanism for parsing XMPP PubSub messages and sending XMPP Event Notifications.

• The XmppMessageListener.java, XmppIqListener.java and XmppPresenceListener.java interfaces informs providers in the ONOS core about incoming XMPP stanzas. Currently, only the XmppIqListener is implemented by InternalXmppIqListener.java in XmppPubSubProvider, because XMPP Publish/Subscribe does not operate on the other XMPP stanzas.

• The XmppDeviceProvider.java manages any XMPP device and its interactions with the ONOS core. It notifies ONOS Device Subsystem about already connected/disconnected devices.

• The XmppDeviceListener.java notifies the provider in ONOS core that XMPP device is connected/disconnected.

Virtual Lab creation and validation

As the main use case for XMPP implementation in ONOS, the XMPP-based BGP-signaled End-System IP/VPNs architecture has been implemented. This architecture in general consists of centralized control plane entity called End-System Route Server and distributed vRouters (or VPN Forwarders). For the experiments purposes the XMPP-enabled vRouter emulator (based on Mininet and Open vSwitch) has been implemented (https://github.com/osinstom/vrouter-client-py). It provides basic functionalities of VPN Forwarder such as XMPP communication with server and VXLAN encapsulation.  There was also developed the Proof-of-Concept application for ONOS providing VPN membership management, which is the basic functionality of End-System Route Server.

In order to run a simple demo you have to set tup three VMs. We use VirtualBox to provide three VMs on local laptop. It's preferred to create two separate networks between VMs (we use VBox Host-Only Adapter networks):  management network for control plane operations and data network for connecting emulated compute nodes. The lab architecture is presented below:

Controller node

Before running the XMPP clients you should run ONOS controller:

• Download ONOS sources:

  mkdir onos/ cd onos/ git init git pull https://gerrit.onosproject.org/onos refs/changes/81/16781/1

  
  

• Start ONOS:

  export ONOS_ROOT=<your-path-to-onos>/onos tools/build/onos-buck run onos-local -- clean debug

  
  

• Activate XMPP Provider and PoC Application:

  cd tools/test/bin ./onos localhost app activate org.onosproject.protocols.xmpp org.onosproject.xmpp.device

  
  

• You should have XMPP server listening on 5269 TCP port
  

Compute nodes

On every compute node there should be vRouter emulator deployed. The vRouter emulator is based on Mininet and allows to emulate data center compute node running VMs (Mininet hosts). The vRouter has been implemented for the L3VPN architecture testing purposes. To configure compute nodes follow the steps below:

• Download vRouter emulator. Note that it is a prototype version.

  git clone https://github.com/osinstom/vrouter-client-py.git

  
  

• Configure vRouter.

  cd vrouter-client-py nano config.ini

  You should configure jid, vrouter.ip and controller.ip parameters. The jid parameter identifies XMPP client and should be unique for compute node. The vrouter.ip is an IP address of data network interface. The controller.ip parameter is an IP address of ONOS controller. Sample config:

  [general] jid=agent2@vnsw.contrailsystems.com vrouter.ip=192.168.121.3 controller.ip=192.168.10.2

  
  

• Run vRouter console.

  sudo python vrouter.py

• The vRouter emulator should establish XMPP stream with controller. You can choose the action to perform from command-line menu. Note that it is prototype (work in progress) application so far and not all function may work properly. Actually, the code from Gerrit patch handles only the device-related operations. As a result of above command you should see new device in the ONOS core.

Demo and Results

A simple demo using vRouter emulator has been developed already. The PoC presents XMPP-based BGP-signaled End System IP VPN using ONOS as a control plane.

The short demo video is available at:

https://drive.google.com/file/d/1Ru1tb_65kI7nnVpK8RLoFDTvc1iT77xy/view?usp=sharing

Presentation with the Technical Steering Team:

Gerrit link: https://gerrit.onosproject.org/#/c/16781/

References:

[1] https://tools.ietf.org/html/rfc7938

[2] https://datatracker.ietf.org/doc/draft-ietf-l3vpn-end-system/?include_text=1

[3] https://xmpp.org/extensions/xep-0060.html

[4] RFC6120, https://xmpp.org/rfcs/rfc6120.html

Copyright © 2016 Atlassian

This work is licensed under a Creative Commons Attribution-Non Commercial-Share Alike 4.0 International License.