mPlane Software Development Kit (SDK) for Python 3

Description

This module provides a mPlane Software Development Kid (SDK) for Python 3 and contains the mPlane protocol reference implementation. It is intended for the use of component and client developers to interoperate with the mPlane platform. It requires Python 3.3 or greater.

The core classes in the mplane.model and mplane.scheduler packages are documented using Sphinx; current Sphinx documentation can be read online here.

The mPlane Protocol provides control and data interchange for passive and active network measurement tasks. It is built around a simple workflow in which Capabilities are published by Components, which can accept Specifications for measurements based on these Capabilities, and provide Results, either inline or via an indirect export mechanism negotiated using the protocol.

Measurement statements are fundamentally based on schemas divided into Parameters, representing information required to run a measurement or query; and Result Columns, the information produced by the measurement or query. Measurement interoperability is provided at the element level; that is, measurements containing the same Parameters and Result Columns are considered to be of the same type and therefore comparable.

Quick Start

To install from PyPI, type:

$ pip3 install mplane-sdk

To install from GitHub type:

$ git clone https://github.com/fp7mplane/protocol-ri
$ cd protocol-ri
$ python3 setup.py install

This section describes how to get started with the mPlane SDK, the included component runtime mpcom, the debugging client mpcli, and the demonstration supervisor mpsup. It presumes that the software is run from the root directory of a working copy of the https://github.com/fp7mplane/protocol-ri Git repository. The demonstration supervisor and the sample configuration files are not installed with the release SDK module.

Run Supervisor, Component and Client

To start the demonstration Supervisor with the included sample configuration and certificates, change to the repository directory and run:

scripts/mpsup --config ./conf/supervisor.conf

To run the Component:

scripts/mpcom --config ./conf/component.conf

At this point, the Component will automatically register its capabilities to the Supervisor. Now launch the Client:

mpcli --config ./conf/client.conf

As soon as it's launched, the Client connects to the Supervisor and retrieves the capabilities. To get a list of commands available, type help. The minimum sequence of commands to run a capability and retrieve results is:

1. listcap will show all the available capabilities.
2. runcap <name_or_token> runs a capability from the listcap list. You will be asked to insert parameter values for that capability.
3. listmeas shows all pending receipts and received measures.
4. showmeas <name_or_token> shows the measure (or pending receipt) in detail.

While executing these operations, the supervisor and the component will print some status udate messages, giving information about the communications going on.

Common Problems

1. If an error like this: AttributeError: 'module' object has no attribute 'url' shows up, try to update the urllib3 library: sudo pip3 install --upgrade urllib3
2. If you get something like: ssl.CertificateError: hostname '127.0.0.1' doesn't match 'Supervisor-1.SSB.mplane.org', try the following steps:
   • add the following entry in /etc/hosts: 127.0.0.1 Supervisor-1.SSB.mplane.org
   • replace all “127.0.0.1” with “Supervisor-1.SSB.mplane.org” in the conf files

Sample Configuration Files

Sample configuration files are located in protocol-ri/conf/ in the mPlane GitHub repository.

component.conf

[TLS] - paths to the certificate and key of the component, and to the root-ca certificate (or ca-chain) [Roles] - bindings between Distinguished Names (of supervisors and clients) and Roles [Authorizations] - for each capability, there is a list of Roles that are authorized to see that capability [module_] - parameters needed by specific component modules (e.g. ping, tStat, etc). If you don't need a module, remove the related section. If you add a module that needs parameters, add the corresponding section.

[component] - miscellaneous settings:

• registry_uri: link to the registry.json file to be used
• workflow: type of interaction between component and client/supervisor. Can be component-initiated or client-initiated. This must be the same both for the component and the client/supervisor, otherwise they will not be able to talk to each other.

To be properly set only if component-initiated workflow is selected:

• client_host: IP address of the client/supervisor to which the component must connect
• client_port: port number of the client/supervisor
• registration _ path: path to which capability registration messages will be sent (see register capability)
• specification _ path: path from which retrieve specifications (see retrieve specification)
• result _ path: path to which results of specifications are returned (see return result)

To be properly set only if client-initiated workflow is selected:

• listen_port: port number on which the component starts listening for mplane messages

client.conf

[TLS] - paths to the certificate and key of the client, and to the root-ca certificate (or ca-chain) [client] - miscellaneous settings:

• registry_uri: link to the registry.json file to be used
• workflow: type of interaction between client and component/supervisor. Can be component-initiated or client-initiated. This must be the same both for the client and the component/supervisor, otherwise they will not be able to talk to each other.

To be properly set only if component-initiated workflow is selected:

• listen_host: IP address where the client starts listening for mplane messages
• listen_port: port number on which the client starts listening
• registration _ path: path to which capability registration messages will be received (see register capability)
• specification _ path: path where specifications will be exposed to components/supervisors (see retrieve specification)
• result _ path: path where results of specifications will be received (see return result)

To be properly set only if client-initiated workflow is selected:

• capability _ url: path from which capabilities will be retrieved

supervisor.conf

Since the Supervisor is just a composition of component and client, its configuration file is just a union of the file described above. [client] section regards the configuration of the part of the supervisor facing the component, in other words its "client part" [component] section erregards the configuration of the part of the supervisor facing the client, in other words its "component part"

Learning More

See doc/HOWTO.md in the GitHub repository for information on getting started with the mPlane SDK for demonstration purposes.

See doc/conf.md for an introduction to the mPlane SDK configuration file format.

See doc/client-shell.md for an introduction to mpcli debug client shell.

See doc/component-dev.md for an introduction to developing components with the mPlane SDK and running them with the mpcom runtime.

See doc/protocol-spec.md for the mPlane protocol specification.

Official version

• The official version of the SDK is available at https://github.com/fp7mplane/protocol-ri.
  Anyone wishing to use the SDK for development within the project should be tracking the master branch of the project on GitHub. The 0.9.0 release (current as of D2.3) is tagged as sdk-v0.9.0.  
• The 0.9.0 release of the SDK is also available from the Python Package Index (PyPI) as mplane-sdk.