One document matched: draft-trammell-mplane-protocol-00.xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.0.20 -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC3205 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.3205.xml">
<!ENTITY RFC3339 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.3339.xml">
<!ENTITY RFC4291 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.4291.xml">
<!ENTITY RFC5246 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.5246.xml">
<!ENTITY RFC5905 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.5905.xml">
<!ENTITY RFC5952 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.5952.xml">
<!ENTITY RFC6455 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.6455.xml">
<!ENTITY RFC7011 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.7011.xml">
<!ENTITY RFC7159 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.7159.xml">
<!ENTITY RFC7230 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.7230.xml">
<!ENTITY RFC7373 SYSTEM "http://unicorn-wg.github.io/idrefs/bibxml/reference.RFC.7373.xml">
]>
<rfc ipr="trust200902" docName="draft-trammell-mplane-protocol-00" category="info">
<?rfc toc="yes"?>
<front>
<title abbrev="mPlane Protocol">mPlane Protocol Specification</title>
<author initials="B." surname="Trammell" fullname="Brian Trammell" role="editor">
<organization>ETH Zurich</organization>
<address>
<postal>
<street>Gloriastrasse 35</street>
<city>8092 Zurich</city>
<country>Switzerland</country>
</postal>
<email>ietf@trammell.ch</email>
</address>
</author>
<author initials="M." surname="Kuehlewind" fullname="Mirja Kuehlewind" role="editor">
<organization>ETH Zurich</organization>
<address>
<postal>
<street>Gloriastrasse 35</street>
<city>8092 Zurich</city>
<country>Switzerland</country>
</postal>
<email>mirja.kuehlewind@tik.ee.ethz.ch</email>
</address>
</author>
<date year="2015" month="August" day="27"/>
<abstract>
<t>This document defines the mPlane architecture for
coordination of heterogeneous network measurement components: probes and
repositories that measure, analyze, and store network measurements,
data derived from measurements, and other ancillary data about elements
of the network. The architecture is defined in terms of relationships
between components and clients which communicate using the mPlane protocol
defined in this document.</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>This document describes the mPlane architecture and protocol, which is designed to provide control and coordination of heterogeneous network measurement tools. It is based heavily on the mPlane project’s deliverable 1.4 <xref target="D14"/>, and is submitted for the information of the Internet engineering community. <xref target="overview-of-the-mplane-architecture"/> gives an overview of the mPlane architecture, <xref target="protocol-information-model"/> defines the protocol information model, and <xref target="representations-and-session-protocols"/> defines the representations of this data model and session protocols over which mPlane could be supported.</t>
<t>Present implementation work is focused on mPlane represented in JSON using HTTPS as a session protocol <xref target="RFC3205"/>. <xref target="workflows-in-https"/> demonstrates how mPlane’s separation of connection initiation and message initiation works in this environment.</t>
</section>
<section anchor="terminology" title="Terminology">
<t>[EDITOR’S NOTE: these terms are not capitalized within the document at this time. Fix this.]</t>
<t><list style="hanging">
<t hangText='Client:'>
An entity which implements the mPlane protocol, receives capabilities published by one or more components, and sends specifications to those component(s) to perform measurements and analysis. See <xref target="components-and-clients"/>.</t>
<t hangText='Component:'>
An entity which implements the mPlane protocol specified
within this document, advertises its capabilities and accepts specifications which request the use of those capabilities. The measurements, analyses, storage facilities and other services provided by a component are completely defined by its capabilities. See <xref target="components-and-clients"/>.</t>
<t hangText='mPlane Message:'>
The atomic unit of exchange in the mPlane protocol. The treatment of a message at a client or component receiving it is based upon its type; see <xref target="message-types"/>.</t>
<t hangText='Capability:'>
An mPlane message that contains a statement of a component’s ability and willingness to perform a specific operation, conveyed from a component to a client. A capability does not represent a guarantee that the specific operation can or will be performed at a specific point in time. See <xref target="capability-and-withdrawal"/></t>
<t hangText='Specification:'>
An mPlane message that contains a statement of a client’s
desire that a component should perform a specific operation, conveyed from a
client to a component. It can be conceptually viewed as a capability whose
parameters have been filled in with values. See <xref target="specification-and-interrupt"/>.</t>
<t hangText='Result:'>
An mPlane message containing a statement produced by a component that a
particular measurement was taken and the given values were observed, or that a
particular operation or analysis was performed and a the given values were
produced. It can be conceptually viewed as a specification whose result
columns have been filled in with values. See <xref target="result"/>.</t>
<t hangText='Element:'>
An identifier for a parameter or result column in a capability, specification, or result, binding a name to a primitive type. Elements are contained in registries that contain the vocabulary from which mPlane capabilities, specifications, and results can be built. See <xref target="element-registry"/>.</t>
</list></t>
</section>
<section anchor="overview-of-the-mplane-architecture" title="Overview of the mPlane Architecture">
<t>mPlane is built around an architecture in which components provide network measurement services and access to stored measurement data which they advertise via capabilities completely describing these services and data. A client makes use of these capabilities by sending specifications that respond to them back to the components. Components may then either return results directly to the clients or sent to some third party via indirect export using an external protocol. The capabilities, specifications, and results are carried over the mPlane protocol, defined in detail in this document. An mPlane measurement infrastructure is built up from these basic blocks.</t>
<t>Components can be roughly classified into probes which generate measurement data and repositories which store and analyze measurement data, though the difference between a probe and a repository in the architecture is merely a matter of the capabilities it provides. Components can be pulled together into an infrastructure by a supervisor, which presents a client interface to subordinate components and a component interface to superordinate clients, aggregating capabilities into higher-level measurements and distributing specifications to perform them.</t>
<t>This arrangement is shown in schematic form in the diagram below.</t>
<figure title="General arrangement of entities in the mPlane architecture" anchor="overview"><artwork><![CDATA[
__________
/ \
| Client |
\ /
-----------
^
| specification/capability/result
v
------------------
| |
| Supervisor |
| |
------------------
^
| specification/capability/result
|
---------------------
| |
v v
/---------\ indirect \____________/
< component >-------->| repository |
\---------/ export \____________/
]]></artwork></figure>
<t>The mPlane protocol is, in essence, a self-describing, error- and delay-tolerant remote procedure call (RPC) protocol: each capability exposes an entry point in the API provided by the component; each specification embodies an API call; and each result returns the results of an API call.</t>
<section anchor="key-architectural-principles-and-features" title="Key Architectural Principles and Features">
<t>mPlane differs from a simple RPC facility in several important ways, detailed in the subsections below.</t>
<section anchor="flexibility-and-extensibility" title="Flexibility and Extensibility">
<t>First, given the heterogeneity of the measurement tools and techniques applied, it is necessary for the protocol to be as flexible and extensible as possible. Therefore, the architecture in its simplest form consists of only two entities and one relationship, as shown in the diagram below: n clients connect to m components via the mPlane protocol. Anything which can speak the mPlane protocol and exposes capabilities thereby is a component; anything which can understand these capabilities and send specifications to invoke them is a client. Everything a component can do, from the point of view of mPlane, is entirely described by its capabilities. Capabilities are even used to expose optional internal features of the protocol itself, and provide a method for built-in protocol extensibility.</t>
</section>
<section anchor="schema-centric-measurement-definition" title="Schema-centric Measurement Definition">
<t>Second, given the flexibility required above, the key to measurement interoperability is the comparison of data types. Each capability, specification, and result contains a schema, comprising the set of parameters required to execute a measurement or query and the columns in the data set that results. From the point of view of mPlane, the schema completely describes the measurement. This implies that when exposing a measurement using mPlane, the developer of a component must build each capabilities it advertises such that the semantics of the measurement are captured by the set of columns in its schema. The elements from which schemas can be built are captured in a type registry. The mPlane platform provides a core registry for common measurement use cases within the project, and the registry facility is itself fully extensible as well, for supporting new applications without requiring central coordination beyond the domain or set of domains running the application.</t>
</section>
<section anchor="iterative-measurement-support" title="Iterative Measurement Support">
<t>Third, the exchange of messages in the protocol was chosen to support iterative measurement in which the aggregated, high-level results of a measurement are used as input to a decision process to select the next measurement. Specifically, the protocol blends control messages (capabilities and specifications) and data messages (results) into a single workflow.</t>
<!-- this is shown in the diagram below.
 -->
</section>
<section anchor="weak-imperativeness" title="Weak Imperativeness">
<t>Fourth, the mPlane protocol is weakly imperative. A capability represents a willingness and an ability to perform a given measurement or execute a query, but not a guarantee or a reservation to do so. Likewise, a specification contains a set of parameters and a temporal scope for a measurement a client wishes a component to perform on its behalf, but execution of specifications is best-effort. A specification is not an instruction which must result either in data or in an error. This property arises from our requirement to support large-scale measurement infrastructures with thousands of similar components, including resource- and connectivity-limited probes such as smartphones and customer-premises equipment (CPE) like home routers. These may be connected to a supervisor only intermittently. In this environment, the operability and conditions in which the probes find themselves may change more rapidly than can be practicably synchronized with a central supervisor; requiring reliable operation would compromise scalability of the architecture.</t>
<t>To support weak imperativeness, each message in the mPlane protocol is self-contained, and contains all the information required to understand the message. For instance, a specification contains the complete information from the capability which it responds to, and a result contains its specification. In essence, this distributes the state of the measurements running in an infrastructure across all components, and any state resynchronization that is necessary after a disconnect happens implicitly as part of message exchange. The failure of a component during a large-scale measurement can be detected and corrected after the fact, by examining the totality of the generated data.</t>
<t>This distribution of state throughout the measurement infrastructure carries with it a distribution of responsibility: a component holding a specification is responsible for ensuring that the measurement or query that the specification describes is carried out, because the client or supervisor which has sent the specification does not necessarily keep any state for it.</t>
<t>Error handling in a weakly imperative environment is different to that in traditional RPC protocols. The exception facility provided by mPlane is designed only to report on failures of the handling of the protocol itself. Each component and client makes its best effort to interpret and process any authorized, well-formed mPlane protocol message it receives, ignoring those messages which are spurious or no longer relevant. This is in contrast with traditional RPC protocols, where even common exceptional conditions are signaled, and information about missing or otherwise defective data must be correlated from logs about measurement control. This traditional design pattern is not applicable in infrastructures where the supervisor has no control over the functionality and availability of its associated probes.</t>
</section>
</section>
<section anchor="entities-and-relationships" title="Entities and Relationships">
<t>The entities in the mPlane protocol and the relationships among them are described in more detail in the subsections below.</t>
<section anchor="components-and-clients" title="Components and Clients">
<t>Specifically, a component is any entity which implements the mPlane protocol specified
within this document, advertises its capabilities and accepts specifications which request the use of those capabilities. The measurements, analyses, storage facilities and other services provided by a component are completely defined by its capabilities.</t>
<t>Conversely, a client is any entity which implements the mPlane protocol, receives capabilities published by one or more components, and sends specifications to those component(s) to perform measurements and analysis.</t>
<t>Every interaction in the mPlane protocol takes place between a component and a client. Indeed, the simplest instantiation of the mPlane architecture consists of one or more clients taking capabilities from one or more components, and sending specifications to invoke those capabilities, as shown in the diagram below. An mPlane domain may consist of as little as a single client and a single component. In this arrangement, mPlane provides a measurement-oriented RPC mechanism.</t>
<figure title="The simplest form of the mPlane architecture" anchor="simple"><artwork><![CDATA[
________________
| |
| client |
| |
----------------
^ n| |
capability | | | specification
| |m v
________________
| |
| component |
| |
----------------
]]></artwork></figure>
</section>
<section anchor="probes-and-repositories" title="Probes and Repositories">
<t>Measurement components can be roughly divided into two categories: probes and repositories. Probes perform measurements, and repositories provide access to stored measurements, analysis of stored measurements, or other access to related external data sources. External databases and data sources (e.g., routing looking glasses, WHOIS services, DNS, etc.) can be made available to mPlane clients through repositories acting as gateways to these external sources, as well.</t>
<t>Note that this categorization is very rough: what a component can do is completely described by its capabilities, and some components may combine properties of both probes and repositories.</t>
</section>
<section anchor="supervisors-and-federation" title="Supervisors and Federation">
<t>An entity which implements both the client and component interfaces can be used to build and federate domains of mPlane components. This supervisor is responsible for collecting capabilities from a set of components, and providing capabilities based on these to its clients. Application-specific algorithms at the supervisor aggregate the lower-level capabilities provided by these components into higher-level capabilities exposed to its clients. This arrangement is shown in the figure below.</t>
<figure title="Simple mPlane architecture with a supervisor" anchor="simple-supervisor"><artwork><![CDATA[
________________
| |
| client |
| |
----------------
^ n| |
capability | | | specification
| |1 v
________________
| |
| component |
/-| |-\
| ---------------- |
| supervisor |
| ________________ |
\-| |-/
| client |
| |
----------------
^ 1| |
capability | | | specification
| |m v
________________
| |
| component |
| |
----------------
]]></artwork></figure>
<t>The set of components which respond to specifications from a single supervisor
is referred to as an mPlane domain. Domain membership is also determined by the issuer of the certificates identifying the clients, components, and supervisor, as detailed in <xref target="access-control-in-https"/>. Within a given domain, each client and component connects to only one supervisor. Underlying measurement components and clients may indeed participate in multiple domains, but these are separate entities from the point of view of the architecture. Interdomain measurement is supported by federation among supervisors: a local supervisor delegates measurements in a remote domain to that domain’s supervisor.</t>
<!-- , as shown in the figure below.
 -->
<t>In addition to capability composition and specification decomposition, supervisors are responsible for client and component registration and authentication, as well as access control based on identity information provided by the session protocol (HTTPS, WebSockets, or SSH) in the general case.</t>
<t>Since the logic for aggregating control and data for a given application is very specific to that application, note that there is no generic supervisor implementation provided with the mPlane SDK.</t>
</section>
<section anchor="external-interfaces-to-mplane-entities" title="External Interfaces to mPlane Entities">
<t>The mPlane protocol specified in this document is designed for the exchange of control messages in an iterative measurement process, and the retrieval of low volumes of highly aggregated data, primarily that leads to decisions about subsequent measurements and/or a final determination.</t>
<t>For measurements generating large amounts of data (e.g. passive observations of high-rate links, or high-frequency active measurements), mPlane supports indirect export. For indirect export, a client or supervisor directs one component (generally a probe) to send results to another component (generally a repository). This indirect export protocol is completely external to the mPlane protocol; the client must only know that the two components support the same protocol and that the schema of the data produced by the probe matches that accepted by the repository. The typical example consists of passive mPlane-controlled probes exporting volumes of data (e.g., anonymized traces, logs, statistics), to an mPlane-accessible repository out-of-band. The use of out-of-band indirect export is justified to avoid serialization overhead, and to ensure fidelity and reliability of the transfer.</t>
<t>For exploratory analysis of large amounts of data at a repository, it is presumed that clients will have additional backchannel direct access beyond those interactions mediated by mPlane. For instance, a repository backed by a relational database could have a web-based graphical user interface that interacts directly with the database.</t>
</section>
</section>
<section anchor="message-types-and-message-exchange-sequences" title="Message Types and Message Exchange Sequences">
<t>The basic messages in the mPlane protocol are capabilities, specifications, and results, as described above. The full protocol contains other message types as well. Withdrawals cancel capabilities (i.e., indicate that the component is no longer capable or willing to perform a given measurement) and interrupts cancel specifications (i.e., indicate that the component should stop performing the measurement). Receipts can be given in lieu of results for not-yet completed measurements or queries, and redemptions can be used to retrieve results referred to by a receipt. Indirections can be used by a component to delegate a specification to a different component. Exceptions can be sent by clients or components at any time to signal protocol-level errors to their peers.</t>
<!--  -->
<t>In the nominal sequence, a capability leads to a specification leads to a result, where results may be transmitted by some other protocol. All the paths through the sequence of messages are shown in the diagram below; message types are described in detail in <xref target="message-types"/>. In the diagram, solid lines mean a message is sent in reply to the previous message in sequence (i.e. a component sends a capability, and a client replies or follows with a specification), and dashed lines mean a message is sent as a followup (i.e., a component sends a capability, then sends a withdrawal to cancel that capability). Messages at the top of the diagram are sent by components, at the bottom by clients.</t>
<t>Separate from the sequence of messages, the mPlane protocol supports two connection establishment patterns:</t>
<t><list style="symbols">
<t>Client-initiated in which clients connect directly to components at known, stable, routable URLs. Client-initiated workflows are intended for use between clients and supervisors, for access to repositories, and for access to probes embedded within a network infrastructure.</t>
<t>Component-initiated in which components initiate connections to clients. Component-initiated workflows are intended for use between components without stable routable addresses and supervisors, e.g. for small probes on embedded devices, mobile devices, or software probes embedded in browsers on personal computers behind network-address translators (NATs) or firewalls which prevent a client from establishing a connection to them.</t>
</list></t>
<t>Within a given mPlane domain, these patterns can be combined (along with indirect export and direct access) to facilitate complex interactions among clients and components according to the requirements imposed by the application and the deployment of components in the network.</t>
</section>
<section anchor="integrating-measurement-tools-into-mplane" title="Integrating Measurement Tools into mPlane">
<t>mPlane’s flexibility and the self-description of measurements provided by the capability-specification-result cycle was designed to allow a wide variety of existing measurement tools, both probes and repositories, to be integrated into an mPlane domain. In both cases, the key to integration is to define a capability for each of the measurements the tool can perform or the queries the repository needs to make available within an mPlane domain. Each capability has a set of parameters - information required to run the measurement or the query - and a set of result columns - information which the measurement or query returns.
The parameters and result columns make up the measurement’s schema, and are chosen from an extensible registry of elements. Practical details are given in <xref target="designing-measurement-and-repository-schemas"/>.</t>
</section>
<section anchor="from-architecture-to-protocol-specification" title="From Architecture to Protocol Specification">
<t>The remainder of this document builds the protocol specification based on this architecture from the bottom up. First, we define the protocol’s information model from the element registry through the types of mPlane messages and the sections they are composed of. We then define a concrete representation of this information model using Javascript Object Notation (JSON, <xref target="RFC7159"/>), and define bindings to HTTP over TLS as a session protocol. Finally, we show how to construct workflows using the protocol to build up complex measurement infrastructures, and detail the responsibilities of an mPlane supervisor.</t>
</section>
</section>
<section anchor="protocol-information-model" title="Protocol Information Model">
<t>The mPlane protocol is message-oriented, built on the representation- and session-protocol-independent exchange of messages between clients and components. This section describes the information model, starting from the element registry which defines the elements from which capabilities can be built, then detailing each type of message, and the sections that make these messages up. It then provides advice on using the information model to model measurements and queries.</t>
<section anchor="element-registry" title="Element Registry">
<t>An element registry makes up the vocabulary by which mPlane components and clients can express the meaning of parameters, metadata, and result columns for mPlane statements. A registry is represented as a JSON <xref target="RFC7159"/> object with the following keys:</t>
<t><list style="symbols">
<t>registry-format: currently <spanx style="verb">mplane-0</spanx>, determines the supported features of the registry format.</t>
<t>registry-uri: the URI identifying the registry. The URI must be dereferencable to retrieve the canonical version of this registry.</t>
<t>registry-revision: a serial number starting with 0 and incremented with each revision to the content of the registry.</t>
<t>includes: a list of URLs to retrieve additional registries from. Included registries will be evaluated in depth-first order, and elements with identical names will be replaced by registries parsed later.</t>
<t>elements: a list of objects, each of which has the following three keys:
<list style="symbols">
<t>name: The name of the element.</t>
</list></t>
<t>prim: The name of the primitive type of the element, from the list of primitives in <xref target="primitive-types"/>.
<list style="symbols">
<t>desc: An English-language description of the meaning of the element.</t>
</list></t>
</list></t>
<t>Since the element names will be used as keys in mPlane messages, mPlane binds to JSON, and JSON mandates lowercase key names, element names must use only lowercase letters.</t>
<t>An example registry with two elements and no includes follows:</t>
<figure><artwork><![CDATA[
{ "registry-format": "mplane-0",
"registry-uri", "http://ict-mplane.eu/registry/core",
"registry-revision": 0,
"includes": [],
"elements": [
{ "name": "full.structured.name",
"prim": "string",
"desc": "A representation of foo..."
},
{ "name": "another.structured.name",
"prim": "string",
"desc": "A representation of bar..."
},
]
}
]]></artwork></figure>
<t>Fully qualified element names consist of the element’s name as an anchor after the URI from which the element came, e.g. <spanx style="verb">http://ict-mplane.eu/registry/core#full.structured.name</spanx>. Elements within the type registry are considered globally equal based on their fully qualified names. However, within a given mPlane message, elements are considered equal based on unqualified names.</t>
<section anchor="structured-element-names" title="Structured Element Names">
<t>To ease understanding of mPlane type registries, element names are structured by convention; that is, an element name is made up of the following structural parts in order, separated by the dot (‘.’) character:</t>
<t><list style="symbols">
<t>basename: exactly one, the name of the property the element specifies or measures. All elements with the same basename describe the same basic property. For example, all elements with basename ‘<spanx style="verb">source</spanx>’ relate to the source of a packet, flow, active measurement, etc.; and elements with basename ‘<spanx style="verb">delay</spanx>’’ relate to the measured delay of an operation.</t>
<t>modifier: zero or more, additional information differentiating elements with the same basename from each other. Modifiers may associate the element with a protocol layer, or a particular variety of the property named in the basename. All elements with the same basename and modifiers refer to exactly the same property. Examples for the <spanx style="verb">delay</spanx> basename include <spanx style="verb">oneway</spanx> and <spanx style="verb">twoway</spanx>, differentiating whether a delay refers to the path from the source to the destination or from the source to the source via the destination; and <spanx style="verb">icmp</spanx> and <spanx style="verb">tcp</spanx>, describing the protocol used to measure the delay.</t>
<t>units: zero or one, present if the quantity can be measured in different units.</t>
<t>aggregation: zero or one, if the property is a metric derived from multiple singleton measurements. Supported aggregations are:
<list style="symbols">
<t><spanx style="verb">min</spanx>: minimum value</t>
<t><spanx style="verb">max</spanx>: maximum value</t>
<t><spanx style="verb">mean</spanx>: mean value</t>
<t><spanx style="verb">sum</spanx>: sum of values</t>
<t><spanx style="verb">NNpct</spanx> (where NN is a two-digit number 01-99): percentile</t>
<t><spanx style="verb">median</spanx>: shorthand for and equivalent to <spanx style="verb">50pct</spanx>.</t>
<t><spanx style="verb">count</spanx>: count of values aggregated</t>
</list></t>
</list></t>
<t>When mapping mPlane structured names into contexts in which dots have special meaning (e.g. SQL column names or variable names in many programming languages), the dots may be replaced by underscores (‘_’). When using external type registries (e.g. the IPFIX Information Element Registry), element names are not necessarily structured.</t>
</section>
<section anchor="primitive-types" title="Primitive Types">
<t>The mPlane protocol supports the following primitive types for elements in the type registry:</t>
<t><list style="symbols">
<t>string: a sequence of Unicode characters</t>
<t>natural: an unsigned integer</t>
<t>real: a real (floating-point) number</t>
<t>bool: a true or false (boolean) value</t>
<t>time: a timestamp, expressed in terms of UTC. The precision of the timestamp is taken to be unambiguous based on its representation.</t>
<t>address: an identifier of a network-level entity, including an address family. The address family is presumed to be implicit in the format of the message, or explicitly stored. Addresses may represent specific endpoints or entire networks.</t>
<t>url: a uniform resource locator</t>
</list></t>
</section>
<section anchor="augmented-registry-information" title="Augmented Registry Information">
<t>Additional keys beyond prim, desc, and name may appear in an mPlane registry to augment information about each element; these are not presently used by the SDK’s information model but may be used by software built around the SDK.</t>
<t>Elements in the core registry at <spanx style="verb">http://ict-mplane.eu/registry/core</spanx> may contain the following augmented registry keys:</t>
<t><list style="symbols">
<t>units: If applicable, units in which the element is expressed; equal to the units part of a structured name if present.</t>
<t>ipfix-eid: The element ID of the equivalent IPFIX <xref target="RFC7011"/> Information Element.</t>
<t>ipfix-pen: The SMI Private Enterprise Number of the equivalent IPFIX Information Element, if any.</t>
</list></t>
</section>
</section>
<section anchor="message-types" title="Message Types">
<t>Workflows in mPlane are built around the capability - specification - result cycle. Capabilities, specifications, and results are kinds of statements: a capability is a statement that a component can perform some action (generally a measurement); a specification is a statement that a client would like a component to perform the action advertised in a capability; and a result is a statement that a component measured a given set of values at a given point in time according to a specification.</t>
<t>Other types of messages outside this nominal cycle are referred to as notifications. Types of notifications include Withdrawals, Interrupts, Receipts, Redemptions, Indirections, and Exceptions. These notify clients or components of conditions within the measurement infrastructure itself, as opposed to directly containing information about measurements or observations.</t>
<t>Messages may also be grouped together into a single envelope message. Envelopes allow multiple messages to be represented within a single message, for example multiple Results pertaining to the same Receipt; and multiple Capabilities or Specifications to be transferred in a single transaction in the underlying session protocol.</t>
<t>The following types of messages are supported by the mPlane protocol:</t>
<section anchor="capability-and-withdrawal" title="Capability and Withdrawal">
<t>A capability is a statement of a component’s ability and willingness to perform a specific operation, conveyed from a component to a client. It does not represent a guarantee that the specific operation can or will be performed at a specific point in time.</t>
<t>A withdrawal is a notification of a component’s inability or unwillingness to perform a specific operation. It cancels a previously advertised capability. A withdrawal can also be sent in reply to a specification which attempts to invoke a capability no longer offered.</t>
</section>
<section anchor="specification-and-interrupt" title="Specification and Interrupt">
<t>A specification is a statement that a component should perform a specific
operation, conveyed from a client to a component. It can be
conceptually viewed as a capability whose parameters have been filled in with
values.</t>
<t>An interrupt is a notification that a component should stop performing a specific operation, conveyed from client to component. It terminates a previously sent specification. If the specification uses indirect export, the indirect export will simply stop running. If the specification has pending results, those results are returned in response to the interrupt.</t>
</section>
<section anchor="result" title="Result">
<t>A result is a statement produced by a component that a particular measurement
was taken and the given values were observed, or that a particular operation or
analysis was performed and a the given values were produced. It can be
conceptually viewed as a specification whose result columns have been filled in with
values. Note that, in keeping with the stateless nature of the mPlane protocol, a
result contains the full set of parameters from which it was derived.</t>
<t>Note that not every specification will lead to a result being returned; for example,
in case of indirect export, only a receipt which can be used for future interruption
will be returned, as the results will be conveyed to a third component using an
external protocol.</t>
</section>
<section anchor="receipt-and-redemption" title="Receipt and Redemption">
<t>A receipt is returned instead of a result by a component in response to a specification which either:</t>
<t><list style="symbols">
<t>will never return results, as it initiated an indirect export, or</t>
<t>will not return results immediately, as the operation producing the results will have a long run time.</t>
</list></t>
<t>Receipts have the same content specification they are returned for.
A component may optionally add a token section, which can be used
in future redemptions or interruptions by the client. The content of
the token is an opaque string generated by the component.</t>
<t>A redemption is sent from a client to a component for a previously received receipt to attempt to retrieve delayed results. It may contain only the token section, or all sections of the received receipt.</t>
</section>
<section anchor="indirection" title="Indirection">
<t>An indirection is returned instead of a result by a component to indicate that the client should contact another component for the desired result.</t>
</section>
<section anchor="exception" title="Exception">
<t>An exception is sent from a client to a component or from a component to a client to signal an exceptional condition within the infrastructure itself. They are not meant to signal exceptional conditions within a measurement performed by a component; see <xref target="error-handling-in-mplane-workflows"/> for more. An exception contains only two sections: an optional token referring back to the message to which the exception is related (if any), and a message section containing free-form, preferably human readable information about the exception.</t>
</section>
<section anchor="envelope" title="Envelope">
<t>An envelope is used to contain other messages. Message containment is necessary in contexts in which multiple mPlane messages must be grouped into a single transaction in the underlying session protocol. It is legal to group any kind of message, and to mix messages of different types, in an envelope. However, in the current revision of the protocol, envelopes are primarily intended to be used for three distinct purposes:</t>
<t><list style="symbols">
<t>To return multiple results for a single receipt or specification if appropriate (e.g., if a specification has run repeated instances of a measurement on a schedule).</t>
<t>To group multiple capabilities together within a single message (e.g., all the capabilities a given component has).</t>
<t>To group multiple specifications into a single message (e.g., to simultaneously send a measurement specification along with a callback control specification).</t>
</list></t>
</section>
</section>
<section anchor="message-sections" title="Message Sections">
<t>Each message is made up of sections, as described in the subsection below. The following table shows the presence of each of these sections in each of the message types supported by mPlane: “req.” means the section is required, “opt.” means it is optional; see the subsection on each message section for details.</t>
<figure title="Message Sections for Each Message Type" anchor="table-messages"><artwork><![CDATA[
| Section | Capability | Spec. | Result | Receipt | Envelope |
| -------------- | ---------- | ----- | ------ |------------|----------|
| Verb | req. | req | req. | req. | |
| Content Type | | | | | req. |
| `version` | req. | req. | req. | req. | req. |
| `registry` | req. | req. | req. | opt. | |
| `label` | opt. | opt. | opt. | opt. | opt. |
| `when` | req. | req. | req. | req. | |
| `parameters` | req./token | req. | req. | opt./token | |
| `metadata` | opt./token | opt. | opt. | opt./token | |
| `results` | req./token | req. | req. | opt./token | |
| `resultvalues` | | | req. | | |
| `export` | opt. | opt. | opt. | opt. | |
| `link` | opt. | opt. | | | |
| `token` | opt. | opt. | opt. | opt. | opt. |
| `contents` | | | | | req. |
]]></artwork></figure>
<t>Withdrawals and indirections take the same sections as capabilities; and redemptions
and interrupts take the same sections as receipts. Exceptions are not shown in this table.</t>
<section anchor="message-type-and-verb" title="Message Type and Verb">
<t>The verb is the action to be performed by the component. The following verbs
are supported by the base mPlane protocol, but arbitrary verbs may be specified
by applications:</t>
<t><list style="symbols">
<t><spanx style="verb">measure</spanx>: Perform a measurement</t>
<t><spanx style="verb">query</spanx>: Query a database about a past measurement</t>
<t><spanx style="verb">collect</spanx>: Receive results via indirect export</t>
<t><spanx style="verb">callback</spanx>: Used for callback control in component-initiated workflows</t>
</list></t>
<t>In the JSON representation of mPlane messages, the verb is the value of the key corresponding to the message’s type, represented as a lowercase string (e.g. <spanx style="verb">capability</spanx>, <spanx style="verb">specification</spanx>, <spanx style="verb">result</spanx> and so on).</t>
<t>Roughly speaking, probes implement <spanx style="verb">measure</spanx> capabilities, and repositories
implement <spanx style="verb">query</spanx> and <spanx style="verb">collect</spanx> capabilities. Of course, any single component
can implement capabilities with any number of different verbs.</t>
<t>Within the SDK, the primary difference between <spanx style="verb">measure</spanx> and <spanx style="verb">query</spanx> is that the temporal scope of a <spanx style="verb">measure</spanx> specification is taken to refer to when the measurement should be scheduled, while the temporal scope of a <spanx style="verb">query</spanx> specification is taken to refer to the time window (in the past) of a query.</t>
<t>Envelopes have no verb; instead, the value of the <spanx style="verb">envelope</spanx> key is the kind of messages the envelope contains, or <spanx style="verb">message</spanx> if the envelope contains a mixture of different unspecified kinds of messages.</t>
</section>
<section anchor="version" title="Version">
<t>The <spanx style="verb">version</spanx> section contains the version of the mPlane protocol to which the message conforms, as an integer serially incremented with each new protocol revision. This section is required in all messages. This document describes version 1 of the protocol.</t>
</section>
<section anchor="registry" title="Registry">
<t>The <spanx style="verb">registry</spanx> section contains the URL identifying the element registry used by this message, and from which the registry can be retrieved. This section is required in all messages containing element names (statements, and receipts/redemptions/interrupts not using tokens for identification; see the <spanx style="verb">token</spanx> section). The default core registry for mPlane is identified by:</t>
<t><spanx style="verb">http://ict-mplane.eu/registry/core</spanx>.</t>
</section>
<section anchor="label" title="Label">
<t>The <spanx style="verb">label</spanx> section of a statement contains a human-readable label identifying it, intended solely for use when displaying information about messages in user interfaces. Results, receipts, redemptions, and interrupts inherit their label from the specification from which they follow; otherwise, client and component software can arbitrarily assign labels . The use of labels is optional in all messages, but as labels do greatly ease human-readability of arbitrary messages within user interfaces, their use is recommended.</t>
<t>mPlane clients and components should never use the label as a unique identifier for a message, or assume any semantic meaning in the label – the test of message equality and relatedness is always based upon the schema and values as in <xref target="message-uniqueness-and-idempotence"/>.</t>
</section>
<section anchor="temporal-scope" title="Temporal Scope (When)">
<t>The <spanx style="verb">when</spanx> section of a statement contains its temporal scope.</t>
<t>A temporal scope refers to when a measurement can be run (in a capability), when it should be run (in a specification), or when it was run (in a result). Temporal scopes can be either absolute or relative, and may have an optional period, referring to how often single measurements should be taken.</t>
<t>The general form of a temporal scope (in BNF-like syntax) is as follows:</t>
<figure><artwork><![CDATA[
simple-when = <singleton> | # A single point in time
<range> | # A range in time
<range> ' / ' <duration> # A range with a period
singleton = <iso8601> | # absolute singleton
'now' # relative singleton
range = <iso8601> ' ... ' <iso8601> | # absolute range
<iso8601> ' + ' <duration> | # relative range
'now' ' ... ' <iso8061> | # definite future
'now' ' + ' <duration> | # relative future
<iso8601> ' ... ' 'now' | # definite past
'past ... now' | # indefinite past
'now ... future' | # indefinite future
<iso8601> ' ... ' 'future' | # absolute indefinite future
'past ... future' | # forever
duration = [ <n> 'd' ] # days
[ <n> 'h' ] # hours
[ <n> 'm' ] # minute
[ <n> 's' ] # seconds
iso8601 = <n> '-' <n> '-' <n> [' ' <n> ':' <n> ':' <n> [ '.' <n> ]]
]]></artwork></figure>
<t>All absolute times are always given in UTC and expressed in ISO8601 format with variable precision.</t>
<t>In capabilities, if a period is given it represents the minimum period supported by the measurement; this is done to allow rate limiting. If no period is given, the measurement is not periodic. A capability with a period can only be fulfilled by a specification with period greater than or equal to the period in the capability. Conversely, a capability without a period can only be fulfilled by a specification without a period.</t>
<t>Within a result, only absolute ranges are allowed within the temporal scope, and refers to the time range of the measurements contributing to the result. Note that the use of absolute times here implies that the components and clients within a domain should have relatively well-synchronized clocks, e.g., to be synchronized using the Network Time Protocol <xref target="RFC5905"/> in order for results to be temporally meaningful.</t>
<t>So, for example, an absolute range in time might be expressed as:</t>
<t><spanx style="verb">when: 2009-02-20 13:02:15 ... 2014-04-04 04:27:19</spanx></t>
<t>A relative range covering three and a half days might be:</t>
<t><spanx style="verb">when: 2009-04-04 04:00:00 + 3d12h</spanx></t>
<t>In a specification for running an immediate measurement for three hours every seven and a half minutes:</t>
<t><spanx style="verb">when: now + 3h / 7m30s</spanx></t>
<t>In a capability noting that a Repository can answer questions about the past:</t>
<t><spanx style="verb">when: past ... now</spanx>.</t>
<t>In a specification requesting that a measurement run from a specified point in time until interrupted:</t>
<t><spanx style="verb">when: 2017-11-23 18:30:00 ... future</spanx></t>
<section anchor="repeating-measurements" title="Repeating Measurements">
<t>Within specifications, the temporal scope can be extended to support
repeated measurement. A repeated specification is conceptually
equivalent to a specification that is sent from the client to the
component once, then retained at the component and initiated multiple times.</t>
<t>The general form of a temporal scope in a repeated specification is as follows (BNF-like syntax):</t>
<figure><artwork><![CDATA[
repeated-when = # implicit inner scope of now
'repeat' <outer-when> |
# simple range/period
'repeat' <outer-when> '{' <inner-when> '}' |
# with crontab
'repeat' <range> 'cron' <crontab> '{' <inner-when> '}'
outer-when = <range> ' / ' <duration>
inner-when = 'now' |
'now' ' + ' <duration> |
'now' ' + ' <duration> / <duration>
crontab = <seconds> <minutes> <hours>
<days-of-month> <days-of-week> <months>
seconds = '*' | <seconds-or-minutes-list>
minutes = '*' | <seconds-or-minutes-list>
seconds-or-minutes-list = <n> [ ',' <seconds-or-minutes-list> ]
hours = '*' | <hours-list>
hours-list = <n> [ ',' <hour-list> ] # 0<=n<24
days-of-month = '*' | <days-of-month-list>
days-of-month-list = <n> [ ',' <days-of-month-list> ] # 0<n<=31
days-of-week = '*' | <days-of-week-list>
days-of-week-list = <n> [ ',' <days-of-week-list> ] # 0<=n<=7
# 0 = Sunday, 1 = Monday, ..., 7 = Sunday
months = '*' | <months-list>
months-list = <n> [ ',' <months-list> ] # 0<n<=12
when = <simple-when> | <repeated-when>
]]></artwork></figure>
<t>A repeated specification consists of an outer temporal specification that governs how often and for how long the specification will repeat, and an inner temporal specification which applies to each individual repetition. The inner temporal specification must always be relative to the current time, i.e. the time of initiated of the repeated specification. If the inner temporal specification is omitted, the specification is presumed to have the relative singleton temporal scope of <spanx style="verb">now</spanx>.</t>
<t>A repeated specification can have a cron-like schedule. In this case
the outer temporal specification only consists of a
range scope to determine the time frame in which the cron-like
schedule is valid. The crontab states the seconds, minutes,
hours, days of the week, days of the month, and months at which the
specification will repeat. An asterisk means to repeat at all
legal values for that field. The specification is only repeated
if all fields match.</t>
<t>Submitting a repeated specification will still result in a single receipt, or in multiple results. These multiple results, resulting either directly from a single repeated specification, or from the a redemption of a receipt resulting from a repeated specification, are grouped in an envelope message.</t>
<t>For example, a repeated specification to take measurements every second for five minutes, repeating once an hour indefinitely would be:</t>
<t><spanx style="verb">when: repeat now ... future / 1h { now + 5m / 1s }</spanx></t>
<t>This repeated specification is equivalent to the repeated submission of the same specification with a temporal scope of <spanx style="verb">when: { now + 5m / 1s }</spanx> once an hour until the specification is cancelled with an interrupt notification.</t>
<t>As a second example, a repeated specification to take measurements every second for five minutes, repeating every half hour within a specific timeframe would be:</t>
<t><spanx style="verb">when: repeat 2014-01-01 13:00:00 ... 2014-06-01 14:00:00 / 30m { now + 5m / 1s }</spanx></t>
<t>Likewise, this repeated specification is equivalent to the submission of the same specification with a temporal scope of <spanx style="verb">when: { now + 5m / 1s }</spanx> at <spanx style="verb">2014-01-01 13:00:00</spanx>, <spanx style="verb">2014-01-01 13:30:00</spanx>, <spanx style="verb">2014-01-01 14:00:00</spanx>, <spanx style="verb">2014-01-01 14:30:00</spanx>, and so on =, until (and including) <spanx style="verb">2014-06-01 13:30:00</spanx> and <spanx style="verb">2014-06-01 14:00:00</spanx>.</t>
<t>A repeated specification taking singleton measurements every hour indefinitely with an implicit inner temporal specification:</t>
<t><spanx style="verb">when: repeat now ... future / 1h</spanx></t>
<t>equivalent to submitting a specification with the temporal scope <spanx style="verb">now</spanx> hourly forever until interrupted.</t>
<t>A crontab specification which is repeated on the first Monday of each
month measuring every hour on that day for 5 minutes would be:
\texttt{when: repeat now … future cron 0 0 * 1,2,3,4,5,6,7 1 * { now + 5m } }</t>
<t>A repeated specification to take measurements each day
of the year at midnight would be:
\texttt{when: repeat now … future cron 0 0 0 * * * }</t>
</section>
</section>
<section anchor="parameters" title="Parameters">
<t>The <spanx style="verb">parameters</spanx> section of a message contains an ordered list of the parameters for a given measurement: values which must be provided by a client to a component in a specification to convey the specifics of the measurement to perform. Each parameter in an mPlane message is a key-value pair, where the key is the name of an element from the element registry. In specifications and results, the value is the value of the parameter. In capabilities, the value is a constraint on the possible values the component will accept for the parameter in a subsequent specification.</t>
<t>Four kinds of constraints are currently supported for mPlane parameters:</t>
<t><list style="symbols">
<t>No constraint: all values are allowed. This is signified by the special constraint string ‘<spanx style="verb">*</spanx>’.</t>
<t>Single value constraint: only a single value is allowed. This is intended for use for capabilities which are conceivably configurable, but for which a given component only supports a single value for a given parameter due to its own out-of-band configuration or the permissions of the client for which the capability is valid. For example, the source address of an active measurement of a single-homed probe might be given as ‘<spanx style="verb">source.ip4: 192.0.2.19</spanx>’.</t>
<t>Set constraint: multiple values are allowed, and are explicitly listed, separated by the ‘<spanx style="verb">,</spanx>’ character. For example, a multi-homed probe allowing two potential source addresses on two different networks might be given as ‘<spanx style="verb">source.ip4: 192.0.2.19, 192.0.3.21</spanx>’.</t>
<t>Range constraint: multiple values are allowed, between two ordered values, separated by the special string ‘<spanx style="verb">...</spanx>’. Range constraints are inclusive. A measurement allowing a restricted range of source ports might be expressed as ‘<spanx style="verb">source.port: 32768 ... 65535</spanx>’</t>
<t>Prefix constraint: multiple values are allowed within a single network, as specified by a network address and a prefix. A prefix constraint may be satisfied by any network of host address completely contained within the prefix. An example allowing probing of any host within a given /24 might be ‘<spanx style="verb">destination.ip4: 192.0.2.0/24</spanx>’.</t>
</list></t>
<t>Parameter and constraint values must be a representation of an instance of the primitive type of the associated element.</t>
</section>
<section anchor="metadata" title="Metadata">
<t>The <spanx style="verb">metadata</spanx> section contains measurement metadata: key-value pairs associated with a capability inherited by its specification and results. Metadata can also be thought of as immutable parameters. This is intended to represent information which can be used to make decisions at the client as to the applicability of a given capability (e.g. details of algorithms used or implementation-specific information) as well as to make adjustments at post-measurement analysis time when contained within results.</t>
<t>An example metadata element might be ‘<spanx style="verb">measurement.identifier: qof</spanx>’, which identifies the underlying tool taking measurements, such that later analysis can correct for known peculiarities in the implementation of the tool. Another example might be ‘<spanx style="verb">location.longitude = 8.55272</spanx>’, which while not particularly useful for analysis purposes, can be used to draw maps of measurements.</t>
</section>
<section anchor="result-columns-and-values" title="Result Columns and Values">
<t>Results are represented using two sections: <spanx style="verb">results</spanx> which identify the elements to be returned by the measurement, and <spanx style="verb">resultvalues</spanx> which contains the actual values. <spanx style="verb">results</spanx> appear in all statements, while <spanx style="verb">resultvalues</spanx> appear only in result messages.</t>
<t>The <spanx style="verb">results</spanx> section contains an ordered list of result columns for a given measurement: names of elements which will be returned by the measurement. The result columns are identified by the names of the elements from the element registry.</t>
<t>The <spanx style="verb">resultvalues</spanx> section contains an ordered list of ordered lists (or, rather, a two dimensional array) of values of results for a given measurement, in row-major order. The columns in the result values appear in the same order as the columns in the <spanx style="verb">results</spanx> section.</t>
<t>Values for each column must be a representation of an instance of the primitive type of the associated result column element.</t>
</section>
<section anchor="export" title="Export">
<t>The <spanx style="verb">export</spanx> section contains a URL or partial URL for indirect export. Its meaning depends on the kind and verb of the message:</t>
<t><list style="symbols">
<t>For capabilities with the <spanx style="verb">collect</spanx> verb, the <spanx style="verb">export</spanx> section contains the URL of the collector which can accept indirect export for the schema defined by the <spanx style="verb">parameters</spanx> and <spanx style="verb">results</spanx> sections of the capability, using the protocol identified by the URL’s schema.</t>
<t>For capabilities with any verb other than <spanx style="verb">collect</spanx>, the <spanx style="verb">export</spanx> section contains either the URL of a collector to which the component can indirectly export results, or a URL schema identifying a protocol over which the component can export to arbitrary collectors.</t>
<t>For specifications with any verb other than <spanx style="verb">collect</spanx>, the <spanx style="verb">export</spanx> section contains the URL of a collector to which the component should indirectly export results. A receipt will be returned for such specifications.</t>
</list></t>
<t>If a component can indirectly export or indirectly collect using multiple protocols, each of those protocols must be identified by its own capability; capabilities with an <spanx style="verb">export</spanx> section can only be used by specifications with a matching <spanx style="verb">export</spanx> section.</t>
<t>The special export schema <spanx style="verb">mplane-https</spanx> implies that the exporter will POST mPlane result messages to the collector at the specified URL. All other export schemas are application-specific, and the mPlane protocol implementation is only responsible for ensuring the schemas and protocol identifiers match between collector and exporter.</t>
</section>
<section anchor="link" title="Link">
<t>The <spanx style="verb">link</spanx> section contains the URL to which messages in the next step in the workflow (i.e. a specification for a capability, a result or receipt for a specification) can be sent, providing indirection. The link URL must currently have the schema <spanx style="verb">mplane-https</spanx>, and refers to posting of messages via HTTP <spanx style="verb">POST</spanx>.</t>
<t>If present in a capability, the client must <spanx style="verb">POST</spanx> specifications for the given capability to the component at the URL given in order to use the capability, as opposed to simply posting them to the known or assumed URL for a component. If present in a specification, the component must <spanx style="verb">POST</spanx> results for the given specification back to the client at the URL given. See the section on workflows below for details.</t>
<t>If present in an indirection message returned for a specification by a component, the client must send the specification to the component at the URL given in the link in order to retrieve results or initiate measurement.</t>
</section>
<section anchor="token" title="Token">
<t>The <spanx style="verb">token</spanx> section contains an arbitrary string by which a message may be identified in subsequent communications in an abbreviated fashion. Unlike labels, tokens are not necessarily intended to be human-readable; instead, they provide a way to reduce redundancy on the wire by replacing the parameters, metadata, and results sections in messages within a workflow, at the expense of requiring more state at clients and components. Their use is optional.</t>
<t>Tokens are scoped to the association between the component and client in which they are first created; i.e., at a component, the token will be associated with the client’s identity, and vice-versa at a client. Tokens should be created with sufficient entropy to avoid collision from independent processes at the same client or token reuse in the case of client or component state loss at restart.</t>
<t>If a capability contains a token, it may be subsequently withdrawn by the same component using a withdrawal containing the token instead of the parameters, metadata, and results sections.</t>
<t>If a specification contains a token, it may be answered by the component with a receipt containing the token instead of the parameters, metadata, and results sections. A specification containing a token may likewise be interrupted by the client with an interrupt containing the token. A component must not answer a specification with a token with a receipt or result containing a different token, but the token may be omitted in subsequent receipts and results.</t>
<t>If a receipt contains a token, it may be redeemed by the same client using a redemption containing the token instead of the parameters, metadata, and results sections.</t>
<t>When grouping multiple results from a repeating specification into an envelope, the envelope may contain the token of the repeating specification.</t>
</section>
<section anchor="contents" title="Contents">
<t>The <spanx style="verb">contents</spanx> section appears only in envelopes, and is an ordered list of messages. If the envelope’s kind identifies a message kind, the contents may contain only messages of the specified kind, otherwise if the kind is <spanx style="verb">message</spanx>, the contents may contain a mix of any kind of message.</t>
</section>
</section>
<section anchor="message-uniqueness-and-idempotence" title="Message Uniqueness and Idempotence">
<t>Messages in the mPlane protocol are intended to support state distribution: capabilities, specifications, and results are meant to be complete declarations of the state of a given measurement. In order for this to hold, it must be possible for messages to be uniquely identifiable, such that duplicate messages can be recognized. With one important exception (i.e., specifications with relative temporal scopes), messages are idempotent: the receipt of a duplicate message at a client or component is a null operation.</t>
<section anchor="message-schema" title="Message Schema">
<t>The combination of elements in the <spanx style="verb">parameters</spanx> and <spanx style="verb">results</spanx> sections, together with the registry from which these elements are drawn, is referred to as a message’s schema. The schema of a measurement can be loosely thought of as the definition of the table, rows of which the message represents.</t>
<t>The schema contributes not only to the identity of a message, but also to the semantic interpretation of the parameter and result values. The meanings of element values in mPlane are dependent on the other elements present in the message; in other words, the key to interpreting an mPlane message is that the unit of semantic identity is a message. For example, the element ‘<spanx style="verb">destination.ip4</spanx>’ as a parameter means “the target of a given active measurement” when together with elements describing an active metric (e.g. ‘<spanx style="verb">delay.twoway.icmp.us</spanx>’), but “the destination of the packets in a flow” when together with other elements in result columns describing a passively-observed flow.</t>
<t>The interpretation of the semantics of an entire message is application-specific. The protocol does not forbid the transmission of messages representing semantically meaningless or ambiguous schemas.</t>
</section>
<section anchor="message-identity" title="Message Identity">
<t>A message’s identity is composed of its schema, together with its temporal scope, metadata, parameter values, and indirect export properties. Concretely, the full content of the <spanx style="verb">registry</spanx>, <spanx style="verb">when</spanx>, <spanx style="verb">parameters</spanx>, <spanx style="verb">metadata</spanx>, <spanx style="verb">results</spanx>, and <spanx style="verb">export</spanx> sections taken together comprise the message’s identity.</t>
<t>One convenience feature complicates this somewhat: when the temporal scope is not absolute, multiple specifications may have the same literal temporal scope but refer to different measurements. In this case, the current time at the client or component when a message is invoked must be taken as part of the message’s identity as well. Implementations may use hashes over the values of the message’s identity sections to uniquely identify messages; e.g. to generate message tokens.</t>
</section>
</section>
<section anchor="designing-measurement-and-repository-schemas" title="Designing Measurement and Repository Schemas">
<t>As noted, the key to integrating a measurement tool into an mPlane infrastructure is properly defining the schemas for the measurements and queries it performs, then defining those schemas in terms of mPlane capabilities. Specifications and results follow naturally from capabilities, and the mPlane SDK allows Python methods to be bound to capabilities in order to execute them. A schema should be defined such that the set of parameters, the set of result columns, and the verb together naturally and uniquely define the measurement or the query being performed. For simple metrics, this is achieved by encoding the entire meaning of the metric in its name. For example, <spanx style="verb">delay.twoway.icmp.us</spanx> as a result column together with <spanx style="verb">source.ip4</spanx> and <spanx style="verb">destination.ip4</spanx> as parameters uniquely defines a single ping measurement, measured via ICMP, expressed in microseconds.</t>
<t>Aggregate measurements are defined by returning metrics with aggregations: <spanx style="verb">delay.twoway.icmp.min.us</spanx>, <spanx style="verb">delay.twoway.icmp.max.us</spanx>, <spanx style="verb">delay.twoway.icmp.mean.us</spanx>, and <spanx style="verb">delay.twoway.icmp.count.us</spanx> as result columns represent aggregate ping measurements with multiple samples.</t>
<t>Note that mPlane results may contain multiple rows. In this case, the parameter values in the result, taken from the specification, apply to all rows. In this case, the rows are generally differentiated by the values in one or more result columns; for example, the <spanx style="verb">time</spanx> element can be used to represent time series, or the <spanx style="verb">hops.ip</spanx> different elements along a path between source and destination, as in a traceroute measurement.</t>
<t>For measurements taken instantaneously, the verb <spanx style="verb">measure</spanx> should be used; for direct queries from repositories, the verb <spanx style="verb">query</spanx> should be used. Other actions that cannot be differentiated by schema alone should be differentiated by a custom verb.</t>
<t>When integrating a repository into an mPlane infrastructure, only a subset of the queries the repository can perform will generally be exposed via the mPlane interface. Consider a generic repository which provides an SQL interface for querying data; wrapping the entire set of possible queries in specific capabilities would be impossible, while providing direct access to the underlying SQL (for instance, by creating a custom registry with a <spanx style="verb">query.sql</spanx> string element to be used as a parameter) would make it impossible to differentiate capabilities by schema (thereby making the interoperability benefits of mPlane integration pointless). Instead, specific queries to be used by clients in concert with capabilities provided by other components are each wrapped within a separate capability, analogous to stored procedure programming in many database engines. Of course, clients which do speak the precise dialect of SQL necessary can integrate directly with the repository separate from the capabilities provided over mPlane.</t>
</section>
</section>
<section anchor="representations-and-session-protocols" title="Representations and Session Protocols">
<t>The mPlane protocol is built atop an abstract data model in order to support multiple representations and session protocols. The canonical representation supported by the present SDK involves JSON <xref target="RFC7159"/> objects transported via HTTP <xref target="RFC7230"/> over TLS <xref target="RFC5246"/> (commonly known as HTTPS).</t>
<section anchor="json-representation" title="JSON representation">
<t>In the JSON representation, an mPlane message is a JSON object, mapping sections by name to their contents. The name of the message type is a special section key, which maps to the message’s verb, or to the message’s content type in the case of an envelope.</t>
<t>Each section name key in the object has a value represented in JSON as follows:</t>
<t><list style="symbols">
<t><spanx style="verb">version</spanx> : an integer identifying the mPlane protocol version used by the message.</t>
<t><spanx style="verb">registry</spanx> : a URL identifying the registry from which element names are taken.</t>
<t><spanx style="verb">label</spanx> : an arbitrary string.</t>
<t><spanx style="verb">when</spanx> : a string containing a temporal scope, as described in <xref target="temporal-scope"/>.</t>
<t><spanx style="verb">parameters</spanx> : a JSON object mapping (non-qualified) element names, either to constraints or to parameter values, as appropriate, and as described in <xref target="parameters"/>.</t>
<t><spanx style="verb">metadata</spanx> : a JSON object mapping (non-qualified) element names to metadata values.</t>
<t><spanx style="verb">results</spanx> : an array of element names.</t>
<t><spanx style="verb">resultvalues</spanx> : an array of arrays of element values in row major order, where each row array contains values in the same order as the element names in the <spanx style="verb">results</spanx> section.</t>
<t><spanx style="verb">export</spanx> : a URL for indirect export.</t>
<t><spanx style="verb">link</spanx> : a URL for message indirection.</t>
<t><spanx style="verb">token</spanx> : an arbitrary string.</t>
<t><spanx style="verb">contents</spanx> : an array of objects containing messages.</t>
</list></t>
<section anchor="textual-representations-of-element-values" title="Textual representations of element values">
<t>Each primitive type is represented as a value in JSON as follows, following the Textual Representation of IPFIX Abstract Data Types defined in <xref target="RFC7373"/>.</t>
<t>Natural and real values are represented in JSON using native JSON representation for numbers.</t>
<t>Booleans are represented by the reserved words <spanx style="verb">true</spanx> and <spanx style="verb">false</spanx>.</t>
<t>Strings and URLs are represented as JSON strings subject to JSON escaping rules.</t>
<t>Addresses are represented as dotted quads for IPv4 addresses as they would be in URLs, and canonical IPv6 textual addresses as in section 2.2 of <xref target="RFC4291"/> as updated by section 4 of <xref target="RFC5952"/>. When representing networks, addresses may be suffixed as in CIDR notation, with a ‘<spanx style="verb">/</spanx>’ character followed by the mask length in bits n, provided that the least significant 32 − n or 128 − n bits of the address are zero, for IPv4 and IPv6 respectively.</t>
<t>Timestamps are represented in <xref target="RFC3339"/> and ISO 8601, with two important differences. First, all mPlane timestamps are are expressed in terms of UTC, so time zone offsets are neither required nor supported, and are always taken to be 0. Second, fractional seconds are represented with a variable number of digits after an optional decimal point after the fraction.</t>
</section>
<section anchor="example-mplane-capabilities-and-specifications" title="Example mPlane Capabilities and Specifications">
<t>To illustrate how mPlane messages are encoded, we consider first two capabilities for a very simple application – ping – as mPlane JSON capabilities. The following capability states that the component can measure ICMP two-way delay from 192.0.2.19 to anywhere on the IPv4 Internet, with a minimum delay between individual pings of 1 second, returning aggregate statistics:</t>
<figure><artwork><![CDATA[
{
"capability": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "ping-aggregate",
"when": "now ... future / 1s",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "*"},
"results": ["delay.twoway.icmp.us.min",
"delay.twoway.icmp.us.mean",
"delay.twoway.icmp.us.50pct",
"delay.twoway.icmp.us.max",
"delay.twoway.icmp.count"]
}
]]></artwork></figure>
<t>In contrast, the following capability would return timestamped singleton delay measurements given the same parameters:</t>
<figure><artwork><![CDATA[
{
"capability": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "ping-singletons",
"when": "now ... future / 1s",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "*"},
"results": ["time",
"delay.twoway.icmp.us"]
}
]]></artwork></figure>
<t>A specification is merely a capability with filled-in parameters, e.g.:</t>
<figure><artwork><![CDATA[
{
"specification": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "ping-aggregate-three-thirtythree",
"token": "0f31c9033f8fce0c9be41d4942c276e4",
"when": "now + 30s / 1s",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "192.0.3.33"},
"results": ["delay.twoway.icmp.us.min",
"delay.twoway.icmp.us.mean",
"delay.twoway.icmp.us.50pct",
"delay.twoway.icmp.us.max",
"delay.twoway.icmp.count"]
}
]]></artwork></figure>
<t>Results are merely specifications with result values filled in and an absolute temporal scope:</t>
<figure><artwork><![CDATA[
{
"result": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "ping-aggregate-three-thirtythree",
"token": "0f31c9033f8fce0c9be41d4942c276e4",
"when": 2014-08-25 14:51:02.623 ... 2014-08-25 14:51:32.701 / 1s",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "192.0.3.33"},
"results": ["delay.twoway.icmp.us.min",
"delay.twoway.icmp.us.mean",
"delay.twoway.icmp.us.50pct",
"delay.twoway.icmp.us.max",
"delay.twoway.icmp.count"],
"resultvalues": [ [ 23901,
29833,
27619,
66002,
30] ]
}
]]></artwork></figure>
<t>More complex measurements can be modeled by mapping them back to tables with multiple rows. For example, a traceroute capability would be defined as follows:</t>
<figure><artwork><![CDATA[
{
"capability": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "traceroute",
"when": "now ... future / 1s",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "*",
"hops.ip.max": "0..32"},
"results": ["time",
"intermediate.ip4",
"hops.ip",
"delay.twoway.icmp.us"]
}
]]></artwork></figure>
<t>with a corresponding specification:</t>
<figure><artwork><![CDATA[
{
"specification": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "traceroute-three-thirtythree",
"token": "2f4123588b276470b3641297ae85376a",
"when": "now",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "192.0.3.33",
"hops.ip.max": 32},
"results": ["time",
"intermediate.ip4",
"hops.ip",
"delay.twoway.icmp.us"]
}
]]></artwork></figure>
<t>and an example result:</t>
<figure><artwork><![CDATA[
{
"result": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "traceroute-three-thirtythree",
"token": "2f4123588b276470b3641297ae85376a,
"when": "2014-08-25 14:53:11.019 ... 2014-08-25 14:53:12.765",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "192.0.3.33",
"hops.ip.max": 32},
"results": ["time",
"intermediate.ip4",
"hops.ip",
"delay.twoway.icmp.us"],
"resultvalues": [ [ "2014-08-25 14:53:11.019", "192.0.2.1",
1, 162 ],
[ "2014-08-25 14:53:11.220", "217.147.223.101",
2, 15074 ],
[ "2014-08-25 14:53:11.570", "77.109.135.193",
3, 30093 ],
[ "2014-08-25 14:53:12.091", "77.109.135.34",
4, 34979 ],
[ "2014-08-25 14:53:12.310", "192.0.3.1",
5, 36120 ],
[ "2014-08-25 14:53:12.765", "192.0.3.33",
6, 36202 ]
]
}
]]></artwork></figure>
<t>Indirect export to a repository with subsequent query requires three capabilities: one in which the repository advertises its ability to accept data over a given external protocol, one in which the probe advertises its ability to export data of the same type using that protocol, and one in which the repository advertises its ability to answer queries about the stored data. Returning to the aggregate ping measurement, first let’s consider a repository which can accept these measurements via direct POST of mPlane result messages:</t>
<figure><artwork><![CDATA[
{
"capability": "collect",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "ping-aggregate-collect",
"when": "past ... future",
"export": "mplane-https://repository.example.com:4343/result",
"parameters": {"source.ip4": "*",
"destination.ip4": "*"},
"results": ["delay.twoway.icmp.us.min",
"delay.twoway.icmp.us.mean",
"delay.twoway.icmp.us.50pct",
"delay.twoway.icmp.us.max",
"delay.twoway.icmp.count"]
}
]]></artwork></figure>
<t>This capability states that the repository at <spanx style="verb">https://repository.example.com:4343/result</spanx> will accept mPlane result messages matching the specified schema, without any limitations on time. Note that this schema matches that of the export capability provided by the probe:</t>
<figure><artwork><![CDATA[
{
"capability": "measure",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "ping-aggregate-export",
"when": "now ... future / 1s",
"export": "mplane-https",
"parameters": {"source.ip4": "192.0.2.19",
"destination.ip4": "*"},
"results": ["delay.twoway.icmp.us.min",
"delay.twoway.icmp.us.mean",
"delay.twoway.icmp.us.50pct",
"delay.twoway.icmp.us.max",
"delay.twoway.icmp.count"]
}
]]></artwork></figure>
<t>which differs only from the previous probe capability in that it states that results can be exported via the <spanx style="verb">mplane-https</spanx> protocol. Subsequent queries can be sent to the repository in response to the query capability:</t>
<figure><artwork><![CDATA[
{
"capability": "query",
"version": 0,
"registry": "http://ict-mplane.eu/registry/core",
"label": "ping-aggregate-query",
"when": "past ... future",
"link": "mplane-https://res.example.com:4343/specification",
"parameters": {"source.ip4": "*",
"destination.ip4": "*"},
"results": ["delay.twoway.icmp.us.min",
"delay.twoway.icmp.us.mean",
"delay.twoway.icmp.us.50pct",
"delay.twoway.icmp.us.max",
"delay.twoway.icmp.count"]
}
]]></artwork></figure>
</section>
</section>
<section anchor="mplane-over-https" title="mPlane over HTTPS">
<t>The default session protocol for mPlane messages is HTTP over TLS with mandatory mutual authentication. This grants confidentiality and integrity to the exchange of mPlane messages through a link security approach, and is transparent to the client. HTTP over TLS was chosen in part because of its ubiquitous implementation on many platforms.</t>
<t>An mPlane component may act either as a TLS server or a TLS client, depending on the workflow. When an mPlane client initiates a connection to a component, it acts as a TLS client, and must present a client certificate, which the component will verify against its allowable clients and map to an internal identity for making access control decisions before proceeding. The component, on the other hand, acts as a TLS server, and must present a server certificate, which the client will verify against its accepted certificates for the component before proceeding. When an mPlane component initiates a connection to a client (or, more commonly, the client interface of a supervisor), this arrangement is reversed: the component acts as a TLS client, the client as a TLS server, and mutual authentication is still mandatory. The mPlane client or component has an identity which is algorithmically derived from it’s certificate’s Distinguished Name (DN).</t>
<t>mPlane envisions a bidirectional message channel; however, unlike WebSockets and SSH described in the next subsections, HTTPS is not a bidirectional protocol. This makes it necessary to specify mappings between this bidirectional message channel and the sequence of HTTPS requests and responses for each deployment scenario. These mappings are given in <xref target="workflows-in-https"/>. Note that in a given mPlane domain, any or all of these mappings may be used simultaneously.</t>
<t>When sending mPlane messages over HTTPS, the Content-Type of the message indicates the message representation. The MIME Content-Type for mPlane messages using JSON representation over HTTPS is <spanx style="verb">application/x-mplane+json</spanx>. When sending exceptions in HTTP response bodies, the response should contain an appropriate 400 (Client Error) or 500 (Server Error) response code. When sending indirections, the response should contain an appropriate 300 (Redirection) response code. Otherwise, the response should contain response code 200 OK.</t>
<section anchor="mplane-pki-for-https" title="mPlane PKI for HTTPS">
<t>The clients and components within an mPlane domain generally share a single certificate issuer, specific to a single mPlane domain. Issuing a certificate to a client or component then grants it membership within the domain. Any client or component within the domain can then communicate with components and clients within that domain. In a domain containing a supervisor, all clients and components within the domain can connect to the supervisor. This is necessary to scale mPlane domains to large numbers of clients and components without needing to specifically configure each client and component identity at the supervisor.</t>
<t>In the case of interdomain federation, where supervisors connect to each other, each supervisor will have its own issuer. In this case, each supervisor must be configured to trust each remote domain’s issuer, but only to identify that domain’s supervisor. This compartmentalization is necessary to keep one domain from authorizing components and clients within another domain.</t>
</section>
<section anchor="access-control-in-https" title="Access Control in HTTPS">
<t>For components with simple authorization policies (e.g., many probes), the ability to establish a connection implies verification of a client certificate valid within the domain, and further implies authorization to continue with any capability offered by the component. Conversely, in component-initiated workflows (see <xref target="component-initiated"/>), the ability of a component to connect to the supervisor implies that the supervisor will trust capabilities from that component.</t>
<t>For components with more complex policies (e.g., many repositories), an identity based on the DN of the peer’s certificate is mapped to an internal identity on which access control decisions can be made. For access control purposes, the identity of an mPlane client or component is based on the Distinguished Name extracted from the certificate, which uniquely and securely identifies the entity carrying it.</t>
<t>In an mPlane domain containing a supervisor, each component trusts its supervisor completely, and accepts every message that can be identified as coming from the supervisor. Access control enforcement takes place on the supervisor, using a RBAC approach: an identity based on the DN extracted from their certificate of the clients is mapped to a role. Each role has access only to a subset of the whole set of capabilities provided by that to a supervisor, as composed from the capabilities offered by the associated components, according to its privileges. Therefore, any client will only have access to capabilities at the supervisor that it is authorized to execute. The same controls are enforced on specifications.</t>
</section>
<section anchor="paths-in-mplane-link-and-export-urls" title="Paths in mPlane Link and Export URLs">
<t>In general, when connecting to a component for the first time, a client or supervisor will have been configured with a URL from which to retrieve capabilities. Conversely, when connecting to a client or supervisor for the first time, a component will have discovered or been configured with a URL to which to post capabilities. From there, every capability retrieved by a client should have a link section to which to POST specifications, and every specification retrieved by a component should have a link section to which to POST results.</t>
<t>However, in cases in which only an address (and not a full URL) is discoverable, given the ease of differentiating message handing in many web application frameworks by URL, mPlane HTTP clients and components can use the following convention: If a client can only discover a component’s address, it should <spanx style="verb">GET /capabilities</spanx> to get that component’s capabilities. If a client posts a specification for a capability that does not contain a link to a component, and only has that component’s address, it should <spanx style="verb">POST</spanx> the specification to <spanx style="verb">/specification</spanx>. If a component wants to return results to a client and only has the client’s address, and the corresponding specification does not have a link, it should <spanx style="verb">POST</spanx> the result to <spanx style="verb">/result</spanx>.</t>
<t>Additional path information can also be used in link and export section URLs to convey an implicit authorization from one component to another via a supervisor. Consider a repository which only wants to accept data from probes which a trusted supervisor has told to export to it. While the probes and repository share a domain by certificate issuer, the repository can further restrict access by placing a cryptographically random token in the export URL in the capability it gives to the supervisor e.g.</t>
<t><spanx style="verb">mplane-https://repository.example.com:4343/4e749ecb647c44d8dd6be3fe0986de03bebe/result</spanx>.</t>
<t>In this case, only components explicitly delegated by the supervisor can export to the repository. The same pattern can be used to delegate posting of specifications and results securely.</t>
</section>
</section>
<section anchor="mplane-over-websockets-over-tls" title="mPlane over WebSockets over TLS">
<t>Though not presently implemented by the SDK, the mPlane protocol specification is designed such that it can also use the WebSockets protocol as specified in <xref target="RFC6455"/> as a session layer. Once an WebSockets connection is established, mPlane messages can be exchanged bidirectionally over the channel. A client may establish a connection to a component, or a component to a client, as required for a given application.</t>
<t>Access control in WebSockets is performed as in the HTTPS case: both clients and components are identified by certificates, identities derived from certificate DN, and domain membership is defined by certificate issuer.</t>
<t>Implementation and further specification of WebSockets as a session layer is a matter for future work. Though WebSockets is a better fit for the bidirectional nature of the mPlane protocol than HTTPS, the latter was chosen as mandatory to implement given the ubiquity of interoperable implementations of it for a diverse set of platforms. We suspect the situation with WebSockets will improve as implementations mature.</t>
</section>
<section anchor="mplane-over-ssh" title="mPlane over SSH">
<t>Though not presently implemented by the SDK, the mPlane protocol specification is designed such that it can also use the Secure Shell (SSH) protocol as a session layer. In the SSH binding, a connection initiator (SSH client) identifies itself with an RSA, DSA, or ECDSA public key, which is bound to a specific identity, and the connection responder (SSH server) identifies itself with a host public key. Once an SSH connection is established, mPlane messages can be exchanged bidirectionally over the channel.</t>
<t>When using SSH as a session layer, clients and components are identified by SSH keys. SSH keys are not very human-readable identifiers, and as such must be mapped to identifiers at each component, client, and supervisor, on which roles can be assigned and access control decisions made. Additionally, SSH keys are not signed by an issuer, so there is no PKI-based definition of membership within a domain as with HTTPS. The need to specifically manage keys for every client and component, and the mappings to identities used in RBAC, will tend to limit the use of SSH to small domains.</t>
<t>Implementation and further specification of SSH as a session layer is a matter for future work. SSH was originally chosen as a possible session protocol for small domains, in order to save the overhead of building a PKI; however, implementation experience has shown that managing SSH keys manually has little administrative overhead advantage over using a small PKI with an algorithmic mapping from subject distinguished names to access control identities.</t>
</section>
</section>
<section anchor="workflows-in-https" title="Workflows in HTTPS">
<t>As noted above, mPlane protocol supports three patterns of workflow: client-initiated, component-initiated, and indirect export. These workflow patterns can be combined into complex interactions among clients and components in an mPlane infrastructure. In the subsections below, we illustrate these workflows as they operate over HTTPS. Operation over WebSockets or SSH is much simpler: since the session protocol in these cases provides a bidirectional channel for message exchange, so the message sender and message exchange initiator are independent from the connection initiator, and callback control and capability discovery as described here are unnecessary.</t>
<section anchor="client-initiated" title="Client-Initiated">
<t>Client-initiated workflows are appropriate for stationary components, i.e., those with stable, routable addresses, which can therefore act as HTTPS servers. This is generally the case for supervisors, large repositories, repositories acting as gateways to external data sources, and certain large-scale or public probes.</t>
<t>Here, the client opens an HTTPS connection the the component, and GETs a capability message, or an envelope containing capability messages, at a known URL. It then subsequently uses these capabilities by POSTing a specification, either to a known URL or to the URL given in the <spanx style="verb">link</spanx> section of the capability. The HTTP response to the POSTed specification contains either a result directly, or contains a receipt which can be redeemed later by POSTing a redemption to the component.</t>
<t>In a client-initiated workflow with a delayed result, the client is responsible for polling the component with a redemption at the appropriate time. For measurements (i.e. specifications with the verb ‘<spanx style="verb">measure</spanx>’), this time is known as it is defined by the end of the temporal scope for the specification.</t>
<t>Note that in client-initiated workflows, clients may store capabilities from components for later use: there may be a significant delay between retrieval of capabilities and transmission of specifications following from those capabilities. It is not necessary for a client to check to see whether a given capability it has previously retrieved is still valid before sending a specification.</t>
<section anchor="capability-discovery" title="Capability Discovery">
<t>For direct client-initiated workflows, the URL(s) from which to GET capabilities is a client configuration parameter. The client-initiated workflow also allows indirection in capability discovery. Instead of GETting capabilities direct from a component, they can also be retrieved from a capability discovery server containing capabilities for multiple components providing capabilities via client-initiated workflows. These components are then identified by the <spanx style="verb">link</spanx> section of each capability. The capabilities may be grouped in an envelope retrieved from the capability discovery server, or linked to in an HTML object retrieved therefrom.</t>
<t>In this way, a client needs only be configured with a single URL for capability discovery, instead of URLs for each component with which it wants to communicate.</t>
</section>
</section>
<section anchor="component-initiated" title="Component-Initiated">
<t>Component-initiated workflows are appropriate for components which do not have stable routable addresses (i.e., are behind NATs and/or are mobile), and which are used by clients that do. Common examples of such components are lightweight probes on mobile devices and customer equipment on access networks, interacting directly with a supervisor.</t>
<t>In this case, the usual client-server relationship is reversed. When the component becomes available, it opens an HTTPS connection to the client and POSTs its capabilities to a known, configured URL at the supervisor. The supervisor remembers which capabilities it wishes to use on which components, and prepares specifications for later retrieval by the client.</t>
<t>The component then polls the supervisor, opening HTTPS connections and attempting to GET a specification from a known URL. The client will either respond 404 Not Found if the client has no current specification for the component, or with a specification to run matching a previously POSTed capability. After completing the measurement specified, the component then calls back and POSTs the results to the supervisor at a known URL.</t>
<t>In this case, the component must be configured with the client’s URL(s).</t>
<section anchor="callback-control" title="Callback Control">
<t>Callback control allows the supervisor to specify to the component when it should call back, in order to allow centralized scheduling of component-initiated workflows, as well as to allow an mPlane infrastructure using component-initiated workflows to scale. Continuous polling of a client by thousands of components would put a network under significant load, and the polling delay introduces a difficult tradeoff between timeliness of specification and polling load. mPlane uses the <spanx style="verb">callback</spanx> verb with component-initiated workflows in order to allow the supervisor fine-grained control over when components will call back.</t>
<t>To use callback control, the component advertises the following capability along with the others it provides:</t>
<figure><artwork><![CDATA[
{
'capability': 'callback',
'version': 0,
'registry': 'http://ict-mplane.eu/registry/core',
'when': 'now ... future',
'parameters': {},
'results': []
}
]]></artwork></figure>
<t>Then, when the component polls the client the first time, it responds with an envelope containing two specifications: the measurement it wants the client to perform, and a callback specification, containing the time at which the client should poll again in the temporal scope; e.g. as follows:</t>
<figure><artwork><![CDATA[
{
'specification': 'callback',
'version': 0,
'registry': 'http://ict-mplane.eu/registry/core',
'when': '2014-09-08 12:40:00.000',
'parameters': {},
'results': []
}
]]></artwork></figure>
<t>Note that if the supervisor has no work for the component, it returns a single callback specification as opposed to returning 404. Note that subsequent callback control specification to a component can have different time intervals, allowing a supervisor fine-grained control on a per-component basis of the tradeoff between polling load and response time.</t>
<t>Components implementing component-initiated workflows should support callback control in order to ensure the scalability of large mPlane infrastructures.</t>
</section>
</section>
<section anchor="indirect-export" title="Indirect Export">
<t>Many common measurement infrastructures involve a large number of probes exporting large volumes of data to a (much) smaller number of repositories, where data is reduced and analyzed. Since (1) the mPlane protocol is not particularly well-suited to the bulk transfer of data and (2) fidelity is better ensured when minimizing translations between representations, the channel between the probes and the repositories is in this case external to mPlane. This indirect export channel runs either a standard export protocol such as IPFIX, or a proprietary protocol unique to the probe/repository pair. It coordinates an exporter which will produce and export data with a collector which will receive it. All that is necessary is that (1) the client, exporter, and collector agree on a schema to define the data to be transferred and (2) the exporter and collector share a common protocol for export.</t>
<t>Here, we consider a client speaking to an exporter and a collector. The client first receives an export capability from the exporter (with verb <spanx style="verb">measure</spanx> and with a protocol identified in the <spanx style="verb">export</spanx> section) and a collection capability from the collector (with the verb <spanx style="verb">collect</spanx> and with a URL in the <spanx style="verb">export</spanx> section describing where the exporter should export), either via a client-initiated workflow or a capability discovery server. The client then sends a specification to the exporter, which matches the schema and parameter constraints of both the export and collection capabilities, with the collector’s URL in the <spanx style="verb">export</spanx> section.</t>
<t>The exporter initiates export to the collector using the specified protocol, and replies with a receipt that can be used to interrupt the export, should it have an indefinite temporal scope. In the meantime, it sends data matching the capability’s schema directly to the collector.</t>
<t>This data, or data derived from the analysis thereof, can then be subsequently retrieved by a client using a client-initiated workflow to the collector.</t>
</section>
<section anchor="error-handling-in-mplane-workflows" title="Error Handling in mPlane Workflows">
<t>Any component may signal an error to its client or supervisor at any time by
sending an exception message. While the taxonomy of error messages is at
this time left up to each individual component, given the weakly imperative
nature of the mPlane protocol, exceptions should be used
sparingly, and only to notify components and clients of errors with the
mPlane infrastructure itself.</t>
<t>It is generally presumed that diagnostic information about errors which may
require external human intervention to correct will be logged at each
component; the mPlane exception facility is not intended as a replacement
for logging facilities (such as syslog).</t>
<t>Specifically, components in component-initiated workflows
should not use the exception mechanism for common error conditions (e.g.,
device losing connectivity for small network-edge probes) – specifications
sent to such components are expected to be best-effort. Exceptions should
also not be returned for specifications which would normally not be delayed
but are due to high load – receipts should be used in this case, instead.
Likewise, specifications which cannot be fulfilled because they request the
use of capabilities that were once available but are no longer should be
answered with withdrawals.</t>
<t>Exceptions should always be sent in reply to messages sent to
components or clients which cannot be handled due to a syntactic or semantic
error in the message itself.</t>
</section>
</section>
<section anchor="the-role-of-the-supervisor" title="The Role of the Supervisor">
<t>For simple infrastructures, a set of components may be controlled directly by a client. However, in more complex infrastructures providing support for multiple clients, a supervisor can mediate between clients and components. From the point of view of the mPlane protocol, a supervisor is merely a combined component and client. The logic binding client and component interfaces within the supervisor is application-specific, as it involves the following operations according to the semantics of each application:</t>
<t><list style="symbols">
<t>translating lower-level capabilities from subordinate components into higher-level (composed) capabilities, according to the application’s semantics</t>
<t>translating higher-level specifications from subordinate components into lower-level (decomposed) specifications</t>
<t>relaying or aggregating results from subordinate components to supervisor clients</t>
</list></t>
<t>The workflows on each side of the supervisor are independent; indeed, the supervisor itself will generally respond to client-initiated exchanges, and use both component-initiated and supervisor-initiated exchanges with subordinate components.</t>
<t>Supervisors can of course be nested in this arrangement, e.g. allowing high-level measurements to be aggregated from a set of subdomains, or federation of measurement across administrative domain boundaries.</t>
<t>In the general case, the component first registers with the supervisor, POSTing its capabilities. The supervisor creates composed capabilities derived from these component capabilities, and makes them available to its client, which GETs them when it connects.</t>
<t>The client then initiates a measurement by POSTing a specification to the supervisor, which decomposes it into a more-specific specification to pass to the component, and hands the client a receipt for a the measurement. When the component polls the supervisor – controlled, perhaps, by callback control as described above – the supervisor passes this derived specification to the component, which executes it and POSTs its results back to the supervisor. When the client redeems its receipt, the supervisor returns results composed from those received from the component.</t>
<t>This simple example illustrates the three main responsibilities of the supervisor, which are described in more detail below.</t>
<section anchor="component-registration" title="Component Registration">
<t>In order to be able to use components to perform measurements, the supervisor must register the components associated with it. For client-initiated workflows – large repositories and the address of the components is often a configuration parameter of the supervisor. Capabilities describing the available measurements and queries at large-scale components can even be part of the supervisor’s externally managed static configuration, or can be dynamically retrieved and updated from the components or from a capability discovery server.</t>
<t>For component-initiated workflows, components connect to the supervisor and POST capabilities and withdrawals, which requires the supervisor to maintain a set of capabilities associated with a set of components currently part of the mPlane infrastructure it supervises.</t>
</section>
<section anchor="client-authentication" title="Client Authentication">
<t>For many components – probes and simple repositories – very simple authentication often suffices, such that any client with a certificate with an issuer recognized as valid is acceptable, and all capabilities are available to. Larger repositories often need finer grained control, mapping specific peer certificates to identities internal to the repository’s access control system (e.g. database users).</t>
<t>In an mPlane infrastructure, it is therefore the supervisor’s responsability to map client identities to the set of capabilities each client is authorized to access. This mapping is part of the supervisor’s configuration.</t>
</section>
<section anchor="capability-composition-and-specification-decomposition" title="Capability Composition and Specification Decomposition">
<t>The most dominant responsibility of the supervisor is composing capabilities from its subordinate components into aggregate capabilities, and decomposing specifications from clients to more-specific specifications to pass to each component. This operation is always application-specific, as the semantics of the composition and decomposition operations depend on the capabilities available from the components, the granularity of the capabilities to be provided to the clients. It is for this reason that the mPlane SDK does not provide a generic supervisor.</t>
</section>
</section>
<section anchor="security-considerations" title="Security Considerations">
<t>The mPlane protocol allows the control of network measurement devices. The
protocol itself uses HTTPS as a session layer, and is therefore secured using
TLS. TLS mutual authentication must be used for the exchange of mPlane
messages, as access control decisions about which clients and components are
trusted for which capabilities take identity information from the certificates
TLS clients and servers use to identify themselves. Current operational best
security practices for the deployment of TLS-secured protocols must be
followed for the deployment of mPlane.</t>
<t>Indirect export, as a design feature, presents a potential for information
leakage, as indirectly exported data is necessarily related to measurement
data and control transported with the mPlane protocol. Though out of scope for
this document, indirect export protocols used within an mPlane domain must be
secured at least as well as the mPlane protocol itself.</t>
</section>
<section anchor="iana-considerations" title="IANA Considerations">
<t>This document has no actions for IANA.</t>
</section>
<section anchor="contributors" title="Contributors">
<t>This document is based on Deliverable 1.4, the architecture and protocol
specification document produced by the mPlane project <xref target="D14"/>, which is the
work of the mPlane consortium, specifically B. Trammell, M. Kuehlewind, M.
Mellia, A. Finamore, S. Pentassuglia, G. De Rosa, F. Invernizzi, M. Milanesio,
D. Rossi, S. Niccolini, I. Leontiadis, T. Szemethy, B. Szabo, R. Winter, M.
Faath, B. Donnet, and D. Papadimitriou. This work is supported by the European Commission under grant agreement FP7-318627 mPlane. Support does not imply endorsement.</t>
</section>
</middle>
<back>
<references title='Informative References'>
&RFC3205;
&RFC3339;
&RFC4291;
&RFC5246;
&RFC5905;
&RFC5952;
&RFC6455;
&RFC7011;
&RFC7159;
&RFC7230;
&RFC7373;
<reference anchor="D14" target="https://www.ict-mplane.eu/sites/default/files//public/public-page/public-deliverables//1095mplane-d14.pdf">
<front>
<title>mPlane Architecture Specification</title>
<author initials="B." surname="Trammell" fullname="Brian Trammell">
<organization></organization>
</author>
<date year="2015" month="April" day="15"/>
</front>
</reference>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 05:55:12 |